tickmarkr 1.84.0 → 1.86.0

package/dist/brand.d.ts

@@ -16,7 +16,11 @@ export declare function bannerShell(): string;
 export declare const TICKMARKR_EXIT_TRAILER = "printf '\\nTICKMARKR_''EXIT:%s\\n' $?";
 /** OBS-50: visible-pane bootstrap script — banner + agent command + byte-identical exit trailer. */
 export declare function paneDispatchScript(body: string[]): string;
-/** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
+/** Record that the command being passed directly to ExecutorDriver.run is a daemon-built launch. */
+export declare function paneLaunchCommand(command: string): string;
+/** Driver-side half of paneLaunchCommand's one-shot handoff. */
+export declare function consumePaneLaunchIntent(): boolean;
+/** OBS-50/342: one short, intent-bearing pane-run line; bootstrap lives beside the prompt. */
 export declare function paneDispatchCommand(scriptPath: string): string;
 /** The settled brand green ramp (256-color), bright → deep. */
 export declare const BRAND_RAMP: readonly [84, 78, 41, 35];

package/dist/brand.js

@@ -78,9 +78,25 @@ export const TICKMARKR_EXIT_TRAILER = `printf '\\nTICKMARKR_''EXIT:%s\\n' $?`;
 export function paneDispatchScript(body) {
     return ["export BASH_SILENCE_DEPRECATION_WARNING=1", ...body, TICKMARKR_EXIT_TRAILER].join("\n");
 }
-/** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
+const pendingPaneLaunchIntents = [];
+/** Record that the command being passed directly to ExecutorDriver.run is a daemon-built launch. */
+export function paneLaunchCommand(command) {
+    const intent = { kind: "launch" };
+    pendingPaneLaunchIntents.push(intent);
+    queueMicrotask(() => {
+        const index = pendingPaneLaunchIntents.indexOf(intent);
+        if (index >= 0)
+            pendingPaneLaunchIntents.splice(index, 1);
+    });
+    return command;
+}
+/** Driver-side half of paneLaunchCommand's one-shot handoff. */
+export function consumePaneLaunchIntent() {
+    return pendingPaneLaunchIntents.shift()?.kind === "launch";
+}
+/** OBS-50/342: one short, intent-bearing pane-run line; bootstrap lives beside the prompt. */
 export function paneDispatchCommand(scriptPath) {
-    return `bash ${shq(scriptPath)}`;
+    return paneLaunchCommand(`bash ${shq(scriptPath)}`);
 }
 // ── design system (v1.50) ── contract: docs/codebase/CLI-DESIGN.md ──────────
 // Every cockpit surface styles through these tokens/glyphs/helpers. Styled only

package/dist/cli/commands/doctor.d.ts

@@ -1,9 +1,12 @@
 import { type ClaudeAlias } from "../../adapters/claude-code.js";
 import type { WorkerAdapter } from "../../adapters/types.js";
 import { type KimiDoctorTurnResult } from "../../adapters/kimi.js";
+import { type CatalogReadResult } from "../../adapters/catalog-remote.js";
 export type DoctorOpts = {
     banner?: boolean;
     kimiTurnProbe?: (cwd: string) => Promise<KimiDoctorTurnResult>;
     resolveClaudeAliasIdentity?: (cwd: string, alias: ClaudeAlias) => string | undefined;
+    catalog?: CatalogReadResult;
+    catalogNow?: () => Date;
 };
 export declare function doctor(_argv: string[], cwd?: string, adapters?: WorkerAdapter[], opts?: DoctorOpts): Promise<string>;

package/dist/cli/commands/doctor.js

