claude-dev-env 2.14.0 → 2.15.0

package/AGENTS.md

@@ -1,61 +1,135 @@
-# Development Assistant
+# Scope
 
-## Communication
+  Every rule in this file governs all text everywhere: chat replies, tool-call sentences, plans, questions you ask, code, code comments, test names, commit subjects, pull request and issue bodies, documentation, and every file you write. No rule stops at the edge of a chat message.
 
-Reply shape and length: follow `~/.claude/rules/eli11-replies.md`. Word choice: follow `~/.claude/rules/plain-language.md`. Progress and finals: follow `~/.claude/rules/opus5-communication-contract.md` (`opus5-communication-contract-v1`). State claims affirmatively.
+  A rule that names a form in order to forbid it passes its own check, and so does a two-column table that teaches a rewrite.
 
-## Security
+Ask when ambiguity materially changes scope or implementation. Collect credentials through secure UI only; never request secrets in chat.
 
-Collect credentials through secure UI only; never request secrets in chat.
+## Documentation
 
-A runtime value that is itself private — a host, an SSH user or port, an owner scope, an account ID — lives in git-ignored local configuration with a committed placeholder in its place. Source files never carry the real value.
+Describe only the current system state. Keep documentation self-contained and free of historical, transitional, conversational, or version-transition language. Never use negative prose or antipatterns. Always state what to do, specifically.
+Code and tests
 
-## Advisors
+Tests must exercise real behavior, real data, and production paths. Test theater is forbidden.
 
-| Path | Holds |
-|---|---|
-| `~/.claude/docs/references/advisor-tool.md` | When to call a stronger reviewer, hard rule before first write, how to treat advice |
-| `/team-advisor` skill | Standing warm advisor bind (map: `docs/references/team-advisor-skill.md`) |
-| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, lifecycle |
+For multi-step code tasks:
 
-Use `/team-advisor` under the rules in `advisor-tool.md` for every advisor consultation.
+Coders consult a warm session-advisor when blocked (Sol xHigh).
+Repair reported findings when that review mode is selected.
 
-## Files and workspaces
+Research and delegation
+Delegate fact extraction when multiple files or search patterns are required. Request precise file-and-line answers.
 
-Put all work in an isolated worktree under the repo's `.claude/worktrees/`.
+Use warm & reusable parallel luna (you decide effort level per task) fast subagents for unrelated questions; threaded & named appropriately.
 
-Default to Edit for existing files; reach for Write only when the path is genuinely new.
+Read or search directly only in files you will modify via es.exe.
 
-## Code and tests
+For code navigation, prefer es.exe, then content search or globbing.
 
-Tests must exercise real behavior, real data, and production paths.
+Scope every es.exe search.
 
-Keep changes within scope. Prefer durable systemic fixes for reusable behavior.
+Never scan an entire drive or network share.
 
-Do not rewrite entire files or rename public parameters without need.
+Task tracking
+Track every task using `update_plan`.
 
-## Reviews
+## Definitions
+Warm agent: Any agent who has acted within the past 30 minutes.
+
+  # Response and working style
+
+  Mid-run and closing narration follow `rules/opus5-communication-contract.md` (`opus5-communication-contract-v1`): first progress update is one sentence; later updates only for important discoveries or direction changes; the final starts with the outcome.
+
+  Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.
+
+  # Word budget
+
+  Say it in the fewest words that stay accurate and complete. Before sending, cut every sentence that does not change what the reader thinks or does.
+
+  Cut these on sight:
+
+  - Deliberation. State the decision, not the reasoning that reached it, unless the reader has to weigh it themselves.
+  - Why you did not do something. Say what you did; add the reason only if the reader must decide whether to do it.
+  - Incidental findings from your own process. Report one only when the reader must act on it, and give it one line.
+  - Any sentence that restates a fact already stated in a heading, a list, or an earlier line.
+
+  When you have more than two facts of the same kind, use a list or a table. Prose paragraphs hide facts; rows expose them.
+
+  # No contrast framing
+
+  Write the claim. Never prop it up against what it is not.
 
-Verify every sub-agent file list, count, description, and finding against the repository and diff.
+  The banned shape is a claim paired with a rejected alternative, in any wording:
 
