claude-dev-env 2.9.0 → 2.11.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/references/CLAUDE.md

@@ -8,8 +8,10 @@ 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 |
+| `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()` |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
+| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
 
 ## Role
 

package/docs/references/advisor-tool.md

@@ -1,14 +1,14 @@
 # Advisor Tool
 
-Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
+Canonical consult timing and weight for the repository advisor path: `/team-advisor` and the shared warm advisor. Anthropic's advisor documentation supplies the source guidance for packet shape and review timing.
 
 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.
 
 ## What it is
 
-`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.
+`/team-advisor` is the repository's advisor implementation. It carries the full first packet explicitly, sends later deltas, and owns the warm Agent/SendMessage or read-only Sol CLI lifecycle.
 
-When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
+See `team-advisor-skill.md` for the bind and lifecycle map.
 
 ## When to call
 
@@ -18,11 +18,11 @@ If the task needs orientation first (find files, fetch a source, see what exists
 
 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 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. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
 - **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.
+On tasks longer than a few steps, aim for an early approach consult and a completion review. Reserve a third consult for recovery or reconciliation, and add consults when material new evidence or forks arise. This cadence guides planning and leaves the task free to follow its evidence. Short reactive tasks may use the single consult that best fits the live decision.
 
 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.
 
@@ -36,16 +36,34 @@ Give the advice serious weight. If a step fails empirically, or primary-source e
 
 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?" A reconcile call is cheaper than the wrong branch.
 
+Work a disagreement in this order: keep the observed evidence in the record, name the conflict plainly, ask the advisor which constraint breaks the tie, then act on the reconciled plan.
+
+## Escalation shapes
+
+Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work, not by default to the advisor.
+
+| Shape | Fits when |
+|---|---|
+| Advisor | The task needs intermittent strategy and review, and one executor keeps the task from start to finish. |
+| Subagent | A piece of the task is a bounded subtask that benefits from its own context and its own loop. |
+| Stronger-model planning phase | The plan needs the strong model's judgment; the fast model can carry it out once written. |
+| Full model switch | Every step of the task needs the stronger tier, not just the hard decisions. |
+
+Spawn a subagent when the work is a delegable bounded subtask. Switch the whole task to the stronger model when every turn needs that tier.
+
 ## 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.)`
 
+Size the ask at roughly 80 percent of the true ceiling; direct address to the advisor lands more reliably than a third-person description.
+
 ## 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 |
+| `team-advisor-skill.md` | Standing warm advisor for this repository |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle — a read map routes each bind or consult moment to its `reference/` detail file |
+| `weak-executor-advisor.md` | Consult deltas for an executor spawned below the advisor's own tier |