@@ -1,19 +1,29 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
+import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { CLAUDE_ALIAS_IDENTITY_STAMPS, claudeCode, resolveClaudeAliasIdentity } from "../../adapters/claude-code.js";
 import { BANNER, dim, fail, kvRow, legend, ok, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
-import { declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
-import { DEFAULT_CONFIG, loadConfig, overlayPreferShapes } from "../../config/config.js";
+import { catalogModelAdvisory, declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
+import { loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
 import { kimi, probeKimiDoctorTurn } from "../../adapters/kimi.js";
 import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
+import { readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const alignedStatusRow = (verdict, key, value) => `  ${statusRow(verdict, kvRow(key, value).slice(2))}`;
 const attentionRow = (text) => `  ${statusRow("warn", text)}`;
 export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(), opts = {}) {
+    if (_argv.length === 1 && _argv[0] === "--refresh-catalog") {
+        const refreshed = await refreshCatalogCommand({ repoRoot: cwd, now: opts.catalogNow });
+        return refreshed.updated
+            ? `tickmarkr doctor --refresh-catalog: model catalog refreshed${refreshed.warning ? `; ${refreshed.warning}` : ""}`
+            : `tickmarkr doctor --refresh-catalog: catalog refresh unavailable — ${refreshed.warning ?? "unknown failure"}; retained ${refreshed.catalog.source} catalog`;
+    }
     const cfg = loadConfig(cwd);
+    // T17: synchronous/cache-only by operator ruling. The only network-bearing catalog function is the
+    // separately invoked refreshCatalogCommand; ordinary doctor never calls it.
+    const catalog = opts.catalog ?? readCachedCatalog(cwd, { now: opts.catalogNow });
     // banner at START — the logo greets the operator before the ~60s probe wait, never trailing it (operator report 2026-07-17)
     if (opts.banner !== false && visual())
         process.stdout.write(BANNER);
@@ -72,8 +82,12 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         const healthy = h.installed && (a.id !== kimi.id || h.authed);
         return alignedStatusRow(healthy ? "pass" : "fail", a.id, state);
     });
-    // v1.48 T1: advisory sweep for known agent CLIs with no adapter — never written to doctor.json health.
-    rows.push(...detectCandidateClis().map(({ binary, version }) => alignedStatusRow("warn", binary, `detected: ${version ?? "version unknown"} (no tickmarkr adapter — not routable)`)));
+    if (catalog.warning) {
+        rows.push(attentionRow(`model catalog cache unreadable — ${catalog.warning}; using vendored fallback (advisory — routing unchanged)`));
+    }
+    // v1.48 T1 / v1.86 T12: advisory sweep for known agent CLIs with no drive contract. Presence is
+    // resolved through the worker's login shell; advisory targets are never executed or written to health.
+    rows.push(...detectCandidateClis({ cwd }).map(({ binary, path }) => alignedStatusRow("warn", binary, `detected at ${path} (no drive contract — not routable)`)));
     const herdr = HerdrDriver.available();
     rows.push(alignedStatusRow(herdr ? "pass" : "fail", "herdr", herdr ? "driver available (HERDR_ENV=1)" : "not detected — subprocess driver will be used"));
     // v1.22 T5: workspace-trust pre-flight — per installed adapter: trusted | seeded | action-required | n/a.
@@ -143,10 +157,23 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             }
         }
     }
+    const resolvedCatalogModel = (adapter, model) => {
+        if (adapter !== "claude-code" || !identityResolver || !(model in CLAUDE_ALIAS_IDENTITY_STAMPS))
+            return undefined;
+        try {
+            return identityResolver(cwd, model);
+        }
+        catch {
+            return undefined;
+        }
+    };
     // MODEL-05/06: print-only drift fragment; advisory, whole-line-commented additions, tickmarkr NEVER applies it.
     // TTY gets a one-line summary + the fragment as a file (the full dump drowned everything else,
     // v1.33.1 onboarding); machine/CI surface keeps the inline dump — layout is pinned by tests.