-Do not commit untracked files unless explicitly instructed.
+  | Banned | Write instead |
+  |---|---|
+  | Verified against the remote, not just locally | Verified against the remote |
+  | This is a design flaw, not a typo | This is a design flaw |
+  | Not a copy of the shared script, but an ad |
+  | Rather than patching the caller, the fix moves into the helper | The fix moves into the helper |
+  | Instead of three passes, it runs one | It runs one pass |
+  | It is not only faster; it is correct | It is correct and faster |
+  | This is less a bug than a missing feature
+  | Let me read the log rather than guessing | Reading the log. |
+  | I'll patch the helper instead of the caller | Patching the helper. |
 
-## Package communication contract
+  Every wording of the shape is banned, including `X, not Y`, `not Y but X`, `rather than Y, X`, `instead of Y, X`, `X over Y`, `not just X — Y`, `less X than Y`, and a negated sentence followed by its po
+  ──── (152 lines hidden) ─────────────────────────────────────────────────────────────────────────────────────────────
+  the name.
 
-Use `opus5-communication-contract-v1` for package communication.
+  | Written on the day | Named for the subject |
+  |---|---|
+  | `august_cert_failures.py` | `cert_rejections.py` |
+  | `fix_august_bug()` | `normalize_calendar_color()` |
+  | `AUGUST_REJECTION_CODES` | `REJECTION_CODE
+  | `test_august_failures` | `test_rejects_wrong_calendar_color` |
+  | `jira4821_validator.py` | `manifest_validator.py` |
+  | `q3_migration/` | `add_tenant_id_column/` |
+  | `v2_client.py` | `retrying_client.py` |
+  | `legacy_export.py` | `csv_export.py` |
+  | `temp_fix.py` | `unicode_path_workaround.p
+  | "Fix August cert failures" | "Fix calendar color mismatch in cert export" |
 
-## Delegation
+  A branch name is a name. It carries no date,ither. Someone reads it to decide whether to check the branch out, so it has to say what the work does.
 
-Request precise file-and-line answers from research subagents.
+  | Written on the day | Named for the subject |
+  |---|---|
+  | `fix/cert-2026-08-b3-calendar-widget-color` | `fix-calendar-widget-color` |
+  | `parse-rejection-emails-cert-2026-08-b3` |
 
-## Task tracking
+  One prefix spreads. Once `august_` sits in one name, the next name matches it for consistency, and within a week the month reads as a real domain concept that forty places depend on. Rename it the hour you notice it.
 
-Track multi-step work with the `task-build` skill.
+  # Change size
 
-## Repository rule
+  When planning work or opening a pull request, size the change first: one self-contained change, around 100 lines, with its tests. Read the small-changelists guide for the numbers, the allowed exceptions, and how to split.
 
-Before changing skill, rule, or hook installation in the claude-dev-env repo, read `docs/references/skill-install-system.md`.
+## Execution and delegation
+
+Delegate all task work to Tier 3 agents.
+
+Draft a separate assignment for each agent. Each assignment must be clear, concise, tightly scoped, independently executable, and explicit about ownership, constraints, deliverables, and verification.
+
+Run independent assignments in parallel. Keep overlapping work sequential. The primary agent coordinates agents, resolves dependencies, verifies results, and reports outcomes.
 
 ## Definitions
 
-Warm agent: active within the past 59 minutes.
+Tier 3 agent: A strong execution specialist that independently completes a bounded assignment, follows repository contracts, repairs routine failures, tests production behavior, and escalates decisions that materially affect architecture or scope.
+
+Warm agent: An agent that has acted within the past 30 minutes. Reuse warm agents for related follow-up work.
+
+  # Corrections
+
+  Only correct an earlier statement when the ecode, conclusions, or decisions. Statecorrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.
+
+  # Tool calls and output hygiene
+
+  When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so. Do not include internal or system XML tags in your response.
+
+  # Code review
+
+  When reviewing code, report everything you find. Filtering belongs in a separate pass.
+
+  <tone_preference>
+  Keep outputs reasonably concise.
+  </tone_preference>

package/agents/AGENTS.md

@@ -6,13 +6,8 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 
 | File | Agent name | Role |
 |---|---|---|
