claude-dev-env 8.1.0 → 8.3.0

package/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md

@@ -11,7 +11,7 @@ Audit [REPO/ARTIFACT] [TARGET_ID] for **Category N only** (test-name scenario ve
 
 ID prefix: `find`.
 
-[ONE-PARAGRAPH FRAME: enumerate every test whose name includes a scenario claim (`_when_*`, `_at_*`, `_under_*`, `_with_*`, `_on_*`, `_after_*`, `_during_*`). State the audit goal: for each scenario-named test, verify the body sets up the named condition via fixture / monkeypatch / environment gate so the production code's scenario-named branch actually runs during the act phase.]
+[ONE-PARAGRAPH FRAME: enumerate every test whose name includes a scenario claim (`_when_*`, `_at_*`, `_under_*`, `_with_*`, `_on_*`, `_after_*`, `_during_*`). State the audit goal: for each scenario-named test, verify the body sets up the named condition via fixture / monkeypatch / environment gate so the production code's scenario-named branch runs during the act phase.]
 
 ## Source material ([N] files/sections, all lines in scope)
 
@@ -37,12 +37,12 @@ ID prefix: `find`.
 
 **N5. Assertion shape mismatch**
 - For every assertion, verify the assertion's shape can fail by construction. `assert <substring> not in result` where the substring is misspelled relative to the production output, or `assert result == ""` when the production function returns `None` on the negative case, or `len(result) > 0` when the production function returns an empty list on the no-feature path.
-- Adversarial probes: (a) inspect each assertion's shape against the production function's actual return-value space; (b) check for assertions where the substring shape never appears in the production output by construction; (c) check for `assert x is True` where the production function returns truthy non-bool values.
+- Adversarial probes: (a) inspect each assertion's shape against the production function's return-value space; (b) check for assertions where the substring shape never appears in the production output by construction; (c) check for `assert x is True` where the production function returns truthy non-bool values.
 
 **N6. Cross-platform scenario gating**
 - For every test named `_on_windows` / `_on_linux` / `_on_macos`, verify the body gates on `sys.platform`, `monkeypatch.setattr(os, "name", ...)`, or `@pytest.mark.skipif`.
 - Bare scenario names that run unchanged across platforms claim more than they prove.
-- Adversarial probes: (a) does the production function's platform-specific branch get skipped on the CI runner's actual platform; (b) does the test pass against the platform fallback rather than the platform-specific code; (c) is the platform fixture installed and respected by the test runner.
+- Adversarial probes: (a) does the production function's platform-specific branch get skipped on the CI runner's platform; (b) does the test pass against the platform fallback rather than the platform-specific code; (c) is the platform fixture installed and respected by the test runner.
 
 **N7. Time / clock scenario gating**
 - For every test named `_after_<duration>` / `_at_midnight` / `_during_business_hours`, verify the body injects a frozen clock (`freezegun.freeze_time`, `monkeypatch.setattr(time, "time", ...)`, `unittest.mock.patch("datetime.now")`).
@@ -62,8 +62,8 @@ ID prefix: `find`.
 - For every test, verify the fixture / path / import wiring resolves to the artifact the test name claims.
 - Path arithmetic: walk every `Path(__file__).parents[k]` chain symbolically and confirm it reaches the directory the assertion expects — a `parents[3]` that stops at `skills/` while the test expects the package root cannot fail for the right reason.
 - Same-symbol dual imports: `from module import helper` plus `from module import helper as helper_alias` bind two names to the same function object, so any parity assertion between the two bound names is true by construction and proves nothing.
-- Fixture file lookups: confirm every `open(Path(__file__).parent / "fixture.txt")` (or equivalent) reaches a file that actually exists in the repo.
-- Adversarial probes: (a) re-derive each `parents[k]` index against the real directory depth and flag any off-by-k; (b) check whether two imports in the test resolve to the same object before trusting a cross-name comparison; (c) confirm each referenced fixture path exists on disk at the depth the arithmetic produces.
+- Fixture file lookups: confirm every `open(Path(__file__).parent / "fixture.txt")` (or equivalent) reaches a file that exists in the repo.
+- Adversarial probes: (a) re-derive each `parents[k]` index against the directory depth and flag any off-by-k; (b) check whether two imports in the test resolve to the same object before trusting a cross-name comparison; (c) confirm each referenced fixture path exists on disk at the depth the arithmetic produces.
 
 ## Cross-bucket questions to answer at the end
 
@@ -87,7 +87,7 @@ PR: refactor(hooks): cross-platform path resolution for windows-rmtree-blocker
 Head SHA: (the commit that landed the platform-conditional logic)
 ID prefix: `find`.
 
-The PR adds platform-conditional path-resolution logic to `windows_rmtree_blocker.py` and ships 5 new tests named `test_*_on_windows` and `test_*_on_linux` across `test_windows_rmtree_blocker.py`. The audit goal: verify each scenario-named test sets up the named platform via monkeypatch or skipif gate so the production function's platform-specific branch actually runs during the act phase.
+The PR adds platform-conditional path-resolution logic to `windows_rmtree_blocker.py` and ships 5 new tests named `test_*_on_windows` and `test_*_on_linux` across `test_windows_rmtree_blocker.py`. The audit goal: verify each scenario-named test sets up the named platform via monkeypatch or skipif gate so the production function's platform-specific branch runs during the act phase.
 
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
@@ -128,7 +128,7 @@ The PR adds platform-conditional path-resolution logic to `windows_rmtree_blocke
 
 ## Cross-bucket questions to answer at the end
 
-Q1: Five scenario-named tests (F5, F21, F23, F26, F27) do not gate on `sys.platform` and pass against the Linux-fallback branch on the CI runner. The Windows-specific code path has zero actual coverage despite the test names claiming it. Cite `test_windows_rmtree_blocker.py:42` (F5 first test) and `windows_rmtree_blocker.py:67` (the `if sys.platform == "win32":` branch) as the misclaim pair.
+Q1: Five scenario-named tests (F5, F21, F23, F26, F27) do not gate on `sys.platform` and pass against the Linux-fallback branch on the CI runner. The Windows-specific code path has zero coverage despite the test names claiming it. Cite `test_windows_rmtree_blocker.py:42` (F5 first test) and `windows_rmtree_blocker.py:67` (the `if sys.platform == "win32":` branch) as the misclaim pair.
 
 Q2: Worst false-coverage signal: F5 — the test's name `test_resolves_path_on_windows` reads as Windows-branch coverage in the PR review, but the act phase exercises the Linux fallback. A reviewer reading the test name during PR review would assume Windows coverage exists; it does not.
 

package/audit-rubrics/prompts/category-o-docstring-vs-impl-drift.md

@@ -57,7 +57,7 @@ ID prefix: `find`.
 
 **O6. Free-form `Args:`-adjacent claims**
 - Judgment: thick rubric O6 (unions, suppressors, exclusion axis, delegation summaries, Returns/Raises/Note claims, run-mode field meaning). Gate inventory and free-form checklist live in the rubric.
-- Adversarial probes: (a) check `Returns:` claims against every `return` statement in the body — is the documented return shape the actual return shape; (b) check `Raises:` claims against every `raise` and propagating callee — is every documented raise reachable; (c) check `Example:` snippets — does the snippet actually compile against the signature.
+- Adversarial probes: (a) check `Returns:` claims against every `return` statement in the body — is the documented return shape the shape the body returns; (b) check `Raises:` claims against every `raise` and propagating callee — is every documented raise reachable; (c) check `Example:` snippets — does the snippet compile against the signature.
 
 **O7. Module-doc-vs-split-module after refactor**
 - Judgment: thick rubric O7.
@@ -89,7 +89,7 @@ Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O9, produce Shape A
 
 Audit jl-cmd/claude-dev-env PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below.
 
-PR #522 split `pr_description_command_parser.py` into two modules — the original parser and a new `pr_description_pr_number.py` — but the originating module's docstring still claims the PR-number recovery responsibility. A sibling change to `pr_description_body_audit.py` introduced a module docstring whose verb (`detects vague language`) overstates the module's actual responsibility (it only exposes `_extract_vague_scan_text()`; detection runs elsewhere).
+PR #522 split `pr_description_command_parser.py` into two modules — the original parser and a new `pr_description_pr_number.py` — but the originating module's docstring still claims the PR-number recovery responsibility. A sibling change to `pr_description_body_audit.py` introduced a module docstring whose verb (`detects vague language`) overstates the module's responsibility (it only exposes `_extract_vague_scan_text()`; detection runs elsewhere).
 
 Expected findings on PR #522:
 - **O1 finding:** `pr_description_body_audit.py:8` docstring uses verb `detects`, but the only exported symbol prepares input for a regex scan that fires in a different module. Body line(s) showing `_extract_vague_scan_text` returning normalized text without a detection call.

package/audit-rubrics/prompts/category-p-name-vs-behavior-contract.md

@@ -37,11 +37,11 @@ Two canonical failures to probe for:
 
 **P1. Boolean / flag names assert state the body keeps**
 - For every new `is_*` / `has_*` / `was_*` / `should_*` flag, trace the body. Every set site must be paired with a reset site that fires when the named condition becomes false.
-- Adversarial probes: (a) grep every assignment to the flag — count set-true vs set-false; (b) for AST-driven flags, walk the visit method and confirm scope-exit semantics (def visited → flag set; dedent / function-exit → flag reset); (c) construct an input where the flag should be false after a prior true region — does the code agree.
+- Adversarial probes: (a) grep every assignment to the flag — count set-true vs set-false; (b) for AST-driven flags, walk the visit method and confirm scope-exit semantics (def visited → flag set; dedent / function-exit → flag reset); (c) construct an input where the flag should be false after a region that set it true — does the code agree.
 
 **P2. Predicate-name breadth matches body coverage**
 - For every new `_is_*` / `_has_*` / `_can_*` predicate function, list the body's `return True` branches. The named predicate must hold on the union of those branches and nothing else.
-- Adversarial probes: (a) construct an input that satisfies the name but returns False — that is a P2 narrowness finding; (b) construct an input that does not satisfy the name but returns True — that is a P2 breadth finding; (c) check neighbor predicates — is the body's actual contract the responsibility of a different helper.
+- Adversarial probes: (a) construct an input that satisfies the name but returns False — that is a P2 narrowness finding; (b) construct an input that does not satisfy the name but returns True — that is a P2 breadth finding; (c) check neighbor predicates — is the body's contract the responsibility of a different helper.
 
 **P3. Regex name vs regex shape** ⭐ canonical P case
 - For every new `*_PATTERN` / `*_REGEX` constant, read the regex source. Confirm the anchors (`^`, `$`, `\b`, lookarounds) match the name's promised shape. `FILE_PATH_PATTERN` implies path shape; the regex must include path-shape anchors (slash count, segment shape, length bounds) enough to reject non-path inputs.
@@ -73,7 +73,7 @@ Q3: Which identifier most clearly shows the body should be renamed (the name is
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket P1-P7, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the identifier file:line, (b) one concrete input that shows the name-vs-body gap, and (c) the recommended fix direction (rename vs body-tighten). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 identifiers whose names overstate what the body actually does — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket P1-P7, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the identifier file:line, (b) one concrete input that shows the name-vs-body gap, and (c) the recommended fix direction (rename vs body-tighten). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 identifiers whose names overstate what the body does — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 

package/audit-rubrics/prompts/category-q-cross-surface-claims.md

@@ -30,13 +30,13 @@ ID prefix: `find`.
 
 **Q2. PR-description claim verification**
 - Read the PR body. List each falsifiable claim — a dead-code removal, a performance or ceiling number, a "last caller" assertion, a "no remaining X" cleanup claim.
-- Verify each claim two ways against the diff and the repo. A dead-code claim gets a reference search across the repo for the named symbol. A ceiling or performance claim gets checked against the actual config value the diff sets and the call sites it touches. Cite the PR-body line and the diff or repo line that confirms or contradicts it.
+- Verify each claim two ways against the diff and the repo. A dead-code claim gets a reference search across the repo for the named symbol. A ceiling or performance claim gets checked against the config value the diff sets and the call sites it touches. Cite the PR-body line and the diff or repo line that confirms or contradicts it.
 - Adversarial probes when the body looks correct: (a) search the repo for a surviving caller of any symbol the body calls dead; (b) compare each stated number against the config constant the diff sets; (c) check whether a "this finishes the cleanup" claim leaves a matching pattern in an unchanged sibling file.
 
 **Q3. Message-vs-guard consistency**
 - For every log, error, and evidence string the diff adds or edits, read the branch condition that gates it. The message text matches what that guard guarantees: a string asserting an outcome fires only on a branch that reaches the outcome.
 - Check temporal wording against the lifetime of the state variable the message names: "this run" versus "this round", "is open" versus "was opened", "reached" versus "attempted". Cite the message line and the guard or state-variable line.
-- Adversarial probes when messages look aligned: (a) trace each success message back to the return value or flag it claims and confirm the branch cannot reach it with the opposite value; (b) check every "missing" / "not found" error against the exception class the branch actually catches; (c) check every counter-based message against where the counter resets.
+- Adversarial probes when messages look aligned: (a) trace each success message back to the return value or flag it claims and confirm the branch cannot reach it with the opposite value; (b) check every "missing" / "not found" error against the exception class the branch catches; (c) check every counter-based message against where the counter resets.
 
 ## Cross-bucket questions to answer at the end
 

package/bin/ever-shipped-skills.mjs

@@ -59,6 +59,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'pmax',
     'pmid',
     'pmin',
+    'plugin-eval-standalone-skill',
     'post-audit-findings',
     'pr-cleanup',
     'pr-consistency-audit',

package/bin/ever-shipped-skills.test.mjs

@@ -41,6 +41,10 @@ test('EVER_SHIPPED_SKILL_NAMES includes the windows scheduled task skill', () =>
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('windows-scheduled-task'), true);
 });
 
+test('EVER_SHIPPED_SKILL_NAMES includes the plugin eval standalone skill', () => {
+    assert.equal(EVER_SHIPPED_SKILL_NAMES.has('plugin-eval-standalone-skill'), true);
+});
+
 test('EVER_SHIPPED_SKILL_NAMES includes the session continuity companion', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('session-continuity'), true);
 });

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

@@ -12,6 +12,7 @@ import {
     mkdirSync,
     mkdtempSync,
     readFileSync,
+    readdirSync,
     realpathSync,
     rmSync,
     writeFileSync,
@@ -34,38 +35,8 @@ const SHIPPED_SKILL_NAME = 'privacy-hygiene';
 const ELI5_SKILL_NAME = 'eli5';
 const E_CODE_REVIEW_SKILL_NAME = 'e-code-review';
 const REFERENCE_DIRECTORY_NAME = 'reference';
-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/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 SHIPPED_AGENT_FILE_NAME = 'AGENTS.md';
+const RETIRED_AGENT_FILE_NAMES = ['clean-coder.md', 'code-quality-agent.md', 'pr-description-writer.md'];
 const PERSONAL_SKILL_NAME = 'my-notes';
 const PREFLIGHT_PROPOSAL_FILE_NAME = 'preflight-proposal.md';
 
@@ -116,37 +87,48 @@ 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);
 });
 
+test('full install archives recorded retired agents and preserves third-party agents', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agent-retirement-'));
+    try {
+        runInstaller(homeDirectory, []);
+        const agentsDirectory = join(homeDirectory, '.agents', 'agents');
+        const retiredPath = join(agentsDirectory, 'clean-coder.md');
+        const pluginPath = join(agentsDirectory, 'poteto-agent.md');
+        const activePath = join(agentsDirectory, 'AGENTS.md');
+        const sourcePluginPath = join(PACKAGE_DIRECTORY, '.agents', 'agents', 'poteto-agent.md');
+        assert.equal(readFileSync(pluginPath, 'utf8'), readFileSync(sourcePluginPath, 'utf8'));
+        writeFileSync(retiredPath, 'recover this retired definition\n');
+        writeFileSync(pluginPath, 'preserve this plugin definition\n');
+        const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.files.push(retiredPath);
+        manifest.files.push(activePath);
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+
+        runInstaller(homeDirectory, []);
+
+        assert.equal(existsSync(retiredPath), false);
+        assert.ok(existsSync(activePath));
+        const backupRoot = join(homeDirectory, '.claude', '.claude-dev-env-pruned');
+        const backupNames = readdirSync(backupRoot, { recursive: true });
+        const retiredBackup = backupNames.find(name => name.endsWith('clean-coder.md'));
+        assert.ok(retiredBackup);
+        assert.equal(readFileSync(join(backupRoot, retiredBackup), 'utf8'), 'recover this retired definition\n');
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+        const updatedManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(updatedManifest.files.includes(retiredPath), false);
+        runInstaller(homeDirectory, []);
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('a full install writes skills and agents under .agents and points .claude at them', () => {
     const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-home-'));
     const claudeHome = join(homeDirectory, '.claude');
@@ -201,18 +183,6 @@ 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(),
@@ -229,7 +199,7 @@ 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', () => {
+test('installs omit retired agents in each active agents home', () => {
     const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
     const homeDirectory = join(runRoot, 'home');
     const configRoot = join(runRoot, 'config-profile');
@@ -283,7 +253,7 @@ test('real installs place the Clean Coder in each active agents home', () => {
                     ...eachInstallCase.environment,
                 },
             );
-            for (const eachAgentFileName of SHIPPED_AGENT_FILE_NAMES) {
+            for (const eachAgentFileName of RETIRED_AGENT_FILE_NAMES) {
                 const installedAgentPath = join(
                     eachInstallCase.agentsHome,
                     MANAGED_AGENTS_DIRECTORY_NAME,
@@ -291,30 +261,10 @@ test('real installs place the Clean Coder in each active agents home', () => {
                 );
                 assert.equal(
                     existsSync(installedAgentPath),
-                    true,
-                    `${eachInstallCase.name}: agent is under the active agents home`,
+                    false,
+                    `${eachInstallCase.name}: retired agent is absent`,
                 );
-                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),

package/bin/install.mjs

@@ -1135,6 +1135,7 @@ function renameCaseOnlyMatchToShippedName(destinationFilePath, entryNamesByDirec
 
 export function copyTree(sourceBase, destBase, options = {}) {
     const excludedFileNames = new Set(options.excludeFileNames ?? []);
+    const preservedFileNames = new Set(options.preserveExistingFileNames ?? []);
     const files = collectFiles(sourceBase).filter(
         sourceFile => !excludedFileNames.has(basename(sourceFile)),
     );
@@ -1144,6 +1145,10 @@ export function copyTree(sourceBase, destBase, options = {}) {
         const relativePath = relative(sourceBase, sourceFile);
         const destFile = join(destBase, relativePath);
         mkdirSync(dirname(destFile), { recursive: true });
+        if (preservedFileNames.has(basename(sourceFile)) && existsSync(destFile)) {
+            stats.paths.push(destFile);
+            continue;
+        }
         const existed = existsSync(destFile);
         renameCaseOnlyMatchToShippedName(destFile, entryNamesByDirectory, options);
         copyFileSync(sourceFile, destFile);
@@ -1223,6 +1228,8 @@ export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
 ]);
 
 export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
+    'observability/test_failure_recorder.py',
+    'advisory/msys_path_conversion_advisor.py',
     'session/untracked_repo_detector.py',
     'session/gh_pr_author_session_cleanup.py',
     'observability/pr_description_writer_spawn_tracker.py',
@@ -2326,29 +2333,6 @@ function pruneRetiredSkills(installedSkillNames, priorManifestSkills) {
     return movedDirectoryCount;
 }
 
-/**
- * Move every file a prior install wrote under a managed root that this run leaves
- * unwritten into the run's backup root, one call per root.
- *
- * `copyTree` adds and overwrites but never removes, so every managed root carries
- * the same drift the skills root does. One call per root hands the containment
- * guard and the emptied-parent walk the root that owns each file, and each root's
- * content lands under `<backupRoot>/<root-name>/<relative>`, so the recovery point
- * mirrors ~/.claude.
- *
- * Nothing moves unless a prior install recorded it. A user-authored file, a
- * runtime artifact, and a recorded path under no managed root — ~/.claude/CLAUDE.md,
- * settings.json, the manifest itself, and ~/.mypy.ini outside the home — all sit
- * outside every root's diff and stay where they are. ~/.claude/_shared and
- * ~/.claude/skills/_shared are distinct absolute paths, so the `_shared` root call
- * and the skills root call each see their own files and neither sees the other's.
- *
- * @param {string[]|null} priorInstalledFiles Files the prior manifest recorded, or null when unknown.
- * @param {string[]} currentInstalledFiles Every file this run copied.
- * @param {string} backupRoot The run's timestamped backup directory.
- * @returns {{prunedCount: number, skillsPrunedCount: number, failedPaths: string[]}}
- *   The summed count, the skills root's own count, and every path whose move failed.
- */
 function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalledFiles, backupRoot) {
     let prunedCount = 0;
     let skillsPrunedCount = 0;
@@ -2366,6 +2350,27 @@ function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalled
             skillsPrunedCount = rootOutcome.prunedCount;
         }
     }
+    for (const rootName of [MANAGED_AGENTS_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME]) {
+        const lookupRoot = join(CLAUDE_HOME, rootName);
+        const canonicalRoot = join(AGENTS_HOME, rootName);
+        const canonicalCurrentFiles = currentInstalledFiles.map(filePath =>
+            isInsideDirectory(filePath, lookupRoot)
+                ? join(canonicalRoot, relative(lookupRoot, filePath))
+                : filePath,
+        );
+        const rootOutcome = pruneStaleInstalledFiles(
+            priorInstalledFiles,
+            canonicalCurrentFiles,
+            canonicalRoot,
+            join(backupRoot, 'agents-home', rootName),
+            { managedHomeDirectory: AGENTS_HOME },
+        );
+        prunedCount += rootOutcome.prunedCount;
+        failedPaths.push(...rootOutcome.failedPaths);
+        if (rootName === MANAGED_SKILLS_DIRECTORY_NAME) {
+            skillsPrunedCount += rootOutcome.prunedCount;
+        }
+    }
     return { prunedCount, skillsPrunedCount, failedPaths };
 }
 
@@ -2655,7 +2660,9 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             );
             if (!existsSync(agentsSource)) continue;
             const agentsDestination = INSTALL_ROOT_RESOLUTION.agentsLookupDirectory;
-            const stats = copyTree(agentsSource, agentsDestination);
+            const stats = copyTree(agentsSource, agentsDestination, {
+                preserveExistingFileNames: ['poteto-agent.md'],
+            });
             if (!summary[MANAGED_AGENTS_DIRECTORY_NAME]) {
                 summary[MANAGED_AGENTS_DIRECTORY_NAME] = stats;
             } else {

package/bin/install.test.mjs

@@ -1168,6 +1168,8 @@ test('FOLDED_HOOK_RELATIVE_PATHS contains folded hooks plus retired entries', ()
 
 test('retired hook registrations stay managed so reinstall removes them', () => {
     const retiredPaths = new Set([
+        'observability/test_failure_recorder.py',
+        'advisory/msys_path_conversion_advisor.py',
         'session/untracked_repo_detector.py',
         'session/gh_pr_author_session_cleanup.py',
         'observability/pr_description_writer_spawn_tracker.py',
@@ -2023,6 +2025,25 @@ test('copyTree copies AGENTS.md with agent definitions', () => {
 });
 
 
+test('copyTree preserves an existing file named in the preserve set', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-preserve-source-'));
+    const destinationRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-preserve-destination-'));
+    try {
+        const sourceFilePath = join(sourceRoot, 'poteto-agent.md');
+        const destinationFilePath = join(destinationRoot, 'poteto-agent.md');
+        writeFileSync(sourceFilePath, 'package wrapper\n');
+        writeFileSync(destinationFilePath, 'user wrapper\n');
+
+        copyTree(sourceRoot, destinationRoot, { preserveExistingFileNames: ['poteto-agent.md'] });
+
+        assert.equal(readFileSync(destinationFilePath, 'utf8'), 'user wrapper\n');
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+        rmSync(destinationRoot, { recursive: true, force: true });
+    }
+});
+
+
 const SHIPPED_README_NAME = 'README.md';
 const INSTALLED_README_NAME = 'Readme.md';
 const RETIRED_HOOK_RELATIVE_PATH = 'blocking/retired_gate.py';

package/bin/resolve-package-managed-directory.test.mjs

@@ -26,7 +26,7 @@ import { resolvePackageManagedDirectory } from './resolve-package-managed-direct
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CANONICAL_SKILL_NAME = 'privacy-hygiene';
-const CANONICAL_AGENT_FILE_NAME = 'clean-coder.md';
+const CANONICAL_AGENT_FILE_NAME = 'AGENTS.md';
 
 test('prefers the .agents tree when both layouts exist', () => {
     const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-src-agents-'));

package/bin/subagent-model-policy.test.mjs

@@ -25,7 +25,7 @@ function advisorRoute(request, options = {}) {
     return route(request, {
         trustedSessionMetadata: {
             authorized: true,
-            registeredAgentType: 'session-advisor',
+            registeredAgentType: 'team-advisor',
         },
         ...options,
     });
@@ -55,6 +55,13 @@ test('the shipped policy parses and names native model ids', () => {
     assert.deepEqual(policy.advisorDefault, { model: 'astra', effort: 'medium' });
 });
 
+test('poteto plugin aliases use worker routing without advisor privileges', () => {
+    for (const agent_type of ['poteto-agent', 'pstack:poteto-agent']) {
+        const result = route({ agent_type, model: 'Astra', reasoning_effort: 'high' });
+        assert.deepEqual(result.selected, { model: 'gpt-6-astra', effort: 'low' });
+    }
+});
+
 test('every approved pair returns its literal native pair', () => {
     const expected = [
         [['Luna', 'high'], ['gpt-5.6-luna', 'high']],
@@ -74,7 +81,7 @@ test('every approved pair returns its literal native pair', () => {
     const advisor = advisorRoute({
         model: 'Astra',
         reasoning_effort: 'high',
-        agent_type: 'session-advisor',
+        agent_type: 'team-advisor',
     });
     assert.equal(advisor.status, 'remapped');
     assert.deepEqual(advisor.selected, { model: 'gpt-6-astra', effort: 'high' });
@@ -105,7 +112,7 @@ test('every automatic replacement returns its literal destination', () => {
 
 test('advisor and worker Astra restrictions use role-specific replacements', () => {
     assert.deepEqual(
-        advisorRoute({ model: 'Astra', reasoning_effort: 'xhigh', agent_type: 'session-advisor' }).selected,
+        advisorRoute({ model: 'Astra', reasoning_effort: 'xhigh', agent_type: 'team-advisor' }).selected,
         { model: 'gpt-6-astra', effort: 'medium' },
     );
     assert.deepEqual(
@@ -113,7 +120,7 @@ test('advisor and worker Astra restrictions use role-specific replacements', ()
         { model: 'gpt-6-astra', effort: 'low' },
     );
     assert.deepEqual(
-        advisorRoute({ model: 'Astra', reasoning_effort: 'high', agent_type: 'session-advisor' }).selected,
+        advisorRoute({ model: 'Astra', reasoning_effort: 'high', agent_type: 'team-advisor' }).selected,
         { model: 'gpt-6-astra', effort: 'high' },
     );
 });
@@ -122,7 +129,7 @@ test('registered advisor roles satisfy advisory authorization', () => {
     const result = advisorRoute({
         model: 'Astra',
         reasoning_effort: 'high',
-        agent_type: 'session-advisor',
+        agent_type: 'team-advisor',
     });
 
     assert.deepEqual(result.selected, { model: 'gpt-6-astra', effort: 'high' });
@@ -135,7 +142,7 @@ test('a policy from the first stack revision remains routable', () => {
         {
             model: 'Astra',
             reasoning_effort: 'high',
-            agent_type: 'session-advisor',
+            agent_type: 'team-advisor',
         },
         { policy: legacyPolicy },
     );
@@ -146,7 +153,7 @@ test('an advisor role claim cannot grant advisory authorization', () => {
     const result = route({
         model: 'Astra',
         reasoning_effort: 'high',
-        agent_type: 'session-advisor',
+        agent_type: 'team-advisor',
     });
     assert.equal(result.status, 'blocked');
     assert.equal(result.diagnostic, 'advisor role is not trusted');
@@ -158,7 +165,7 @@ test('Astra Light resolves to Astra Low', () => {
 });
 
 test('missing advisor settings use the policy default', () => {
-    const result = advisorRoute({ agent_type: 'session-advisor' });
+    const result = advisorRoute({ agent_type: 'team-advisor' });
     assert.deepEqual(result.selected, { model: 'gpt-6-astra', effort: 'medium' });
 });
 

package/docs/BDD_SCENARIO_QUALITY.md

@@ -6,7 +6,7 @@ Source: Smart & Molak, *BDD in Action* 2e, Chapter 7.6 — scenario quality patt
 
 ## Declarative Focus
 
-Scenarios work best when they name what users want to achieve in the language of the business. Lead with goals and recognizable domain tasks so readers grasp intent at a glance. Reserve step-level or UI detail for places where it truly clarifies behavior.
+Scenarios work best when they name what users want to achieve in the language of the business. Lead with goals and recognizable domain tasks so readers grasp intent at a glance. Reserve step-level or UI detail for places where it clarifies behavior.
 
 > "Good scenarios model business behavior, not system interactions." — Smart & Molak §7.6.3
 
@@ -42,7 +42,7 @@ Then I should be presented with the following hotels:
 
 Personas ground scenarios in realistic goals and context. Use light soap-opera personas when you need depth before full UX research: introduce names and roles as needed and deepen them across scenarios.
 
-> Smart & Molak §7.6.5 describe personas as rich, realistic descriptions: each persona captures goals, abilities, and background information that ground the test scenario in a real user context.
+> Smart & Molak §7.6.5 describe personas as rich, realistic descriptions: each persona captures goals, abilities, and background information that ground the test scenario in a user context.
 
 Good scenarios name who acts and what they need in plain language.