claude-dev-env 2.8.0 → 2.10.0

package/bin/resolve-install-root.mjs

@@ -0,0 +1,181 @@
+/**
+ * Pure install-root resolver for the claude-dev-env installer.
+ *
+ * Precedence (highest first):
+ *   1. explicitTarget — CLI --target or a caller-supplied absolute path
+ *   2. CLAUDE_CONFIG_DIR from the environment (profile isolation root)
+ *   3. join(homeDirectory, '.claude') — main-profile default
+ *
+ * CLAUDE_HOME is never honored as a profile root.
+ */
+
+import { homedir } from 'node:os';
+import { join, normalize, resolve, sep } from 'node:path';
+import { MYPY_INI_FILE_NAME } from './install-constants.mjs';
+
+export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
+export const DEFAULT_CLAUDE_DIRECTORY_NAME = '.claude';
+export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
+
+/**
+ * @typedef {{
+ *   explicitTarget?: string | null,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   homeDirectory?: string,
+ * }} ResolveInstallRootOptions
+ */
+
+/**
+ * @typedef {{
+ *   managedRoot: string,
+ *   source: 'explicit-target' | 'claude-config-dir' | 'default-home',
+ *   homeDirectory: string,
+ *   manifestFilePath: string,
+ *   mypyIniInstallPath: string,
+ *   allDeclaredExternalPaths: string[],
+ * }} InstallRootResolution
+ */
+
+/**
+ * Resolve the managed install root and declared external destinations.
+ *
+ * @param {ResolveInstallRootOptions} [options]
+ * @returns {InstallRootResolution}
+ */
+export function resolveInstallRoot(options = {}) {
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const environment = options.environment ?? process.env;
+    const explicitTarget = normalizeOptionalPath(options.explicitTarget);
+
+    /** @type {InstallRootResolution['source']} */
+    let source;
+    /** @type {string} */
+    let managedRoot;
+
+    if (explicitTarget) {
+        managedRoot = explicitTarget;
+        source = 'explicit-target';
+    } else {
+        const configDir = normalizeOptionalPath(
+            environment[CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE],
+        );
+        if (configDir) {
+            managedRoot = configDir;
+            source = 'claude-config-dir';
+        } else {
+            managedRoot = resolve(join(homeDirectory, DEFAULT_CLAUDE_DIRECTORY_NAME));
+            source = 'default-home';
+        }
+    }
+
+    const mypyIniInstallPath = resolve(join(homeDirectory, MYPY_INI_FILE_NAME));
+    return {
+        managedRoot,
+        source,
+        homeDirectory: resolve(homeDirectory),
+        manifestFilePath: join(managedRoot, MANIFEST_FILE_NAME),
+        mypyIniInstallPath,
+        allDeclaredExternalPaths: [mypyIniInstallPath],
+    };
+}
+
+/**
+ * True when candidatePath is the managed root or a descendant of it.
+ * Requires a separator boundary so `.claude-extra` is not inside `.claude`.
+ *
+ * @param {string} candidatePath
+ * @param {string} managedRoot
+ * @returns {boolean}
+ */
+export function isPathWithinManagedRoot(candidatePath, managedRoot) {
+    if (!candidatePath || !managedRoot) {
+        return false;
+    }
+    const normalizedCandidate = normalizePathForComparison(candidatePath);
+    const normalizedRoot = normalizePathForComparison(managedRoot);
+    if (normalizedCandidate === normalizedRoot) {
+        return true;
+    }
+    const rootWithSeparator = normalizedRoot.endsWith('/')
+        ? normalizedRoot
+        : `${normalizedRoot}/`;
+    return normalizedCandidate.startsWith(rootWithSeparator);
+}
+
+/**
+ * True when a write destination is allowed: inside the managed root or on
+ * the declared external allowlist (today: ~/.mypy.ini under the home dir).
+ *
+ * @param {string} candidatePath
+ * @param {InstallRootResolution} resolution
+ * @returns {boolean}
+ */
+export function isAllowedInstallDestination(candidatePath, resolution) {
+    if (isPathWithinManagedRoot(candidatePath, resolution.managedRoot)) {
+        return true;
+    }
+    const normalizedCandidate = normalizePathForComparison(candidatePath);
+    return resolution.allDeclaredExternalPaths.some(
+        (eachExternalPath) => normalizePathForComparison(eachExternalPath) === normalizedCandidate,
+    );
+}
+
+/**
+ * Parse an explicit --target value from argv tokens.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+export function parseExplicitTargetFromArgv(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--target') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--target requires a path argument');
+            }
+            return value;
+        }
+        if (token.startsWith('--target=')) {
+            const value = token.slice('--target='.length);
+            if (!value) {
+                throw new Error('--target requires a path argument');
+            }
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string | null | undefined} maybePath
+ * @returns {string | null}
+ */
+function normalizeOptionalPath(maybePath) {
+    if (typeof maybePath !== 'string') {
+        return null;
+    }
+    const trimmed = maybePath.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return resolve(trimmed);
+}
+
+/**
+ * Compare-key for a filesystem path: resolve, forward-slash, case-fold on win32.
+ *
+ * @param {string} filesystemPath
+ * @returns {string}
+ */
+export function normalizePathForComparison(filesystemPath) {
+    const resolved = resolve(normalize(filesystemPath));
+    let withForwardSlashes = resolved.split(sep).join('/');
+    if (process.platform === 'win32') {
+        withForwardSlashes = withForwardSlashes.toLowerCase();
+    }
+    if (withForwardSlashes.length > 1 && withForwardSlashes.endsWith('/')) {
+        withForwardSlashes = withForwardSlashes.slice(0, -1);
+    }
+    return withForwardSlashes;
+}