-| `caveman.md` | Caveman Agent | Terse voice and smallest-possible artifacts; questions premise before building |
-| `clasp-deployment-orchestrator.md` | Clasp Deployment Orchestrator | Creates and deploys Google Apps Script projects with multiple files |
 | `clean-coder.md` | Clean Coder | Primary code-writing agent; links the review contract, CODE_RULES, and enforcer; task-local discovery and gate-clean first writes |
-| `code-advisor.md` | Code Advisor | Single-executor mid-run advisor (PLAN/CORRECTION/STOP as final text); distinct from session-advisor |
 | `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
-| `deep-research.md` | Deep Research | Citation-grounded research with web search |
-| `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
 | `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |

package/agents/test_agent_frontmatter.py

@@ -42,8 +42,8 @@ non-empty string, and a `name` equal to its file stem — a mapping that loads
 but binds `description` to nothing, or names an agent the file does not,
 registers a subagent the caller cannot spawn::
 
-    ok:   docs-agent.md  -> name: docs-agent
-    flag: docs-agent.md  -> name: doc-manager   <- wrong spawn id
+    ok:   clean-coder.md  -> name: clean-coder
+    flag: clean-coder.md  -> name: doc-manager   <- wrong spawn id
     flag: description:                          <- loads as None, loader needs text
 
 Every check above is parametrized over the definitions that yield a
@@ -52,8 +52,8 @@ and leave the suite green while unreadable. The block is what the fence lines
 delimit, so the file that opens no fence or never closes one is exactly the
 broken file these checks exist to catch::
 
-    ok:   docs-agent.md  -> ---  name/description  ---   <- block found
-    flag: docs-agent.md  -> ---  name/description        <- no closing fence,
+    ok:   clean-coder.md  -> ---  name/description  ---   <- block found
+    flag: clean-coder.md  -> ---  name/description        <- no closing fence,
                                                             silently uncovered
 
 `test_every_agent_definition_yields_a_frontmatter_block` holds that floor: it
@@ -218,8 +218,8 @@ def _agent_name_problem(parsed_frontmatter: object, expected_name: str) -> str |
     A subagent registers under the name in its frontmatter, so a name that is
     not the file stem is spawned by an id no caller uses::
 
-        docs-agent.md -> name: docs-agent   -> ok:   None
-        docs-agent.md -> name: doc-manager  -> flag: wrong spawn id
+        clean-coder.md -> name: clean-coder   -> ok:   None
+        clean-coder.md -> name: doc-manager  -> flag: wrong spawn id
 
     Args:
         parsed_frontmatter: Value `yaml.safe_load` produced for the block.
@@ -289,7 +289,7 @@ def test_agent_frontmatter_loads_as_a_yaml_mapping(
 @pytest.mark.parametrize(
     "agent_file_name",
     (
-        "docs-agent.md",
+        "clean-coder.md",
         "issue-tracker.md",
         "skill-writer-agent.md",
     ),

package/bin/AGENTS.md

@@ -1,20 +1,22 @@
 # bin
 
-The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, and writes `~/.mypy.ini` under the process home.
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, writes `~/.mypy.ini` under the process home, and copies Codex exec-policy files into `~/.codex/rules` (`CODEX_HOME/rules` when that variable is set), and generates Cursor `.mdc` files into `~/.cursor/rules` from the installed Claude rules.
 
 ## Files
 
 | File | Purpose |
 |---|---|
 | `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
-| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` |
+| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` plus files under the Codex rules directory and the Cursor home |
 | `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
 | `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
 | `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
 | `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
 | `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
 | `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
-| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes (also imported by `resolve-install-root.mjs`) |
+| `install.codex-rules.test.mjs` | Tests that Codex exec-policy files copy to `~/.codex/rules`, honor `CODEX_HOME`, skip `--only journal`, and uninstall without touching `default.rules` |
+| `install.cursor-rules.test.mjs` | Tests that Cursor `.mdc` files generate into `~/.cursor/rules` from Claude rules, skip `--only journal`, and leave a local extra `.mdc` in place |
+| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes, plus the Codex home and rules directory names `resolve-install-root.mjs` uses |
 | `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
@@ -78,7 +80,7 @@ A run that moves nothing sweeps nothing, so every recovery point the user holds
 
 `--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
 
-Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
+Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory, or it sits under the Codex rules directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
 
 The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
 