-    const frag = suggestOverlay(cfg, health, adapters, stateDirName(cwd));
+    const frag = suggestOverlay(cfg, health, adapters, stateDirName(cwd), {
+        catalog,
+        resolvedModel: resolvedCatalogModel,
+    });
     let drift = "";
     if (frag) {
         if (visual()) {
@@ -191,24 +218,19 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
                 : "";
             rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)}${windowCol} ${auth}  ${dim("denied=")}${denied}  ${dim("prefer=")}${pref}`);
         }
-        if (unclassified.length)
+        if (unclassified.length) {
+            // Keep the historical count as an index, but it is no longer the whole report: every model gets
+            // a cache-backed evidence or explicit uncovered line. Neither branch changes cfg, health, or route().
             rows.push(`    ${dim(`(${unclassified.length} more listed, unclassified)`)}`);
+            for (const model of unclassified) {
+                const advisory = catalogModelAdvisory(cfg, catalog, a.id, model, resolvedCatalogModel(a.id, model));
+                rows.push(`    ${dim(`catalog · ${advisory.display}`)}`);
+            }
+        }
         return rows;
     });
-    const autoPrefer = readAutoPrefer(cwd);
-    const preferStatus = autoPrefer
-        ? Object.keys(cfg.routing.map).flatMap((shape) => {
-            const auto = autoPrefer[shape];
-            if (!Array.isArray(auto))
-                return [];
-            const seed = DEFAULT_CONFIG.routing.map[shape]?.prefer ?? [];
-            if (!auto.length && !seed.length)
-                return []; // nothing derived, nothing seeded — an empty line is noise
-            return [`    ${dim(`prefer ${shape} (auto):`)} ${auto.join(" > ")} ${dim("— seed was")} [${seed.join(", ")}]`];
-        })
-        : [];
-    const modelSummary = modelStatus.length || preferStatus.length
-        ? `\n${legend("model status:")}\n${[...modelStatus, ...preferStatus].join("\n")}`
+    const modelSummary = modelStatus.length
+        ? `\n${legend("model status:")}\n${modelStatus.join("\n")}`
         : "";
     const header = visual()
         ? `${statusRow("pass", `${title("tickmarkr doctor")} ${legend("· capability matrix")}`)}\n${rule()}`

package/dist/cli/commands/fleet.d.ts

@@ -15,6 +15,13 @@ export type FleetIO = {
     debug?: boolean;
     reloadGuard?: (bytes: string) => string | null;
 };
+export type FleetWriteHooks = {
+    readPrior?: (path: string) => string;
+    beforeRename?: () => void;
+};
+/** Atomic sibling-temp writer. Reading and serializing happen before `${path}.tmp` exists, and
+ * any pre-rename interruption unlinks only that exact candidate while the original remains intact. */
+export declare function writeFleetOverlay(path: string, serialize: (priorBytes: string) => string, hooks?: FleetWriteHooks): void;
 export declare function fleet(argv: string[], cwd?: string, adapters?: WorkerAdapter[], io?: FleetIO): Promise<string | {
     out: string;
     code: number;

package/dist/cli/commands/fleet.js

@@ -1,9 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parseArgs } from "node:util";
-import { allAdapters, discoverChannels, doctorAgeMs, initDoctorReuse, readAutoPrefer } from "../../adapters/registry.js";
+import { allAdapters, discoverChannels, doctorAgeMs, initDoctorReuse } from "../../adapters/registry.js";
 import { fleetUnclassifiedModels } from "../../adapters/model-lints.js";
-import { fleetEditableFromConfig, fleetEditableEquals, fleetRepoOverlayFromDelta, formatFleetPrint, globalConfigDir, harvestFleetProvenance, overlayBytesLoadError, overlayPreferShapes, readOverlayFile, repoOverlayPath, repoOverlayYaml, ROUTING_MODES, unifiedYamlDiff, } from "../../config/config.js";
+import { fleetEditableFromConfig, fleetEditableEquals, formatFleetPrint, globalConfigDir, overlayBytesLoadError, renderFleetOverlayWrite, repoOverlayPath, ROUTING_MODES, unifiedYamlDiff, } from "../../config/config.js";
+import { projectFleetWhy, renderFleetWhy } from "../../config/fleet-why.js";
 import { SHAPES, TIERS } from "../../graph/schema.js";
 import { candidateRow, costSignal, shapeCandidates } from "./fleet-picker.js";
 import { route } from "../../route/router.js";
@@ -36,26 +37,30 @@ function currentRepoOverlayText(repoRoot) {
     const p = repoOverlayPath(repoRoot);
     return existsSync(p) ? readFileSync(p, "utf8") : "";
 }
-function provenanceMap(editable) {
-    const out = {};
-    for (const [adapter, models] of Object.entries(editable.tiers)) {
-        for (const [model, v] of Object.entries(models)) {
-            if (v?.provenance) {
-                out[adapter] ??= {};
-                out[adapter][model] = v.provenance;
-            }
+/** Atomic sibling-temp writer. Reading and serializing happen before `${path}.tmp` exists, and
+ * any pre-rename interruption unlinks only that exact candidate while the original remains intact. */
+export function writeFleetOverlay(path, serialize, hooks = {}) {
+    const prior = hooks.readPrior
+        ? hooks.readPrior(path)
+        : (existsSync(path) ? readFileSync(path, "utf8") : "");
+    const bytes = serialize(prior);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    try {
+        writeFileSync(tmp, bytes);
+        hooks.beforeRename?.();
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
         }
+        catch {
+            // Preserve the write failure; cleanup is constrained to the exact sibling candidate.
+        }
+        throw error;
     }
-    return out;
-}
-// v1.51 T4: serializeFleetOverlay predates routing.mode — splice the mode line under routing:
-// so a repo-declared mode survives fleet writes and a mode selection lands as routing.mode.
-function withModeLine(yaml, mode) {
-    if (!mode)
-        return yaml;
-    if (/^routing:$/m.test(yaml))
-        return yaml.replace(/^routing:$/m, `routing:\n  mode: ${mode}`);
-    return `routing:\n  mode: ${mode}\n${yaml}`;
 }
 function formatFleetSteering(cfg) {
     const blocks = [];
@@ -76,12 +81,14 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         args: argv,
         options: {
             print: { type: "boolean" },
+            why: { type: "boolean" },
             "global-dir": { type: "string" },
             fresh: { type: "boolean" },
         },
     });
     const globalDir = values["global-dir"] ?? globalConfigDir();
     const print = values.print ?? false;
+    const why = values.why ?? false;
     const input = io.input ?? process.stdin;
     const output = io.output ?? process.stdout;
     const interactive = input.isTTY === true && output.isTTY === true;
@@ -95,7 +102,7 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         // not from another parse of either raw overlay.
         return `${body.slice(0, nl)}\n# mode: ${rm.mode.mode} (${rm.source})${body.slice(nl)}${formatFleetSteering(rm.cfg)}`;
     }