package/bin/select-install-targets.mjs

@@ -0,0 +1,401 @@
+/**
+ * Pure install-target selection for single-profile and selected multi-profile runs.
+ *
+ * Selection finishes before any filesystem mutation. The caller injects the
+ * profiles root and the profile-id → directoryName map so tests need no live
+ * env or disk fixtures.
+ */
+
+import { join, resolve, isAbsolute, normalize } from 'node:path';
+import {
+    resolveInstallRoot,
+    parseExplicitTargetFromArgv,
+    normalizePathForComparison,
+} from './resolve-install-root.mjs';
+
+export const MAIN_DEFAULT_TARGET_IDENTITY = 'main';
+export const TARGET_IDENTITY_FLAG = '--target-identity';
+export const PROFILE_FLAG = '--profile';
+export const PROFILES_FLAG = '--profiles';
+export const DEFAULT_PROFILES_ROOT_DIRECTORY_NAME = '.claude-profiles';
+export const PROFILES_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PROFILES_ROOT';
+
+/**
+ * @typedef {{
+ *   mode: 'main-default' | 'explicit-path' | 'profiles' | 'child-identity',
+ *   allProfileIds: string[],
+ *   explicitTarget: string | null,
+ *   targetIdentity: string | null,
+ * }} InstallTargetSelection
+ */
+
+/**
+ * @typedef {{
+ *   targetIdentity: string,
+ *   managedRoot: string,
+ *   source: string,
+ *   profileId: string | null,
+ * }} ResolvedInstallTarget
+ */
+
+/**
+ * Parse target-selection flags from argv. Does not resolve paths.
+ *
+ * Rejects ambiguous combinations (path target + profile), empty profile lists,
+ * and a child hop that still carries profile flags.
+ *
+ * @param {string[]} argv
+ * @returns {InstallTargetSelection}
+ */
+export function parseInstallTargetSelectionFromArgv(argv) {
+    const explicitTarget = parseExplicitTargetFromArgv(argv);
+    const targetIdentity = parseTargetIdentityFromArgv(argv);
+    const allProfileIds = parseProfileIdsFromArgv(argv);
+    const hasProfileFlags = allProfileIds.length > 0
+        || argvIncludesFlag(argv, PROFILE_FLAG)
+        || argvIncludesFlag(argv, PROFILES_FLAG);
+
+    if (targetIdentity && hasProfileFlags) {
+        throw new Error(
+            'child install hop rejects --profile/--profiles when --target-identity is set',
+        );
+    }
+    if (explicitTarget && hasProfileFlags) {
+        throw new Error(
+            'ambiguous targets: use either --target <path> or --profile/--profiles, not both',
+        );
+    }
+    if (hasProfileFlags && allProfileIds.length === 0) {
+        throw new Error('--profile/--profiles requires at least one profile id');
+    }
+    if (allProfileIds.length > 0) {
+        const allDuplicates = findDuplicateStrings(allProfileIds);
+        if (allDuplicates.length > 0) {
+            throw new Error(`duplicate profile id(s): ${allDuplicates.join(', ')}`);
+        }
+        return {
+            mode: 'profiles',
+            allProfileIds,
+            explicitTarget: null,
+            targetIdentity: null,
+        };
+    }
+    if (targetIdentity) {
+        return {
+            mode: 'child-identity',
+            allProfileIds: [],
+            explicitTarget,
+            targetIdentity,
+        };
+    }
+    if (explicitTarget) {
+        return {
+            mode: 'explicit-path',
+            allProfileIds: [],
+            explicitTarget,
+            targetIdentity: null,
+        };
+    }
+    return {
+        mode: 'main-default',
+        allProfileIds: [],
+        explicitTarget: null,
+        targetIdentity: null,
+    };
+}
+
+/**
+ * Resolve the ordered list of install targets from a parsed selection.
+ *
+ * Dedupes on the resolved managed root path (case-insensitive on Windows) so
+ * `--target` and a profile that names the same directory cannot both run.
+ * Sanitizes each profile directoryName: absolute paths and `..` segments fail.
+ *
+ * @param {InstallTargetSelection} selection
+ * @param {{
+ *   homeDirectory: string,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   profilesRoot?: string | null,
+ *   directoryNameByProfileId?: Record<string, string>,
+ * }} options
+ * @returns {ResolvedInstallTarget[]}
+ */
+export function resolveInstallTargets(selection, options) {
+    const environment = options.environment ?? {};
+    const homeDirectory = options.homeDirectory;
+    const directoryNameByProfileId = options.directoryNameByProfileId ?? {};
+
+    if (selection.mode === 'profiles') {
+        const profilesRoot = resolveProfilesRootDirectory({
+            homeDirectory,
+            environment,
+            profilesRoot: options.profilesRoot,
+        });
+        /** @type {ResolvedInstallTarget[]} */
+        const allTargets = [];
+        for (const eachProfileId of selection.allProfileIds) {
+            const directoryName = directoryNameByProfileId[eachProfileId];
+            if (typeof directoryName !== 'string' || !directoryName.trim()) {
+                throw new Error(`unknown profile id: ${eachProfileId}`);
+            }
+            const safeDirectoryName = assertSafeProfileDirectoryName(directoryName);
+            const managedRoot = resolve(join(profilesRoot, safeDirectoryName));
+            allTargets.push({
+                targetIdentity: eachProfileId,
+                managedRoot,
+                source: 'selected-profile',
+                profileId: eachProfileId,
+            });
+        }
+        return dedupeTargetsByManagedRoot(allTargets);
+    }
+
+    const explicitTarget = selection.mode === 'main-default' ? null : selection.explicitTarget;
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment,
+        explicitTarget,
+    });
+    const isChildIdentity = selection.mode === 'child-identity';
+    return [{
+        targetIdentity: isChildIdentity
+            ? (selection.targetIdentity ?? MAIN_DEFAULT_TARGET_IDENTITY)
+            : MAIN_DEFAULT_TARGET_IDENTITY,
+        managedRoot: resolution.managedRoot,
+        source: resolution.source,
+        profileId: isChildIdentity ? selection.targetIdentity : null,
+    }];
+}
+
+/**
+ * Build the per-target ownership manifest record.
+ *
+ * @param {{
+ *   packageName: string,
+ *   packageVersion: string,
+ *   targetIdentity: string,
+ *   managedRoot: string,
+ *   files: string[],
+ *   skills?: string[] | null,
+ *   installedAt?: string,
+ * }} parameters
+ * @returns {Record<string, unknown>}
+ */
+export function buildTargetManifestRecord(parameters) {
+    /** @type {Record<string, unknown>} */
+    const manifest = {
+        package: parameters.packageName,
+        version: parameters.packageVersion,
+        installedAt: parameters.installedAt ?? new Date().toISOString(),
+        targetIdentity: parameters.targetIdentity,
+        managedRoot: parameters.managedRoot,
+        files: parameters.files,
+    };
+    if (parameters.skills) {
+        manifest.skills = parameters.skills;
+    }
+    return manifest;
+}
+
+/**
+ * Strip target-selection flags so group parsing sees only install flags.
+ *
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+export function stripTargetSelectionFlagsFromArgv(argv) {
+    /** @type {string[]} */
+    const remaining = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === PROFILE_FLAG || token === PROFILES_FLAG || token === TARGET_IDENTITY_FLAG) {
+            const value = argv[index + 1];
+            if (value && !value.startsWith('--')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (
+            token.startsWith(`${PROFILE_FLAG}=`)
+            || token.startsWith(`${PROFILES_FLAG}=`)
+            || token.startsWith(`${TARGET_IDENTITY_FLAG}=`)
+        ) {
+            continue;
+        }
+        if (token === '--target') {
+            const value = argv[index + 1];
+            if (value && !value.startsWith('--')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (token.startsWith('--target=')) {
+            continue;
+        }
+        remaining.push(token);
+    }
+    return remaining;
+}
+
+/**
+ * @param {{
+ *   homeDirectory: string,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   profilesRoot?: string | null,
+ * }} options
+ * @returns {string}
+ */
+export function resolveProfilesRootDirectory(options) {
+    if (typeof options.profilesRoot === 'string' && options.profilesRoot.trim()) {
+        return resolve(options.profilesRoot);
+    }
+    const environment = options.environment ?? {};
+    const fromEnvironment = environment[PROFILES_ROOT_ENVIRONMENT_VARIABLE];
+    if (typeof fromEnvironment === 'string' && fromEnvironment.trim()) {
+        return resolve(fromEnvironment.trim());
+    }
+    return resolve(join(options.homeDirectory, DEFAULT_PROFILES_ROOT_DIRECTORY_NAME));
+}
+
+/**
+ * Reject absolute and parent-hop directoryName values on every host platform.
+ *
+ * Host `isAbsolute` plus Windows drive and UNC spellings so a Linux CI host
+ * still rejects a profile map that smuggles an absolute Windows path.
+ *
+ * @param {string} directoryName
+ * @returns {string}
+ */
+export function assertSafeProfileDirectoryName(directoryName) {
+    const trimmed = directoryName.trim();
+    if (!trimmed) {
+        throw new Error('profile directoryName must be a non-empty relative name');
+    }
+    const hasWindowsDriveAbsolute = /^[A-Za-z]:[\\/]/.test(trimmed);
+    const hasWindowsUncAbsolute = trimmed.startsWith('\\\\') || trimmed.startsWith('//');
+    if (isAbsolute(trimmed) || hasWindowsDriveAbsolute || hasWindowsUncAbsolute) {
+        throw new Error(`profile directoryName must be relative, got absolute: ${trimmed}`);
+    }
+    const allSegments = normalize(trimmed).split(/[/\\]/).filter(Boolean);
+    if (allSegments.some((eachSegment) => eachSegment === '..')) {
+        throw new Error(`profile directoryName rejects parent segments: ${trimmed}`);
+    }
+    return trimmed;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function parseProfileIdsFromArgv(argv) {
+    /** @type {string[]} */
+    const allProfileIds = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === PROFILE_FLAG || token === PROFILES_FLAG) {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error(`${token} requires a comma-separated profile id list`);
+            }
+            allProfileIds.push(...splitProfileIdList(value));
+            index += 1;
+            continue;
+        }
+        if (token.startsWith(`${PROFILE_FLAG}=`) || token.startsWith(`${PROFILES_FLAG}=`)) {
+            const prefix = token.startsWith(`${PROFILE_FLAG}=`)
+                ? `${PROFILE_FLAG}=`
+                : `${PROFILES_FLAG}=`;
+            const value = token.slice(prefix.length);
+            if (!value) {
+                throw new Error(`${prefix.slice(0, -1)} requires a comma-separated profile id list`);
+            }
+            allProfileIds.push(...splitProfileIdList(value));
+        }
+    }
+    return allProfileIds;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function parseTargetIdentityFromArgv(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === TARGET_IDENTITY_FLAG) {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error(`${TARGET_IDENTITY_FLAG} requires an identity argument`);
+            }
+            return value;
+        }
+        if (token.startsWith(`${TARGET_IDENTITY_FLAG}=`)) {
+            const value = token.slice(`${TARGET_IDENTITY_FLAG}=`.length);
+            if (!value) {
+                throw new Error(`${TARGET_IDENTITY_FLAG} requires an identity argument`);
+            }
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string} rawList
+ * @returns {string[]}
+ */
+function splitProfileIdList(rawList) {
+    return rawList
+        .split(',')
+        .map((eachId) => eachId.trim())
+        .filter((eachId) => eachId.length > 0);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {string} flagName
+ * @returns {boolean}
+ */
+function argvIncludesFlag(argv, flagName) {
+    return argv.some(
+        (eachToken) => eachToken === flagName || eachToken.startsWith(`${flagName}=`),
+    );
+}
+
+/**
+ * @param {string[]} allValues
+ * @returns {string[]}
+ */
+function findDuplicateStrings(allValues) {
+    const seen = new Set();
+    const allDuplicates = new Set();
+    for (const eachValue of allValues) {
+        if (seen.has(eachValue)) {
+            allDuplicates.add(eachValue);
+        }
+        seen.add(eachValue);
+    }
+    return [...allDuplicates];
+}
+
+/**
+ * @param {ResolvedInstallTarget[]} allTargets
+ * @returns {ResolvedInstallTarget[]}
+ */
+function dedupeTargetsByManagedRoot(allTargets) {
+    const seenRootByKey = new Map();
+    /** @type {ResolvedInstallTarget[]} */
+    const uniqueTargets = [];
+    for (const eachTarget of allTargets) {
+        const rootKey = normalizePathForComparison(eachTarget.managedRoot);
+        if (seenRootByKey.has(rootKey)) {
+            const priorIdentity = seenRootByKey.get(rootKey);
+            throw new Error(
+                `duplicate managed root for targets ${priorIdentity} and ${eachTarget.targetIdentity}: ${eachTarget.managedRoot}`,
+            );
+        }
+        seenRootByKey.set(rootKey, eachTarget.targetIdentity);
+        uniqueTargets.push(eachTarget);
+    }
+    return uniqueTargets;
+}

package/commands/CLAUDE.md

@@ -11,12 +11,10 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
 | `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
 | `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
-| `initialize.md` | `/initialize` | Bootstraps a new project with standard Claude Code config |
 | `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
 | `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
 | `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
 | `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
-| `stubcheck.md` | `/stubcheck` | Finds stub bodies (`pass`/`...`/`raise NotImplementedError`) in the diff |
 | `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
 
 ## Format

package/docs/CODE_RULES.md

@@ -1,6 +1,8 @@
 # Code Rules Reference
 
-Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only.
+Compact **projection** of the repository-root canonical policy [`AGENTS.md`](../../../AGENTS.md). When this file and `AGENTS.md` disagree, **`AGENTS.md` wins** — update this projection in the same change.
+
+⚡ marks rules enforced by hand-maintained `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only. Session policy (question routing, task tracking) lives in `rules/*.md`; see [`code-standards.md`](../rules/code-standards.md).
 
 ---
 
@@ -46,7 +48,7 @@ Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` fo
 
 ## 6. COMPLETE TYPE HINTS
 
-ALL parameters typed, ALL returns typed. No `Any`, no `# type: ignore` (also enforced by the mypy_validator.py hook).
+ALL parameters typed, ALL returns typed. No `Any`. A `# type: ignore` is allowed only with a second trailing `#` justification of at least five characters (e.g. `# type: ignore[misc]  # stubs missing in foo library`); bare ignores are blocked by `code_rules_enforcer.py`. Prefer fixing the type over an ignore when a real annotation is available.
 
 ## 6.5 FILE LENGTH GUIDANCE
 

package/docs/references/CLAUDE.md

@@ -8,8 +8,9 @@ Pointer documents to external sources, standard terminology, and internal tool o
 |---|---|
 | `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
 | `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
-| `advisor-tool.md` | The `advisor()` tool: a no-parameter review call that forwards the full conversation history to a stronger reviewer model, and when to call it |
-| `team-advisor-skill.md` | The `/team-advisor` skill: spawning a standing review agent at the strongest reachable tier, and how it relates to the `advisor()` tool |
+| `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
+| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and how it pairs with `advisor()` |
 
 ## Role
 

package/docs/references/advisor-tool.md

@@ -1,13 +1,51 @@
 # Advisor Tool
 
-`advisor()` is a review tool backed by a stronger reviewer model. It takes no parameters — calling it forwards the entire conversation history automatically, so the reviewer sees the task, every tool call made, and every result seen so far.
+Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
 
-## When to call it
+Source bones: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (Suggested system prompt for coding tasks). API shape, model pairs, cost, and caching live there. This file carries only the call rules a session needs every time.
 
-Call `advisor()` before substantive work: before writing, before committing to an interpretation, before building on an assumption. Orientation work — finding files, fetching a source, seeing what exists — comes first; call `advisor()` once that orientation is done and before the substantive step begins.
+## What it is
 
-Treat the advisor as more experienced than the calling agent. Consult it whenever a path forward is uncertain.
+`advisor()` is a no-parameter review call. The platform forwards the full conversation (task, tool calls, results) to a stronger model. The executor continues with that guidance.
 
-## Availability
+When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
 
-`advisor()` is present only in environments where it has been configured as a tool. Check the available tools before relying on it; when it is absent, fall back to `/team-advisor` (see `team-advisor-skill.md` in this directory).
+## When to call
+
+Call **before substantive work** — before writing, before locking an interpretation, before building on an assumption.
+
+If the task needs orientation first (find files, fetch a source, see what exists), do that, then call. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call:
+
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not.
+- **When stuck** — errors recur, approach does not converge, results do not fit.
+- **When considering a change of approach.**
+
+On tasks longer than a few steps, call at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you do not need repeated calls — most value is on the first call, before the approach hardens.
+
+Call for design, architecture, and risk questions where you will not touch a file. If the response would be analysis or a recommendation with no other tool calls, call first. That judgment is where a second opinion is highest value. Simple factual lookups and arithmetic do not need a call.
+
+## Hard rule
+
+Your first write, edit, or state-changing shell call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation (`ls`, `cat`, `grep`, `find`, and harness equivalents) is not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
+
+## How to treat advice
+
+Give the advice serious weight. If a step fails empirically, or primary-source evidence contradicts a claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it is evidence the test does not check what the advice is checking.
+
+If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw the evidence but may have underweighted it; a reconcile call is cheaper than the wrong branch.
+
+## Brevity cue
+
+When the consult path supports a free-text brief, append:
+
+`(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`
+
+## Related
+
+| Doc | Holds |
+|---|---|
+| [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | API shape, model pairs, cost, caching, full best practices |
+| `team-advisor-skill.md` | Standing warm advisor when `advisor()` is missing |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle, executor paste blocks |