package/bin/install-constants.mjs

@@ -85,3 +85,54 @@ export const SETTINGS_FILE_NAME = 'settings.json';
  * removes the file the install created.
  */
 export const MYPY_INI_FILE_NAME = '.mypy.ini';
+
+/**
+ * Environment variable Codex uses for its config home. When unset, Codex reads
+ * `~/.codex`. The installer copies shipped exec-policy files into
+ * `<that home>/rules`.
+ */
+export const CODEX_HOME_ENVIRONMENT_VARIABLE = 'CODEX_HOME';
+
+/**
+ * Directory name Codex uses under the user home when `CODEX_HOME` is unset.
+ */
+export const DEFAULT_CODEX_DIRECTORY_NAME = '.codex';
+
+/**
+ * Directory name under the Codex home that holds `*.rules` exec-policy files.
+ * Codex loads every file in that directory; see `load_exec_policy` in Codex.
+ */
+export const CODEX_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Package subdirectory that holds the shipped Codex exec-policy files. The
+ * installer copies this tree into the Codex rules directory, not into
+ * `~/.claude/`.
+ */
+export const CODEX_RULES_PACKAGE_DIRECTORY_NAME = 'codex-rules';
+
+/**
+ * Shipped exec-policy file name. A distinct name keeps a local `default.rules`
+ * file in place.
+ */
+export const CODEX_RULES_SHIPPED_FILE_NAME = 'claude-dev-env.rules';
+
+/**
+ * Directory name Cursor uses under the user home for editor config.
+ */
+export const DEFAULT_CURSOR_DIRECTORY_NAME = '.cursor';
+
+/**
+ * Directory name under the Cursor home that holds generated `.mdc` rule files.
+ */
+export const CURSOR_RULES_DIRECTORY_NAME = 'rules';
+
+/**
+ * Installed script that writes Cursor `.mdc` files from Claude rules.
+ */
+export const CURSOR_SYNC_SCRIPT_FILE_NAME = 'sync_to_cursor.py';
+
+/**
+ * Windows Python launcher command the installer may bake into hook settings.
+ */
+export const WINDOWS_PYTHON_LAUNCHER_COMMAND = 'py -3';

package/bin/install.codex-rules.test.mjs

