claude-dev-env 2.15.1 → 2.17.0

package/.agents/skills/review-tier/scripts/test_generation.py

@@ -0,0 +1,171 @@
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from review_tier import build_generation, inventory_generation, router_state_directory, router_state_root, router_state_root_id
+
+
+def test_generation_uses_live_git_surface(tmp_path: Path) -> None:
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=tmp_path, check=True)
+    (tmp_path / "tracked.py").write_text("x = 1\n", encoding="utf-8")
+    subprocess.run(["git", "add", "tracked.py"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "-c", "user.name=Test", "-c", "user.email=test@example.com", "commit", "-qm", "init"], cwd=tmp_path, check=True)
+    (tmp_path / "untracked.py").write_text("y = 2\n", encoding="utf-8")
+    inventory = inventory_generation(tmp_path)
+    assert "untracked.py" in inventory["untracked"]
+    card = build_generation(tmp_path, card_path=tmp_path / "card.json")
+    assert card["inventory_hash"] == inventory["inventory_hash"]
+
+
+def test_router_state_root_id_is_stable_for_normalized_roots(tmp_path: Path) -> None:
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data-link").symlink_to(tmp_path / "data", target_is_directory=True)
+    state_root = router_state_root(tmp_path, {"CLAUDE_PLUGIN_DATA": str(tmp_path / "data" / ".." / "data")})
+    symlink_root = router_state_root(tmp_path, {"CLAUDE_PLUGIN_DATA": str(tmp_path / "data-link")})
+    assert state_root == symlink_root
+    assert router_state_root_id(state_root) == router_state_root_id(symlink_root)
+
+
+def test_router_state_directory_is_scoped_under_the_router_root(tmp_path: Path) -> None:
+    state_directory = router_state_directory(tmp_path)
+    custom_environment = {"CLAUDE_PLUGIN_DATA": str(tmp_path / "custom-data")}
+    custom_state_directory = router_state_directory(tmp_path, custom_environment)
+
+    assert state_directory.parent == router_state_root(tmp_path)
+    assert custom_state_directory == router_state_root(tmp_path, custom_environment) / state_directory.name
+    assert custom_state_directory != state_directory
+    assert len(state_directory.name) == 64
+
+
+def test_generation_records_committed_and_working_domains_once(tmp_path: Path) -> None:
+    repository = tmp_path / "repository"
+    repository.mkdir()
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=repository, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=repository, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=repository, check=True)
+    tracked = repository / "packages" / "feature.py"
+    tracked.parent.mkdir()
+    tracked.write_text("one\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=repository, check=True)
+    subprocess.run(["git", "commit", "-qm", "initial"], cwd=repository, check=True)
+    initial_commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repository, check=True, capture_output=True, text=True).stdout.strip()
+    tracked.write_text("one\nbase\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(tracked)], cwd=repository, check=True)
+    subprocess.run(["git", "commit", "-qm", "feature"], cwd=repository, check=True)
+    tracked.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(tracked)], cwd=repository, check=True)
+    tracked.write_text("one\ntwo\nthree\n", encoding="utf-8")
+    (repository / "new.py").write_text("new\n", encoding="utf-8")
+    inventory = inventory_generation(repository, initial_commit)
+    records = {record["path"]: record["domains"] for record in inventory["files_by_domain"]}
+    assert records["packages/feature.py"] == ["committed", "staged", "unstaged"]
+    assert records["new.py"] == ["untracked"]
+    assert inventory["base_ref"] and inventory["merge_base"] and inventory["HEAD"]
+
+
+@pytest.mark.parametrize("base_ref", ["missing", "HEAD~99"])
+def test_invalid_base_writes_no_card(tmp_path: Path, base_ref: str) -> None:
+    repository = tmp_path / "repository"
+    repository.mkdir()
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=repository, check=True)
+    (repository / "seed.txt").write_text("seed\n", encoding="utf-8")
+    subprocess.run(["git", "add", "seed.txt"], cwd=repository, check=True)
+    subprocess.run(["git", "-c", "user.name=Test", "-c", "user.email=test@example.com", "commit", "-qm", "initial"], cwd=repository, check=True)
+    with pytest.raises(ValueError, match="INVALID_BASE_REF"):
+        build_generation(repository, base_ref=base_ref, card_path=tmp_path / "card.json")
+    assert not (tmp_path / "card.json").exists()
+
+
+def _git_repository(root: Path) -> None:
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=root, check=True)
+    (root / "seed.txt").write_text("seed\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-qm", "initial"], cwd=root, check=True)
+
+
+def test_diff_hash_changes_when_same_path_content_changes(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    tracked_path = tmp_path / "seed.txt"
+    first_hash = inventory_generation(tmp_path)["diff_hash"]
+    tracked_path.write_text("changed\n", encoding="utf-8")
+    assert inventory_generation(tmp_path)["diff_hash"] != first_hash
+
+
+def test_effective_lines_include_committed_staged_unstaged_and_untracked(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    committed_path = tmp_path / "committed.txt"
+    committed_path.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "committed"], cwd=tmp_path, check=True)
+    staged_path = tmp_path / "staged.txt"
+    staged_path.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(staged_path)], cwd=tmp_path, check=True)
+    staged_path.write_text("one\ntwo\nthree\n", encoding="utf-8")
+    unstaged_path = tmp_path / "seed.txt"
+    unstaged_path.write_text("seed\nchanged\n", encoding="utf-8")
+    (tmp_path / "untracked.txt").write_text("one\ntwo\n", encoding="utf-8")
+    inventory = inventory_generation(tmp_path)
+    assert inventory["lines"] >= 6
+
+
+def test_inventory_preserves_rename_prior_path_and_operations(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    old_path = tmp_path / "old name.txt"
+    old_path.write_text("content\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "rename source"], cwd=tmp_path, check=True)
+    new_path = tmp_path / "new name.txt"
+    old_path.rename(new_path)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
+    records = {record["path"]: record for record in inventory_generation(tmp_path)["files_by_domain"]}
+    assert records["new name.txt"]["prior_path"] == "old name.txt"
+    assert records["new name.txt"]["operation_by_domain"]["staged"] == "R"
+
+
+def test_inventory_preserves_delete_binary_space_unicode_and_symlink_identity(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    deleted = tmp_path / "deleted file.txt"
+    deleted.write_text("delete me\n", encoding="utf-8")
+    binary = tmp_path / "binary.bin"
+    binary.write_bytes(b"\0\xff")
+    unicode_path = tmp_path / "café.txt"
+    unicode_path.write_text("unicode\n", encoding="utf-8")
+    link = tmp_path / "link.txt"
+    link.symlink_to("seed.txt")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "surface"], cwd=tmp_path, check=True)
+    surface_commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, capture_output=True, text=True).stdout.strip()
+    deleted.unlink()
+    binary.write_bytes(b"\0\x00changed")
+    unicode_path.write_text("unicode changed\n", encoding="utf-8")
+    link.unlink()
+    link.symlink_to("café.txt")
+    subprocess.run(["git", "add", "-u"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
+    records = {record["path"]: record for record in inventory_generation(tmp_path, surface_commit)["files_by_domain"]}
+    assert records["deleted file.txt"]["content_sha256"] != "0" * 64
+    assert records["binary.bin"]["binary"] is True
+    assert records["café.txt"]["path"] == "café.txt"
+    assert records["link.txt"]["content_sha256"]
+
+
+def test_package_count_uses_distinct_monorepo_package_keys(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    for path in ("packages/one/a.py", "packages/one/b.py", "apps/two/c.py", "root.py"):
+        target = tmp_path / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text("x\n", encoding="utf-8")
+    assert inventory_generation(tmp_path)["packages"] == 3
+
+
+def test_explicit_and_default_base_provenance_fields_are_exact(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    default_inventory = inventory_generation(tmp_path)
+    explicit_inventory = inventory_generation(tmp_path, "HEAD")
+    assert default_inventory["base_source"] == "configured_fallback"
+    assert explicit_inventory["base_source"] == "explicit"
+    for field in ("base_ref", "base_source", "base_sha", "merge_base_sha", "head_sha"):
+        assert default_inventory[field]

package/.agents/skills/review-tier/scripts/test_review_tier.py

@@ -0,0 +1,33 @@
+from review_tier import build_decision, calculate_tier, canonical_json_hash, effective_tier, load_policy, policy_hash
+
+
+def test_public_policy_functions_return_behavior() -> None:
+    tier_policy = load_policy()
+    assert policy_hash(tier_policy)
+    assert canonical_json_hash(tier_policy) == policy_hash(tier_policy)
+    decision = build_decision({}, "base", "head", ".", "digest", requested_override="T1")
+    assert decision["effective_tier"] == "T1"
+
+
+def test_tier_boundaries_and_hard_trigger() -> None:
+    assert calculate_tier({"files": 0, "lines": 0, "packages": 0, "risk": 0}) == "T1"
+    assert calculate_tier({"files": 2}) == "T2"
+    assert calculate_tier({"files": 5}) == "T2"
+    assert calculate_tier({"hard_triggers": ["security"]}) == "T3"
+
+
+def test_all_six_axes_accept_zero_one_two_boundaries() -> None:
+    axes = ("files", "lines", "packages", "risk", "public_api", "dependencies")
+    assert calculate_tier({axis: 0 for axis in axes}) == "T1"
+    assert calculate_tier({axis: 1 for axis in axes}) == "T3"
+    assert calculate_tier({axis: 2 for axis in axes}) == "T3"
+
+
+def test_score_boundaries_keep_small_changes_below_t3() -> None:
+    assert calculate_tier({"files": 1, "lines": 1}) == "T2"
+    assert calculate_tier({"files": 2, "packages": 1, "risk": 1}) == "T3"
+
+
+def test_upward_and_approved_downward_override() -> None:
+    assert effective_tier("T1", "T3") == "T3"
+    assert effective_tier("T3", "T1") == "T1"

package/.agents/skills/run-claude-dev-env/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: run-claude-dev-env
+description: Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.
+---
+
+`claude-dev-env` is the npm-distributed installer that copies this repo's rules, hooks, commands, and docs into `~/.claude/`, copies skills and agents into `~/.agents/`, publishes directory pointers at `~/.claude/skills` and `~/.claude/agents`, and merges its hook entries into `~/.claude/settings.json`. Its entry point is `bin/install.mjs`. Drive it with the smoke driver at `.claude/skills/run-claude-dev-env/driver.mjs`, which runs the installer against a throwaway sandbox home directory so a run never touches the real `~/.claude/` or `~/.agents/`.
+
+All paths below are written from the `packages/claude-dev-env/` directory.
+
+## Prerequisites
+
+The installer needs three tools on `PATH`:
+
+- **Node.js 18+** — the installer is an ES module (verified on Node 22.17).
+- **Python 3.8+** — the installer bakes a Python interpreter into every hook command and aborts if it finds none. On Windows it skips the Microsoft Store stub (verified `py -3` → Python 3.13.5).
+- **git** — the installer reads `git status` to guard against installing from a conflicted source, and sets a global git hooks path.
+
+```bash
+node --version
+git --version
+py -3 --version    # POSIX: python3 --version
+```
+
+On a fresh Ubuntu container the three come from `sudo apt-get install -y nodejs python3 git`.
+
+## Run (agent path) — the smoke driver
+
+The driver is the handle to reach for first. It spawns the installer against a fresh temp home directory with `HOME`, `USERPROFILE`, and `GIT_CONFIG_GLOBAL` all redirected, runs the `--help` → install → `--uninstall` lifecycle, asserts the result of each step against the sandbox tree, then deletes the sandbox. It works the same on Windows and POSIX.
+
+```bash
+node .claude/skills/run-claude-dev-env/driver.mjs
+```
+
+Expected tail:
+
+```
+21/21 checks passed.
+ALL CHECKS PASSED
+```
+
+The driver proves a full install lands skills under `<sandbox>/.agents/skills` with a directory pointer at `<sandbox>/.claude/skills`, lands agents the same way, lands hook scripts, rules, the `CLAUDE.md` hub, a populated `settings.json`, and a tracking manifest, and that `--uninstall` removes every manifest-tracked file. The real `~/.claude/`, `~/.agents/`, and the real global git config stay untouched. Exit code is 0 only when all checks hold.
+
+## Run (human path) — install for real
+
+These write into your real `~/.claude/` and set a global git hooks path. Run them only when you mean to install on this machine.
+
+```bash
+node bin/install.mjs --help         # usage only, no side effects
+node bin/install.mjs                # install every group
+node bin/install.mjs --only core    # install one or more named groups
+node bin/install.mjs --update       # remove manifest-tracked files, then reinstall
+node bin/install.mjs --uninstall    # remove every installed file
+```
+
+Groups: `core`, `journal`, and the discovered `prompt-generator` dependency group. Run `node bin/install.mjs --help` for the live list. The published package runs the same entry point as `npx claude-dev-env`.
+
+## Test
+
+```bash
+npm test
+```
+
+Runs `node --test` over `bin/*.test.mjs` and `.agents/skills/**/*.test.mjs` with Node's built-in test runner — no extra dependency, no network. Expected: `# fail 0`, with the pass count growing as tests are added.
+
+## Gotchas
+
+- **The install target is `os.homedir()/.claude` with no override flag** (the `CLAUDE_HOME` constant in `bin/install.mjs`). To drive the installer without overwriting your real config, redirect the home directory: set `USERPROFILE` (Windows) and `HOME` (POSIX) to a temp dir. The driver does this for you.
+- **The installer reaches outside `~/.claude/`.** It writes skills and agents under `~/.agents/`, runs `git config --global core.hooksPath ...`, which applies to every git repo on the machine, and it writes `~/.mypy.ini`. The driver isolates those writes by pointing `GIT_CONFIG_GLOBAL` at a sandbox file and redirecting the home directory.
+- **git "dubious ownership" aborts the install.** The source-conflict guard runs `git status`; when the checkout sits on a path git distrusts (a UNC network share owned by another account), git exits 128 with a dubious-ownership message that the installer rethrows. The driver seeds its sandbox git config with `safe.directory = *` so the guard runs. For a real install on such a checkout, add the exception: `git config --global --add safe.directory '<repo-path>'`.
+- **`npm install` at the repo root fails on a Windows network-share checkout.** npm symlinks the workspace package into root `node_modules` and the share rejects the symlink (`UNKNOWN ... symlink`, errno -4094). The package's own `node_modules` already carries its single dependency, so the driver and tests run without it. The installer also keeps working when `@jl-cmd/prompt-generator` cannot resolve — it skips that group with a warning (`discoverDependencyGroups` in `bin/install.mjs`).
+- **Microsoft Store Python is rejected on Windows.** The installer skips any interpreter under a `WindowsApps` directory because that stub cannot run as a hook subprocess (`isWindowsStorePythonStub` in `bin/install.mjs`). Install Python from python.org if detection fails.
+
+## Troubleshooting
+
+- **`ERROR: No usable Python 3 found`**: no `py -3` / `python3` / `python` resolves to a non-Store Python 3. Install Python 3.8+ from python.org and reopen the shell.
+- **`fatal: detected dubious ownership in repository`**: add the `safe.directory` exception shown above, then rerun.
+- **`ERROR: settings.json is malformed JSON`**: `~/.claude/settings.json` has a syntax error; fix the JSON and rerun.
+
+## Files
+
+- `SKILL.md` — this page: the agent path (the driver), the human install path, the test command, gotchas, and troubleshooting.
+- `driver.mjs` — the smoke harness that drives `bin/install.mjs` against a sandbox home directory. Run it; you do not need to read it. It sits beside this file at `.claude/skills/run-claude-dev-env/driver.mjs`.
+
+The `/run` skill auto-discovers this skill when asked to run, install, or test `claude-dev-env`.

package/.agents/skills/run-claude-dev-env/driver.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Smoke driver for the claude-dev-env installer.
+ *
+ * The installer (bin/install.mjs) writes into os.homedir()/.claude and
+ * os.homedir()/.agents and has
+ * three global side effects: it copies files under ~/.claude/ and ~/.agents/, sets
+ * `git config --global core.hooksPath`, and writes ~/.mypy.ini. There is no
+ * flag to redirect the target, so this driver isolates every side effect by
+ * spawning the installer with HOME, USERPROFILE, and GIT_CONFIG_GLOBAL all
+ * pointed at a throwaway sandbox directory. Node's os.homedir() follows
+ * USERPROFILE on Windows and HOME on POSIX, so setting both redirects the
+ * install target on either platform without touching the real ~/.claude/.
+ *
+ * The isolated GIT_CONFIG_GLOBAL is seeded with `safe.directory = *` so the
+ * installer's `git status` source-conflict guard runs even when the checkout
+ * lives somewhere git flags as dubious ownership (for example a UNC network
+ * share), while the installer's `git config --global core.hooksPath` write
+ * still lands only in the sandbox config.
+ *
+ * It runs the three lifecycle commands an agent cares about — `--help`, a full
+ * install, and `--uninstall` — and asserts the observable result of each
+ * against the sandbox tree. Exit code 0 means every assertion held.
+ *
+ * Usage: node .claude/skills/run-claude-dev-env/driver.mjs
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    existsSync,
+    lstatSync,
+    readFileSync,
+    realpathSync,
+    writeFileSync,
+    readdirSync,
+    rmSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const DRIVER_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(DRIVER_DIRECTORY, '..', '..', '..');
+const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
+
+const checks = [];
+
+function record(label, passed, detail) {
+    checks.push({ label, passed, detail });
+    const mark = passed ? 'PASS' : 'FAIL';
+    console.log(`  [${mark}] ${label}${detail ? ` — ${detail}` : ''}`);
+}
+
+function collectFilesRecursive(directory) {
+    const collected = [];
+    if (!existsSync(directory)) return collected;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const entryPath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            collected.push(...collectFilesRecursive(entryPath));
+        } else {
+            collected.push(entryPath);
+        }
+    }
+    return collected;
+}
+
+function runInstaller(sandboxHome, installerArguments) {
+    const gitConfigGlobal = join(sandboxHome, '.gitconfig-sandbox');
+    const result = spawnSync(process.execPath, [INSTALL_ENTRY, ...installerArguments], {
+        cwd: PACKAGE_ROOT,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: sandboxHome,
+            USERPROFILE: sandboxHome,
+            GIT_CONFIG_GLOBAL: gitConfigGlobal,
+        },
+    });
+    return result;
+}
+
+function main() {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-driver-'));
+    const claudeHome = join(sandboxHome, '.claude');
+    writeFileSync(join(sandboxHome, '.gitconfig-sandbox'), '[safe]\n\tdirectory = *\n');
+    console.log(`Sandbox HOME: ${sandboxHome}`);
+    console.log(`Install entry: ${INSTALL_ENTRY}\n`);
+
+    try {
+        console.log('Step 1: node bin/install.mjs --help');
+        const help = runInstaller(sandboxHome, ['--help']);
+        record('--help exits 0', help.status === 0, `exit=${help.status}`);
+        record('--help prints usage', /Usage:/.test(help.stdout), '');
+        record('--help wrote nothing to ~/.claude', !existsSync(claudeHome), '');
+
+        console.log('\nStep 2: node bin/install.mjs (full install)');
+        const install = runInstaller(sandboxHome, []);
+        if (install.status !== 0) {
+            console.log(install.stdout);
+            console.log(install.stderr);
+        }
+        record('install exits 0', install.status === 0, `exit=${install.status}`);
+
+        const manifestPath = join(claudeHome, '.claude-dev-env-manifest.json');
+        let manifest = null;
+        if (existsSync(manifestPath)) {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        record('manifest written', manifest !== null, manifestPath);
+        record(
+            'manifest names this package',
+            manifest?.package === 'claude-dev-env',
+            manifest ? `package=${manifest.package} version=${manifest.version}` : 'missing',
+        );
+        record(
+            'manifest tracks installed files',
+            Array.isArray(manifest?.files) && manifest.files.length > 0,
+            manifest?.files ? `${manifest.files.length} files` : 'none',
+        );
+
+        const skillsDirectory = join(claudeHome, 'skills');
+        const agentsHomeSkillsDirectory = join(sandboxHome, '.agents', 'skills');
+        const installedSkills = existsSync(skillsDirectory)
+            ? readdirSync(skillsDirectory, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+            : [];
+        record('skills installed', installedSkills.length > 0, `${installedSkills.length} skill dirs`);
+        record(
+            'skills live under ~/.agents/skills',
+            existsSync(agentsHomeSkillsDirectory)
+                && installedSkills.some((entry) => existsSync(join(agentsHomeSkillsDirectory, entry.name))),
+            agentsHomeSkillsDirectory,
+        );
+        record(
+            '~/.claude/skills is a directory pointer',
+            existsSync(skillsDirectory) && lstatSync(skillsDirectory).isSymbolicLink(),
+            skillsDirectory,
+        );
+        const sampleSkillName = installedSkills.find((entry) => existsSync(join(skillsDirectory, entry.name, 'SKILL.md')))?.name;
+        if (sampleSkillName) {
+            const lookupSkillPath = join(skillsDirectory, sampleSkillName, 'SKILL.md');
+            const canonicalSkillPath = join(agentsHomeSkillsDirectory, sampleSkillName, 'SKILL.md');
+            record(
+                'skill files match through the lookup pointer',
+                existsSync(lookupSkillPath)
+                    && existsSync(canonicalSkillPath)
+                    && realpathSync(lookupSkillPath) === realpathSync(canonicalSkillPath),
+                sampleSkillName,
+            );
+        } else {
+            record('skill files match through the lookup pointer', false, 'no skill dirs');
+        }
+
+        const agentsLookupDirectory = join(claudeHome, 'agents');
+        const agentsHomeAgentsDirectory = join(sandboxHome, '.agents', 'agents');
+        record(
+            'agents live under ~/.agents/agents',
+            existsSync(agentsHomeAgentsDirectory)
+                && readdirSync(agentsHomeAgentsDirectory).some((name) => name.endsWith('.md')),
+            agentsHomeAgentsDirectory,
+        );
+        record(
+            '~/.claude/agents is a directory pointer',
+            existsSync(agentsLookupDirectory) && lstatSync(agentsLookupDirectory).isSymbolicLink(),
+            agentsLookupDirectory,
+        );
+
+        const hookFiles = collectFilesRecursive(join(claudeHome, 'hooks')).filter((file) =>
+            file.endsWith('.py'),
+        );
+        record('hook scripts installed', hookFiles.length > 0, `${hookFiles.length} .py files`);
+
+        const ruleFiles = existsSync(join(claudeHome, 'rules'))
+            ? readdirSync(join(claudeHome, 'rules')).filter((name) => name.endsWith('.md'))
+            : [];
+        record('rules installed', ruleFiles.length > 0, `${ruleFiles.length} .md files`);
+
+        record('CLAUDE.md hub installed', existsSync(join(claudeHome, 'CLAUDE.md')), '');
+
+        const settingsPath = join(claudeHome, 'settings.json');
+        let managedHookCount = 0;
+        if (existsSync(settingsPath)) {
+            const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+            for (const matcherGroups of Object.values(settings.hooks ?? {})) {
+                for (const group of matcherGroups) {
+                    for (const hook of group.hooks ?? []) {
+                        if (hook.command.replace(/\\/g, '/').includes('/.claude/hooks')) {
+                            managedHookCount += 1;
+                        }
+                    }
+                }
+            }
+        }
+        record('settings.json carries managed hooks', managedHookCount > 0, `${managedHookCount} hook commands`);
+
+        const gitConfigGlobalPath = join(sandboxHome, '.gitconfig-sandbox');
+        const gitHooksPathRedirectedIntoSandbox =
+            existsSync(gitConfigGlobalPath) &&
+            readFileSync(gitConfigGlobalPath, 'utf8').replace(/\\/g, '/').includes('/.claude/hooks/git-hooks');
+        record(
+            'global git hooksPath isolated to sandbox',
+            gitHooksPathRedirectedIntoSandbox,
+            'GIT_CONFIG_GLOBAL kept the real ~/.gitconfig untouched',
+        );
+
+        const sampleInstalledFile = manifest?.files?.find((file) => existsSync(file));
+
+        console.log('\nStep 3: node bin/install.mjs --uninstall');
+        const uninstall = runInstaller(sandboxHome, ['--uninstall']);
+        if (uninstall.status !== 0) {
+            console.log(uninstall.stdout);
+            console.log(uninstall.stderr);
+        }
+        record('uninstall exits 0', uninstall.status === 0, `exit=${uninstall.status}`);
+        record('manifest removed', !existsSync(manifestPath), '');
+        record(
+            'tracked file removed',
+            sampleInstalledFile ? !existsSync(sampleInstalledFile) : false,
+            sampleInstalledFile ? sampleInstalledFile : 'no sample file captured',
+        );
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+        console.log(`\nSandbox removed: ${sandboxHome}`);
+    }
+
+    const failures = checks.filter((check) => !check.passed);
+    console.log(`\n${checks.length - failures.length}/${checks.length} checks passed.`);
+    if (failures.length > 0) {
+        console.log('FAILED:');
+        for (const failure of failures) {
+            console.log(`  - ${failure.label}`);
+        }
+        process.exit(1);
+    }
+    console.log('ALL CHECKS PASSED');
+}
+
+main();

package/.agents/skills/session-log/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/{skills → .agents/skills}/session-log/SKILL.md

@@ -25,7 +25,7 @@ Sessions come in many shapes — convergence loops, feature builds, research div
 - **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
 - **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
 - **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
-- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/doc-prose-cuts.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
+- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html. Apply `~/.claude/rules/asd-ste100-language.md` for user-facing word choice and sentence style, and keep the session report current and self-contained.
 - **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
 - **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
 

package/.agents/skills/session-tidy/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md