-    if (!interactive)
+    if (!why && !interactive)
         return { out: NON_TTY_MSG, code: 1 };
     const fresh = values.fresh ?? false;
     const { reuse, health: cached } = initDoctorReuse(cwd, fresh);
@@ -107,10 +114,7 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
     }
     const rm = resolveRunMode(cwd, { globalDir });
     const cfg = rm.cfg;
-    // OBS-88: harvest existing `# note` comments from the overlay bytes at session load — the
-    // session must know about every prior note, not only its own edits, or the next write strips them
-    const harvested = harvestFleetProvenance(currentRepoOverlayText(cwd));
-    const initial = fleetEditableFromConfig(cfg, harvested.tiers);
+    const initial = fleetEditableFromConfig(cfg);
     const editable = structuredClone(initial);
     const health = cached;
     const modelGroups = adapters
@@ -183,21 +187,52 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
                 : ["    (no floor changes)"]),
         ];
     };
-    const autoPrefer = readAutoPrefer(cwd);
-    const overlayShapes = overlayPreferShapes(cwd, { globalDir });
-    const routedShapeRows = (mode, map) => SHAPES.map((shape) => {
-        let now;
-        try {
-            const routed = route(previewTask(shape), previewCfg(mode, map), channels, profile, undefined, undefined, PREVIEW_EXPLORE);
-            const assignment = routed.assignment;
-            now = `${assignment.adapter}:${assignment.model} (${assignment.channel}, ${assignment.tier})  ${costSignal(assignment, cfg.pricing)}`;
-        }
-        catch (error) {
-            now = error.message;
+    const whyDeclaration = (shape, mode, map, mapProducedValue) => {
+        const mapChanged = JSON.stringify(map[shape] ?? {}) !== JSON.stringify(editable.map[shape] ?? {});
+        if (mapProducedValue) {
+            return mapChanged
+                ? { operatorPinned: true }
+                : { declaredAt: `routing.map.${shape}` };
         }
-        const auto = autoPrefer?.[shape] && !overlayShapes.has(shape) ? "  (auto-prefer active)" : "";
-        return { id: shape, label: `${shape}  →  ${now}${auto}` };
-    });
+        const floorSource = modeCfgs[mode].mode.provenance[shape];
+        if (floorSource === undefined)
+            return {};
+        if (floorSource === "config floors")
+            return { declaredAt: `routing.floors.${shape}` };
+        if (mode !== rm.mode.mode)
+            return { operatorPinned: true };
+        return rm.source === "default"
+            ? { declaredAt: `routing.floors.${shape}` }
+            : { declaredAt: "routing.mode" };
+    };
+    const projectedShapeRows = (mode, map) => {
+        const values = SHAPES.map((shape) => {
+            try {
+                const routed = route(previewTask(shape), previewCfg(mode, map), channels, profile, undefined, undefined, PREVIEW_EXPLORE);
+                const assignment = routed.assignment;
+                const effective = `${assignment.adapter}:${assignment.model} (${assignment.channel}, ${assignment.tier})  ${costSignal(assignment, cfg.pricing)}`;
+                const mapProducedValue = map[shape]?.pin !== undefined || routed.provenance.includes("via prefer");
+                return {
+                    id: shape,
+                    effective,
+                    ...whyDeclaration(shape, mode, map, mapProducedValue),
+                };
+            }
+            catch (error) {
+                const mapProducedValue = map[shape]?.pin !== undefined || (map[shape]?.prefer?.length ?? 0) > 0;
+                return {
+                    id: shape,
+                    effective: error.message,
+                    ...whyDeclaration(shape, mode, map, mapProducedValue),
+                    setupCommand: "tickmarkr fleet",
+                };
+            }
+        });
+        return projectFleetWhy(values, { repoRoot: cwd, globalDir });
+    };
+    const routedShapeRows = (mode, map) => projectedShapeRows(mode, map).map(({ id, label }) => ({ id, label }));
+    if (why)
+        return renderFleetWhy(projectedShapeRows(rm.mode.mode, editable.map));
     const candidatesForShape = (shape, mode, map) => shapeCandidates(previewTask(shape), previewCfg(mode, map), channels, profile).map((candidate) => ({
         id: `${candidate.assignment.adapter}:${candidate.assignment.model}`,
         label: candidateRow(candidate, cfg.pricing),
@@ -220,6 +255,7 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         const discovered = which === "review" ? [...reviewAdapters, ...seats] : seats;
         return [...discovered, ...current.filter((entry) => !discovered.includes(entry))];
     };
+    let pendingWrite = null;
     const reviewOverlay = (state) => {
         const staged = structuredClone(initial);
         staged.denyAdapters = state.denyAdapters;
@@ -237,42 +273,24 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         // the diff and asks for confirmation, but owns neither filesystem access nor a writer.
         const before = currentRepoOverlayText(cwd);
         const path = repoOverlayPath(cwd);
-        const existing = readOverlayFile(path);
         const modeChanged = state.selectedMode !== rm.mode.mode;
-        const writeMode = modeChanged
-            ? state.selectedMode
-            : existing.routing?.mode;
-        const merged = fleetEditableEquals(initial, staged)
-            ? structuredClone(existing)
-            : fleetRepoOverlayFromDelta(initial, staged, existing);
-        let steeringChanged = false;
-        for (const key of ["review", "consult"]) {
-            if (JSON.stringify(state.steering[key]) === JSON.stringify(initialSteering[key]))
-                continue;
-            steeringChanged = true;
-            const block = { ...merged[key] };
-            if (state.steering[key])
-                block.prefer = state.steering[key];
-            else
-                delete block.prefer;
-            if (Object.keys(block).length)
-                merged[key] = block;
-            else
-                delete merged[key];
-        }
-        const tierNotes = structuredClone(harvested.tiers);
-        for (const [adapter, models] of Object.entries(provenanceMap(staged))) {
-            for (const [model, note] of Object.entries(models)) {
-                (tierNotes[adapter] ??= {})[model] = note;
-            }
+        const steeringChanged = ["review", "consult"].some((key) => JSON.stringify(state.steering[key]) !== JSON.stringify(initialSteering[key]));
+        if (!modeChanged && !steeringChanged && fleetEditableEquals(initial, staged)) {
+            pendingWrite = null;
+            return { kind: "empty" };
         }
-        const after = withModeLine(repoOverlayYaml(merged, tierNotes, {
-            adapters: harvested.denyAdapters,
-            models: harvested.denyModels,
-        }), writeMode);
-        if ((!modeChanged && !steeringChanged && fleetEditableEquals(initial, staged)) || before === after) {
+        const write = {
+            initial,
+            edited: staged,
+            ...(modeChanged ? { mode: state.selectedMode } : {}),
+            steering: { initial: initialSteering, edited: state.steering },
+        };
+        const after = renderFleetOverlayWrite(before, write);
+        if (before === after) {
+            pendingWrite = null;
             return { kind: "empty" };
         }
+        pendingWrite = write;
         return {
             kind: "diff",
             before,
@@ -348,7 +366,9 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(),
         return "fleet: discarded overlay changes";
     // The command remains the single config actuator. Every interactive edit reaches this
     // one write only after the component-rendered diff confirm and the production reload guard.
-    mkdirSync(dirname(result.review.path), { recursive: true });
-    writeFileSync(result.review.path, result.review.after);
+    const write = pendingWrite;
+    if (!write)
+        throw new Error("fleet write reached confirmation without a staged overlay mutation");
+    writeFleetOverlay(result.review.path, (prior) => renderFleetOverlayWrite(prior, write));
     return `fleet: wrote ${result.review.path}`;
 }

package/dist/cli/commands/init.js

@@ -109,6 +109,43 @@ A run is green only when the run-end event exists in the journal AND tip verify
 ### Verified handoffs
 
 When relaying missions between agents, never use bare send-text (\`herdr agent send\` / pane send-text) — it omits Enter. Use \`herdr pane run <pane> "<message>"\` or \`herdr notification show "<message>"\`. Confirm delivery by reading the target pane afterward; never report "relayed" without read-back.
+
+### Orient before you act — this block may be the ONLY guidance your host loaded
+
+These same bytes are written into EVERY repository guidance file this project has, because hosts disagree
+about which one they read: some load only \`AGENTS.md\`, some also load a repo-level guidance file, some load
+a user-level one instead. **Anything stated in only one file is invisible to some agent.** So do not assume
+you were handed the whole picture — list the repository root, open every guidance file present, and then:
+
+- **Read your host's PROJECT MEMORY before starting.** Hosts that keep one store it under a per-project
+  state directory keyed by the absolute working-directory path; find it and read its index plus every entry
+  whose name concerns METHOD or DISCIPLINE. It holds rules that cost real defects to learn. Entries may
+  predate a project rename, so **search by CONCEPT, not by the current product name.** A memory nobody opens
+  is worse than none: every seat assumes the lesson is recorded somewhere and no seat looks.
+- **The gates are the product.** Seven, defined in \`src/graph/schema.ts\`:
+  \`build test lint evidence scope acceptance review\`. **That is DECLARATION order, not execution order** —
+  the first five run as a battery that stops at its first red, then \`acceptance\` and \`review\` run
+  CONCURRENTLY (\`run-gates.ts:39\`, *"judge ‖ review"*). The first five are MANDATORY; only \`acceptance\` and
+  \`review\` may be omitted per task. Implementations are in \`src/gates/\` — \`baseline.ts\` (build/test/lint,
+  diffed against a recorded baseline so pre-existing failures are forgiven), \`evidence.ts\`, \`scope.ts\`,
+  \`acceptance.ts\` (its judge reads the DIFF and every criterion must cite a changed hunk), \`review.ts\`
+  (cross-vendor). \`run-gates.ts\` drives them. **A declared gate is not a passed gate, and a gate that
+  returned zero findings is not the same as a gate that ran.**
+- **Spec-authoring law ships in the spec template** that \`tickmarkr init\` writes: the hard bounds and which
+  direction each moves, what makes a criterion real, and why an absence or a source-text grep is never a
+  criterion. Read it before authoring or repairing acceptance items.
+- **Editing \`src/gates/\`, \`src/compile/\` or \`src/graph/\`?** Read \`docs/codebase/ARCHITECTURE.md\` first.
+- **EVERY fix gets a ship/no-ship decision, recorded, at the moment it is made.** Ask one question of each
+  one: *does a user hit this defect?* If yes, the fix belongs in \`src/**\` or \`skills/**\` — the only trees
+  the package carries (\`files: [dist, schema, skills, fixtures]\`). A script, overlay, config entry or
+  operator-side workaround that resolves the symptom **locally is not the fix; it is a decision to leave
+  every other user broken**, and it must say so in writing and name the condition that removes it.
+  **The default answer is SHIP.** A local remedy is the exception and carries the burden of proof.
+  Watch for the three shapes this hides in: a fix applied where you happened to be standing rather than
+  where the defect lives; an observation filed with a product fix named in its own text and queued
+  nowhere; and a local tool that quietly grows into a product feature nobody shipped. **A defect and its
+  fix must be recorded in the same place, or the queue silently becomes a list of things everyone assumed
+  someone else had shipped.**
 ${DOCS_END}
 `;
 // Every applicable host location gets the skills, each paired with its own repository guidance
@@ -120,6 +157,54 @@ const hostTargets = (cwd) => {
         targets.push({ skillsDir: join(cwd, ".claude", "skills"), docPath: join(cwd, "CLAUDE.md") });
     return targets;
 };
+const packagedSkillDir = (skill) => fileURLToPath(new URL(`../../../skills/${skill}`, import.meta.url));
+// Every file the package ships for a skill, DERIVED from the tree rather than listed. OBS-373: a script
+// was added to the shipped overseer skill long after repos had installed it, and because the SKILL.md
+// that MANDATES that script was already on disk, every existence check reported "installed" while the
+// thing the skill tells you to run was absent. A literal list here would be the same closed-set-restated
+// defect one layer down, so this walks instead.
+function skillFileList(root, prefix = "") {
+    return readdirSync(root, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap((entry) => {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        return entry.isDirectory() ? skillFileList(join(root, entry.name), rel) : [rel];
+    });
+}
+// Drift is only computed for skills that ARE installed. A skill never installed is not drift — `--agent`
+// installs it and says so, and nagging about it would bury the case this exists for.
+function skillDrift(cwd) {
+    const drifted = [];
+    for (const { skillsDir } of hostTargets(cwd)) {
+        for (const skill of AGENT_SKILLS) {
+            const dir = join(skillsDir, skill);
+            if (!existsSync(join(dir, "SKILL.md")))
+                continue;
+            const src = packagedSkillDir(skill);
+            const missing = [];
+            const modified = [];
+            for (const rel of skillFileList(src)) {
+                // readFileSync resolves symlinks, so a symlinked mirror compares equal to a copied one.
+                if (!existsSync(join(dir, rel)))
+                    missing.push(rel);
+                else if (!readFileSync(join(dir, rel)).equals(readFileSync(join(src, rel))))
+                    modified.push(rel);
+            }
+            if (missing.length || modified.length)
+                drifted.push({ skill, dir, missing, modified });
+        }
+    }
+    return drifted;
+}
+// Name what drifted. "stale" alone sends the reader to diff three directories by hand, and the file that
+// matters is usually the one they never knew shipped.
+const describeDrift = (d) => [
+    d.missing.length ? `missing ${d.missing.join(", ")}` : "",
+    d.modified.length ? `modified ${d.modified.join(", ")}` : "",
+].filter(Boolean).join(", ");
+// PRESENCE, deliberately — the wizard's question is "install these?", and a repo that already has them
+// should not be asked again just because a copy drifted. Staleness is a different question with a
+// different answer (`--agent --force`), and it is reported by name on every init path below.
 const skillsInstalled = (cwd) => hostTargets(cwd).every((t) => AGENT_SKILLS.every((s) => existsSync(join(t.skillsDir, s, "SKILL.md"))));
 const wizardDriverDefault = () => process.env.HERDR_ENV === "1" ? "herdr" : "auto";
 async function installAgentFiles(cwd, force, docs, notes) {
@@ -132,12 +217,20 @@ async function installAgentFiles(cwd, force, docs, notes) {
         return /^(?:y|yes)$/i.test((await prompt.question(`${question} [y/N] `)).trim());
     };
     try {
+        const drift = skillDrift(cwd);
         for (const { skillsDir, docPath } of hostTargets(cwd)) {
             for (const skill of AGENT_SKILLS) {
                 const dest = join(skillsDir, skill, "SKILL.md");
                 const exists = existsSync(dest);
-                if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
-                    notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
+                const stale = drift.find((d) => d.dir === join(skillsDir, skill));
+                // An install that already matches the package byte for byte needs no prompt and no write. Before
+                // this, every re-init asked to overwrite a current skill and the answer meant nothing either way.
+                if (exists && !stale) {
+                    notes.push(`kept current ${dest}`);
+                    continue;
+                }
+                if (exists && !force && !(await confirm(`Overwrite ${dest} (${describeDrift(stale)})?`))) {
+                    notes.push(`skipped existing ${dest} — ${describeDrift(stale)}; pass --force to overwrite it`);
                     continue;
                 }
                 // whole skill dir, not just SKILL.md — the overseer ships its pane-watcher script
@@ -145,9 +238,21 @@ async function installAgentFiles(cwd, force, docs, notes) {
                 notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
             }
             const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
-            if (current.includes(DOCS_BEGIN) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs begin -->`)
-                || current.includes(DOCS_END) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs end -->`)) {
-                notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
+            // The block is CANONICAL guidance ("stated once here, restated nowhere"), so a repo that has
+            // run init once must still be able to receive corrections to it. Before v1.86 this branch only
+            // ever said "kept", with no lever — not even --force, which IS honoured for skills above. So
+            // the block was write-once and every later improvement reached new repos only. Under --force,
+            // replace the marked region in place and leave every human-authored line outside it untouched.
+            const marked = new RegExp(`<!-- (?:tickmarkr|${LEGACY_PREFIX}):agent-docs begin -->[\\s\\S]*?`
+                + `<!-- (?:tickmarkr|${LEGACY_PREFIX}):agent-docs end -->`);
+            if (marked.test(current)) {
+                if (force) {
+                    writeFileSync(docPath, current.replace(marked, AGENT_DOCS.trimEnd()));
+                    notes.push(`refreshed tickmarkr agent docs in ${docPath}`);
+                }
+                else {
+                    notes.push(`kept existing tickmarkr agent docs in ${docPath}; pass --force to refresh them`);
+                }
             }
             else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
                 appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
@@ -249,6 +354,14 @@ export async function init(argv, cwd = process.cwd()) {
             notes.push(`wrote ${specPath}`);
         }
     }
+    // Say it on EVERY init, not only the --agent path. The upgrade that produced OBS-373 is silent by
+    // shape: the package moves, the installed copy does not, and nothing in the repo changes to hint at it.
+    // --agent reports drift per skill below, so this only speaks when that path will not.
+    if (!values.agent) {
+        for (const d of skillDrift(cwd)) {
+            notes.push(`stale ${join(d.dir, "SKILL.md")} — ${describeDrift(d)}; run tickmarkr init --agent --force to refresh it`);
+        }
+    }
     const fresh = values.fresh ?? false;
     const { reuse, ageMs, health } = initDoctorReuse(cwd, fresh);
     const doc = reuse && health && ageMs !== null