@@ -0,0 +1,173 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    readFileSync,
+    existsSync,
+    rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_RULES_DIRECTORY_NAME,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+    DEFAULT_CODEX_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { CONTENT_DIRECTORIES, INSTALL_GROUPS } from './install.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const SHIPPED_RULES_SOURCE_PATH = join(
+    PACKAGE_DIRECTORY,
+    CODEX_RULES_PACKAGE_DIRECTORY_NAME,
+    CODEX_RULES_SHIPPED_FILE_NAME,
+);
+
+function runInstaller(homeDirectory, extraArguments) {
+    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_ENVIRONMENT_VARIABLE]: join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME),
+        },
+    });
+}
+
+test('CONTENT_DIRECTORIES omits codex-rules because that tree installs to the Codex home', () => {
+    assert.equal(CONTENT_DIRECTORIES.includes(CODEX_RULES_PACKAGE_DIRECTORY_NAME), false);
+});
+
+test('the core group installs Codex exec-policy files', () => {
+    assert.equal(INSTALL_GROUPS.core.includeCodexRules, true);
+});
+
+test('resolveInstallRoot names ~/.codex/rules and allows files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(homeDirectory, DEFAULT_CODEX_DIRECTORY_NAME, CODEX_RULES_DIRECTORY_NAME);
+    assert.equal(resolution.codexRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, CODEX_RULES_SHIPPED_FILE_NAME), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('CODEX_HOME relocates the Codex rules destination', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-codex-home-default');
+    const relocatedHome = join(tmpdir(), 'cdev-codex-home-relocated');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: { [CODEX_HOME_ENVIRONMENT_VARIABLE]: relocatedHome },
+        explicitTarget: null,
+    });
+    assert.equal(
+        resolution.codexRulesInstallDirectory,
+        join(relocatedHome, CODEX_RULES_DIRECTORY_NAME),
+    );
+});
+
+test('a full install copies shipped Codex rules and leaves a local default.rules in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-install-'));
+    try {
+        const userRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            'default.rules',
+        );
+        mkdirSync(dirname(userRulesPath), { recursive: true });
+        writeFileSync(userRulesPath, 'prefix_rule(pattern=["echo", "hi"], decision="allow")\n');
+
+        runInstaller(homeDirectory, []);
+
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        assert.equal(existsSync(installedRulesPath), true);
+        assert.equal(
+            readFileSync(installedRulesPath, 'utf8'),
+            readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8'),
+        );
+        assert.equal(
+            readFileSync(userRulesPath, 'utf8'),
+            'prefix_rule(pattern=["echo", "hi"], decision="allow")\n',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full install Codex rules file contains no personal home path', () => {
+    const shippedText = readFileSync(SHIPPED_RULES_SOURCE_PATH, 'utf8');
+    assert.equal(shippedText.includes('Users\\jon'), false);
+    assert.equal(shippedText.includes('Users/jon'), false);
+    assert.equal(shippedText.includes('JonEcho'), false);
+});
+
+test('--only journal skips Codex rules; --only core copies them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-groups-'));
+    try {
+        const installedRulesPath = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+            CODEX_RULES_SHIPPED_FILE_NAME,
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(installedRulesPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(installedRulesPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('uninstall removes the shipped Codex rules file and leaves default.rules', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-codex-uninstall-'));
+    try {
+        const rulesDirectory = join(
+            homeDirectory,
+            DEFAULT_CODEX_DIRECTORY_NAME,
+            CODEX_RULES_DIRECTORY_NAME,
+        );
+        const userRulesPath = join(rulesDirectory, 'default.rules');
+        mkdirSync(rulesDirectory, { recursive: true });
+        writeFileSync(userRulesPath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+        runInstaller(homeDirectory, ['--uninstall']);
+
+        const installedRulesPath = join(rulesDirectory, CODEX_RULES_SHIPPED_FILE_NAME);
+        assert.equal(existsSync(installedRulesPath), false);
+        assert.equal(readFileSync(userRulesPath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.cursor-rules.test.mjs

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+    resolveInstallRoot,
+    isAllowedInstallDestination,
+} from './resolve-install-root.mjs';
+import {
+    DEFAULT_CURSOR_DIRECTORY_NAME,
+    CURSOR_RULES_DIRECTORY_NAME,
+} from './install-constants.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        },
+    });
+}
+
+test('resolveInstallRoot names ~/.cursor/rules and allows generated mdc files under it', () => {
+    const homeDirectory = join(tmpdir(), 'cdev-cursor-rules-home');
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment: {},
+        explicitTarget: null,
+    });
+    const expectedDirectory = join(
+        homeDirectory,
+        DEFAULT_CURSOR_DIRECTORY_NAME,
+        CURSOR_RULES_DIRECTORY_NAME,
+    );
+    assert.equal(resolution.cursorRulesInstallDirectory, expectedDirectory);
+    assert.equal(
+        isAllowedInstallDestination(join(expectedDirectory, 'plain-language.mdc'), resolution),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(join(homeDirectory, '.ssh', 'id_rsa'), resolution),
+        false,
+    );
+});
+
+test('a full install writes stem-named Cursor rules and leaves a local extra mdc in place', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-install-'));
+    try {
+        const extraRulePath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'user-local.mdc',
+        );
+        mkdirSync(dirname(extraRulePath), { recursive: true });
+        writeFileSync(extraRulePath, 'keep-me\n');
+
+        runInstaller(homeDirectory, []);
+
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        assert.equal(existsSync(generatedPath), true);
+        const generatedText = readFileSync(generatedPath, 'utf8');
+        assert.equal(generatedText.includes('alwaysApply: true'), true);
+        assert.equal(readFileSync(extraRulePath, 'utf8'), 'keep-me\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('--only journal skips Cursor rule generation; --only core writes them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-groups-'));
+    try {
+        const generatedPath = join(
+            homeDirectory,
+            DEFAULT_CURSOR_DIRECTORY_NAME,
+            CURSOR_RULES_DIRECTORY_NAME,
+            'plain-language.mdc',
+        );
+        runInstaller(homeDirectory, ['--only', 'journal']);
+        assert.equal(existsSync(generatedPath), false);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        assert.equal(existsSync(generatedPath), true);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});