@gobing-ai/spur 0.4.2 → 0.4.3

package/plugins/sp/lib/context-session-start.ts

@@ -0,0 +1,214 @@
+/**
+ * context-session-start — SessionStart hook for indexed-context.
+ *
+ * Generates a session ID, writes `.spur/context/.session.json` (tracking the current session
+ * for PostToolUse and Stop hooks), and appends a `session_start` event to `token-ledger.jsonl`.
+ * Task 0246: best-effort agent/model hints on session file + event. Task 1159: the pointer records
+ * the host-native {@link SessionOwner} that created it, so a nested child can reuse the ledger for
+ * tool recording without being able to tear it down.
+ *
+ * **Fail-open contract:** every error path exits 0 with no output.
+ *
+ * Self-contained by design (task 0232/0246).
+ *
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-session-start.ts` keeps the argv/stdin adapter.
+ */
+
+import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveAgentHint, resolveModelHint } from './agent-hint';
+import { claudeHookOwnerFromPayloadText, type SessionOwner } from './context-owner';
+import { checkContextFreshness } from './context-post-tool';
+import { getEnvVar, getEnvVars } from './env';
+
+// Owner identity + Claude payload derivation live in ./context-owner (pure, unit-testable);
+// re-exported here because this module stays the hook surface consumers reach for.
+
+/**
+ * Ancestor-run marker exported by `@gobing-ai/ts-ai-runner` ≥ 0.4.15 (`AGENT_RUN_ID_ENV`).
+ *
+ * `AiRunner` sets this in the agent subprocess environment whenever the caller supplies an
+ * `AgentRunCorrelation`, which Spur's pipeline always does
+ * (`packages/app/src/workflow/actions/agent-run.ts:148-152`) as does `spur agent run`
+ * (`packages/app/src/services/agent-service.ts:661`). execa's `extendEnv` default propagates it
+ * transitively, so every descendant of an agent run — including the hook subprocesses the host
+ * fires inside it — inherits the same value. Its mere presence answers "am I nested?" exactly.
+ *
+ * Deliberately a string literal rather than an import: this hook is self-contained by design
+ * (tasks 0232/0246) and runs both as a standalone script and from Superskill's bundled runner, so
+ * it must not depend on the workspace's module graph. The name is a published contract on the
+ * ts-ai-runner side, so a literal here is a stable coupling, not a guess.
+ */
+export const AGENT_RUN_ID_ENV = 'SPUR_RUN_ID';
+
+/**
+ * Fallback idle window for hosts and code paths that do **not** propagate a run correlation
+ * (task 0398 R3).
+ *
+ * Only consulted when {@link AGENT_RUN_ID_ENV} is absent. With ts-ai-runner ≥ 0.4.15 the
+ * agent-run path is detected exactly, so this no longer covers the case that motivated it — it
+ * remains as a backstop for nested `SessionStart` fires that arrive outside a correlated run
+ * (a host that spawns its own helper processes, or an `agent.run` invoked without a correlation).
+ *
+ * ponytail: still a wall-clock heuristic on that residual path — two genuinely distinct
+ * uncorrelated sessions started inside the window merge into one ledger session. Kept because
+ * deleting it would regress every non-correlated nesting path back to the original bug, and the
+ * set of hosts is not enumerable from here. Delete it once every nesting path is known to carry a
+ * correlation.
+ */
+export const SESSION_REUSE_IDLE_MS = 4 * 60 * 60 * 1000;
+
+interface SessionFileBody {
+    session?: unknown;
+    started?: unknown;
+}
+
+/**
+ * Return the id of the session already in flight, or null when a new one should be minted.
+ *
+ * **Why this exists (0398 R3).** `SessionStart` fires in every nested `agent.run` subprocess, not
+ * once per host session. Each firing used to mint a fresh `session-<date>-<HHMM>` id (now
+ * seconds-plus-random, 1166), append a
+ * `session_start` row, and overwrite the `.session.json` pointer that `context-post-tool` reads —
+ * so a single pipeline run registered as dozens of sessions and orphaned the parent's event
+ * stream. The H6 corpus shows the signature: 332 `session_start` against 157 `session_end` over
+ * 18 days, 298 distinct ids, 39 starts in a 2-day window that held a handful of real sessions.
+ *
+ * **Two signals, in precedence order.** (1) {@link AGENT_RUN_ID_ENV} present → definitively a
+ * descendant of an agent run: reuse the recorded session with no time bound, because a pipeline step
+ * legitimately runs for the full `implementTimeoutMs` (45 min) and longer batches for hours, so any
+ * wall-clock window would eventually split a run that is still in flight. (2) No marker → fall back
+ * to the {@link SESSION_REUSE_IDLE_MS} window on the `started` stamp, for hosts that nest without
+ * propagating a correlation. A crashed session leaves a stale `.session.json`: on (2) the idle window
+ * retires it, on (1) a stale file is only reachable from inside a live agent run, where reusing it is
+ * the correct answer anyway.
+ */
+export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
+    let body: SessionFileBody;
+    try {
+        // No in-flight session, unreadable file or corrupt pointer → mint a new one.
+        body = JSON.parse(readFileSync(join(dir, '.session.json'), 'utf-8')) as SessionFileBody;
+    } catch {
+        return null;
+    }
+
+    if (typeof body.session !== 'string' || body.session.length === 0) return null;
+
+    // Signal 1 — exact ancestry. No `started` parse, no time bound.
+    const runId = env[AGENT_RUN_ID_ENV];
+    if (typeof runId === 'string' && runId.trim().length > 0) return body.session;
+
+    // Signal 2 — residual heuristic for uncorrelated nesting.
+    if (typeof body.started !== 'string') return null;
+
+    const started = Date.parse(body.started);
+    if (Number.isNaN(started)) return null;
+
+    const idleMs = now.getTime() - started;
+    if (idleMs < 0 || idleMs > SESSION_REUSE_IDLE_MS) return null; // stale or clock-skewed → new
+
+    return body.session;
+}
+
+/**
+ * Core session-start path (testable). Returns session id on success, null on I/O failure.
+ *
+ * Idempotent per in-flight session (0398 R3): when `resolveActiveSession` finds one, this returns
+ * that id and writes nothing — no ledger row, no pointer rewrite.
+ *
+ * Ownership (task 1159): a **new** pointer records a valid `owner` only; a reused start never
+ * rewrites the pointer, so a nested child cannot take ownership from the parent that opened it,
+ * and only the recorded owner's shutdown can finalize the ledger.
+ */
+export function recordSessionStart(
+    dir: string,
+    env: NodeJS.ProcessEnv = getEnvVars(),
+    now: () => Date = () => new Date(),
+    agentFallback?: string,
+    owner?: SessionOwner,
+): string | null {
+    try {
+        mkdirSync(dir, { recursive: true });
+    } catch {
+        return null;
+    }
+
+    const at = now();
+
+    const active = resolveActiveSession(dir, at, env);
+    if (active !== null) return active;
+    const pad = (n: number) => String(n).padStart(2, '0');
+    // Uniqueness suffix (1166): minute-granular ids collided when a session started in the same
+    // minute an earlier one ended, and the frozen end algorithm then suppressed the new session's
+    // `session_end` row as a duplicate. Seconds + a random suffix make collisions practically
+    // impossible; the id stays an opaque ledger key everywhere else.
+    const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}-${randomUUID().slice(0, 8)}`;
+    const ts = at.toISOString();
+    const agent = resolveAgentHint(env, agentFallback);
+    const model = resolveModelHint(env);
+
+    const sessionBody: Record<string, unknown> = {
+        session: sessionId,
+        started: ts,
+        reads: 0,
+        writes: 0,
+        tokens: 0,
+    };
+    if (agent) sessionBody.agent = agent;
+    if (model) sessionBody.model = model;
+    const ownerId = typeof owner?.sessionId === 'string' ? owner.sessionId.trim() : '';
+    const host = owner?.host;
+    if (ownerId !== '' && (host === 'claude' || host === 'pi')) sessionBody.owner = { host, sessionId: ownerId };
+
+    const sessionFile = join(dir, '.session.json');
+    try {
+        writeFileSync(sessionFile, JSON.stringify(sessionBody));
+    } catch {
+        return null;
+    }
+
+    const startEvent: Record<string, unknown> = { ts, session: sessionId, type: 'session_start' };
+    if (agent) startEvent.agent = agent;
+    if (model) startEvent.model = model;
+
+    // Freshness check (task 0711 R4): report whether the context indexes were
+    // regenerated at the current HEAD. Best-effort, fail-open — git failures
+    // yield head=null, which marks stale only via the sidecar's own defects.
+    let headCommit: string | null = null;
+    try {
+        const out = execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const trimmed = out.trim();
+        headCommit = trimmed.length > 0 ? trimmed : null;
+    } catch {
+        headCommit = null;
+    }
+    let freshnessRaw: string | null = null;
+    try {
+        freshnessRaw = readFileSync(join(dir, '.freshness.json'), 'utf-8');
+    } catch {
+        freshnessRaw = null;
+    }
+    startEvent.contextFreshness = checkContextFreshness(freshnessRaw, headCommit);
+
+    const ledgerPath = join(dir, 'token-ledger.jsonl');
+    try {
+        appendFileSync(ledgerPath, `${JSON.stringify(startEvent)}\n`);
+    } catch {
+        return null;
+    }
+
+    return sessionId;
+}
+
+/**
+ * Open (or reuse) the session for a raw Claude stdin payload (task 1159, testable half).
+ *
+ * Malformed/absent text still opens the session ownerless (legacy policy); the dir resolution lives
+ * here rather than in the entrypoint so the untestable subprocess body stays a few lines.
+ */
+export function recordSessionStartFromPayloadText(text: string, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
+    return recordSessionStart(dir, env, undefined, undefined, claudeHookOwnerFromPayloadText(text, env) ?? undefined);
+}

package/plugins/sp/lib/context-session-stop.ts

@@ -0,0 +1,196 @@
+/**
+ * context-session-stop — SessionEnd hook for indexed-context (session teardown).
+ *
+ * Scans `token-ledger.jsonl` for the current session's events, computes rollup totals, appends
+ * a `session_end` event, and cleans up `.session.json`. Registered on SessionEnd (not Stop) so it
+ * runs once at true session teardown: on Claude Code the rollup counts the whole session (Stop fired
+ * per-turn and tore down after turn 1), and on Pi/omp it maps to `session_shutdown` — off the
+ * `agent_end`/Stop event where blocking gates (e.g. cc/anti-hallucination) live and would collide.
+ *
+ * **Owner-gated finalization (task 1159).** A nested `agent.run` reuses its parent's pointer but
+ * used to finalize and delete it on its own shutdown, so every later parent tool event landed in a
+ * dead ledger. Shutdown now proceeds only when the caller's host-native identity equals the owner
+ * recorded on the pointer, so a child's shutdown is a no-op.
+ *
+ * **Fail-open contract:** every error path — missing `.spur/context/`, missing/unparseable
+ * `.session.json`, write failure — exits 0 with no output.
+ *
+ * Self-contained by design (task 0232). Installed hook configs use the portable
+ * `superskill hook run sp context-session-stop` entrypoint.
+ *
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-session-stop.ts` keeps the argv/stdin adapter.
+ */
+
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+// Type-only import: erased at bundle time, so this hook keeps its minimal
+// node:fs/node:path/env dependency surface (sp-plugin-standalone contract).
+import type { SessionOwner } from './context-owner';
+import { claudeHookOwnerFromPayloadText } from './context-owner';
+import { getEnvVar, getEnvVars } from './env';
+
+interface LedgerEvent {
+    session: string;
+    type: string;
+    tokens?: number;
+}
+
+interface SessionPointer {
+    session?: unknown;
+    owner?: unknown;
+}
+
+/** Parse and validate an owner read from the pointer or supplied by a caller. */
+function validSessionOwner(raw: unknown): SessionOwner | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const host = (raw as { host?: unknown }).host;
+    const sessionId = (raw as { sessionId?: unknown }).sessionId;
+    if (host !== 'claude' && host !== 'pi') return null;
+    if (typeof sessionId !== 'string') return null;
+    const trimmed = sessionId.trim();
+    return trimmed.length > 0 ? { host, sessionId: trimmed } : null;
+}
+
+function sameOwner(a: SessionOwner, b: SessionOwner): boolean {
+    return a.host === b.host && a.sessionId === b.sessionId;
+}
+
+/** Read and validate the private session pointer, or null when absent/corrupt. */
+function readPointer(sessionFile: string): SessionPointer | null {
+    if (!existsSync(sessionFile)) return null;
+    try {
+        return JSON.parse(readFileSync(sessionFile, 'utf-8')) as SessionPointer;
+    } catch {
+        return null;
+    }
+}
+
+/** Scan the token-ledger JSONL for this session's events and compute rollup totals. */
+function computeSessionTotals(
+    ledgerPath: string,
+    sessionId: string,
+): { reads: number; writes: number; tokens: number } {
+    let reads = 0;
+    let writes = 0;
+    let tokens = 0;
+    let lines: string[];
+    try {
+        lines = readFileSync(ledgerPath, 'utf-8').split('\n');
+    } catch {
+        return { reads, writes, tokens }; // missing/unreadable ledger → zero totals
+    }
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+            const evt = JSON.parse(line) as LedgerEvent;
+            if (evt.session !== sessionId) continue;
+            if (evt.type === 'read') reads++;
+            else if (evt.type === 'write') writes++;
+            if (evt.tokens) tokens += evt.tokens;
+        } catch {
+            // skip unparseable lines
+        }
+    }
+    return { reads, writes, tokens };
+}
+
+/** Return the existing `session_end` row for `sessionId`, or null when the ledger has none. */
+function findSessionEnd(ledgerPath: string, sessionId: string): Record<string, unknown> | null {
+    let lines: string[];
+    try {
+        lines = readFileSync(ledgerPath, 'utf-8').split('\n');
+    } catch {
+        return null;
+    }
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+            const evt = JSON.parse(line) as Record<string, unknown>;
+            if (evt.type === 'session_end' && evt.session === sessionId) return evt;
+        } catch {
+            // skip unparseable lines
+        }
+    }
+    return null;
+}
+
+/**
+ * Finalize one session (task 0969 R3; owner-gated task 1159): read the `.session.json` pointer,
+ * compute the session's rollup totals, append the `session_end` row, remove the pointer
+ * (best-effort) and return the event. Shared by this hook's entrypoint and Pi's `session_shutdown`
+ * so both hosts roll up identically. Returns null on every fail-open path.
+ *
+ * `caller` is the identity of the process firing shutdown. Finalization requires it to be a valid
+ * identity that **equals** the pointer's recorded owner; a missing/mismatched/malformed caller, a
+ * legacy ownerless pointer or a corrupt pointer all return null with no writes and no removal.
+ * Ownerless pointers stay readable and reusable for tool recording — the bounded legacy policy is
+ * that an unattributable session is retired by the existing idle-start expiry, never claimed here.
+ *
+ * Repeat safety: before appending, an existing `session_end` row for the ledger suppresses a
+ * second one, so a replay after a failed pointer cleanup neither duplicates the row nor strands the
+ * pointer. Removal re-reads the pointer and requires both the ledger id and the owner to be
+ * unchanged, so a pointer replaced since the first read is left untouched.
+ */
+export function recordSessionEnd(
+    dir: string,
+    now: () => Date = () => new Date(),
+    caller?: SessionOwner,
+): Record<string, unknown> | null {
+    const sessionFile = join(dir, '.session.json');
+    const pointer = readPointer(sessionFile);
+    if (!pointer) return null;
+
+    const sessionId = typeof pointer.session === 'string' ? pointer.session : '';
+    if (!sessionId) return null;
+
+    // Ownership gate: only the identity recorded at creation may finalize or remove.
+    const pointerOwner = validSessionOwner(pointer.owner);
+    const callerOwner = validSessionOwner(caller);
+    if (!pointerOwner || !callerOwner || !sameOwner(pointerOwner, callerOwner)) return null;
+
+    const ledgerPath = join(dir, 'token-ledger.jsonl');
+
+    let event: Record<string, unknown>;
+    const existing = findSessionEnd(ledgerPath, sessionId);
+    if (existing) {
+        // Replay: the end row survived an earlier failed pointer cleanup. Retry the removal below
+        // without appending a duplicate.
+        event = existing;
+    } else {
+        const totals = computeSessionTotals(ledgerPath, sessionId);
+        event = { ts: now().toISOString(), session: sessionId, type: 'session_end', totals };
+        try {
+            appendFileSync(ledgerPath, `${JSON.stringify(event)}\n`);
+        } catch {
+            return null; // retain the pointer so a later owning shutdown can retry
+        }
+    }
+
+    // Remove only the exact pointer finalized above: re-read and require the ledger id and owner
+    // to be unchanged, so a pointer replaced during recording survives.
+    try {
+        const current = readPointer(sessionFile);
+        const currentOwner = current ? validSessionOwner(current.owner) : null;
+        if (current?.session === sessionId && currentOwner && sameOwner(currentOwner, pointerOwner)) {
+            rmSync(sessionFile, { force: true });
+        }
+    } catch {
+        // cleanup is best-effort
+    }
+
+    return event;
+}
+
+/**
+ * Finalize the session for a raw Claude stdin payload (task 1159, testable half).
+ *
+ * Malformed/absent text carries no identity, so shutdown fails closed; the dir resolution lives here
+ * rather than in the entrypoint so the untestable subprocess body stays a few lines.
+ */
+export function recordSessionEndFromPayloadText(
+    text: string,
+    env: NodeJS.ProcessEnv = getEnvVars(),
+): Record<string, unknown> | null {
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
+    return recordSessionEnd(dir, undefined, claudeHookOwnerFromPayloadText(text, env) ?? undefined);
+}

package/plugins/sp/lib/dogfood-pipeline.ts

@@ -0,0 +1,265 @@
+/**
+ * dogfood pipeline-driving detection — the pure detector core.
+ *
+ * Extracted from `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts` (task 1173, plan
+ * P7/ADR-130): the reusable detection logic lives in lib, and the script keeps only the live
+ * Phase 1.0 CLI gate. Callers and tests may keep importing the script — it re-exports this module.
+ *
+ * Contract (0274 §3 dogfood-pipeline-detect, 0277 R1):
+ *   - Word-boundary matchers with `-` treated as a word char (NOT a boundary).
+ *     A token counts only when it is a distinct hyphen-word, not when it is a
+ *     substring of a longer alphanumeric or hyphen run. This removes the
+ *     leading-space dependency of the @1.1 prose detector.
+ *   - Two token shapes, both with strict `[^\w-]` boundaries:
+ *       (a) complete tokens — `--next`, `dev-run`, `dev-runall`, `dev-wrap`,
+ *           `dev-wrapall`, `dev-idea` — matched as whole hyphen-words so the
+ *           slash form `/sp:dev-run` matches on its `dev-run` tail whether or
+ *           not it is preceded by a space, but `--next` does NOT match inside
+ *           `--next-gen` (the trailing `-gen` breaks the boundary).
+ *       (b) bare nouns — `run`, `runall`, `wrap`, `wrapall`, `idea` — matched
+ *           only as standalone words, so `run` matches in
+ *           `bun ... task run 0042` but NOT inside `runaway`/`prerun`, and
+ *           `idea` does NOT match inside `idealist`/`ideal`.
+ *   - Listing both shapes is what makes the detector leading-space invariant
+ *     (the slash form is caught by its `dev-*` tail; the bare noun is caught
+ *     when it appears as its own word) without letting `run` leak into every
+ *     `-run-` identifier.
+ *
+ * Non-goals of detectPipelineDriving: decides ambiguity only. It does NOT decide
+ * observe vs fix — any explicit `--max-retry` value proceeds regardless.
+ * Implement-heavy advisory is a separate helper (detectImplementHeavy).
+ */
+
+/**
+ * Tokens whose presence makes a testee pipeline-driving. Ordered for stable
+ * diagnostics. Two shapes per the contract above: complete `dev-*` / `--next`
+ * tokens first, then bare nouns.
+ */
+const PIPELINE_TOKENS = [
+    '--next',
+    'dev-runall',
+    'dev-wrapall',
+    'dev-refineall',
+    'dev-verifyall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'refineall',
+    'verifyall',
+    'runall',
+    'wrapall',
+    'run',
+    'wrap',
+    'idea',
+] as const;
+
+/** Refuse message when pipeline-driving and `--max-retry` was not passed (exact string). */
+export const PIPELINE_DRIVING_REFUSE_MESSAGE =
+    '⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)';
+
+/**
+ * Refuse message when the testee carries a mutating `--fix` mode (`--fix all` /
+ * `--fix blockers-first`) and `--max-retry` was not passed. A mutating fix mode
+ * mutates the working tree independent of pipeline-driving (task 0293 R1/R2):
+ * `--max-retry 0` bounds the **driver** only — the testee's own `--fix` pass
+ * still mutates the tree — so the message must not imply otherwise.
+ */
+export const MUTATING_FIX_REFUSE_MESSAGE =
+    '⚠ mutating --fix mode detected (--fix all | --fix blockers-first); pass --max-retry 0 (observe-only for the driver; the testee still mutates the tree) or --max-retry N (fix mode, driver + testee both mutate)';
+
+/** Advisory when pipeline-driving + implement-heavy derived steps (exact string). */
+export const IMPLEMENT_HEAVY_ADVISORY_MESSAGE =
+    '⚠ implement-heavy pipeline dogfood: prefer --max-retry 0 (observe-only) or step-split; operator --max-retry N overrides';
+
+/**
+ * Tokens that mark a derived step as implement-heavy (mutates product/code or
+ * drives a mutating pipeline leg). Deliberately excludes verify/review/unit-only
+ * surfaces even when they carry `--next`.
+ */
+const IMPLEMENT_HEAVY_TOKENS = [
+    'dev-runall',
+    'dev-wrapall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'runall',
+    'wrapall',
+    // bare `run` / `wrap` / `idea` — only when not clearly a non-mutating surface
+    'run',
+    'wrap',
+    'idea',
+    'implement',
+] as const;
+
+/**
+ * A verify/review surface stops being non-mutating the moment it carries a
+ * repair mode: `--fix all` / `--fix blockers-first` applies Edit/Write repairs
+ * to the working tree (0280 dogfood, finding P2). `--fix none` stays
+ * observational. Boundary-guarded so `--prefix all` / `--focus all` never match.
+ * Exported so the Phase 1.0 gate and tests share one matcher (task 0293 R1/R4).
+ */
+export function hasMutatingFixMode(step: string): boolean {
+    return /(?<![\w-])--fix[=\s]+(all|blockers-first)(?![\w-])/i.test(step);
+}
+
+/**
+ * Match a token at a word boundary. A "word boundary" here is the position
+ * between a non-`[\w-]` char (or string start) and the token, and between the
+ * token and a non-`[\w-]` char (or string end). Treating `-` as a word char
+ * is what makes `--next` reject `--next-gen` and `dev-run` reject `dev-runner`.
+ */
+function tokenMatches(testee: string, token: string): boolean {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // (?<![\w-]) — not preceded by a word char or hyphen.
+    // (?![\w-])  — not followed by a word char or hyphen.
+    const re = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, 'i');
+    return re.test(testee);
+}
+
+/**
+ * Returns whether the testee string is pipeline-driving (contains any of the
+ * pipeline-driving tokens as a distinct hyphen-word). Machine-checked
+ * counterpart of the prose list in SKILL.md §Pipeline-driving detection and
+ * dev-dogfood.md.
+ */
+export function detectPipelineDriving(testee: string): boolean {
+    if (typeof testee !== 'string' || testee.length === 0) {
+        return false;
+    }
+    return PIPELINE_TOKENS.some((token) => tokenMatches(testee, token));
+}
+
+/**
+ * True when a single step label (or the whole testee) is implement-heavy —
+ * it chains into real implementation / wrap / idea work, not verify-only.
+ *
+ * Non-mutating surfaces (`dev-verify`, `dev-review`, `dev-unit`, plain
+ * `dev-refine` without a further run) are never implement-heavy even if
+ * pipeline-driving via `--next` — UNLESS they carry a mutating repair mode
+ * (`--fix all` / `--fix blockers-first`), which turns the verify/review leg
+ * into a tree-mutating fix pass (0280 dogfood, finding P2).
+ */
+export function isImplementHeavyStep(step: string): boolean {
+    if (typeof step !== 'string' || step.length === 0) return false;
+    // Explicit non-mutating surfaces win unless a mutating token co-occurs.
+    const nonMutatingOnly =
+        tokenMatches(step, 'dev-verify') || tokenMatches(step, 'dev-review') || tokenMatches(step, 'dev-unit');
+    const hasMutating = IMPLEMENT_HEAVY_TOKENS.some((token) => tokenMatches(step, token)) || hasMutatingFixMode(step);
+    if (nonMutatingOnly && !hasMutating) return false;
+    // refine alone is planning, not implement-heavy; refine+run/--next chain is.
+    if (tokenMatches(step, 'dev-refine') && !hasMutating && !tokenMatches(step, '--next')) {
+        return false;
+    }
+    if (tokenMatches(step, 'dev-refine') && tokenMatches(step, '--next')) {
+        // refine --next chains into run → implement-heavy
+        return true;
+    }
+    return hasMutating;
+}
+
+/**
+ * True when the testee is implement-heavy: it carries a pipeline-driving token,
+ * a mutating `--fix` mode, OR at least one derived step (or the testee itself
+ * when no steps given) is implement-heavy. Used for the W8 Phase 1 advisory
+ * after step derivation.
+ *
+ * Task 0293 R3: a mutating `--fix` mode alone is implement-heavy even with no
+ * pipeline token — the verify/review leg itself becomes a tree-mutating fix
+ * pass.
+ */
+export function detectImplementHeavy(testee: string, derivedSteps: string[] = []): boolean {
+    if (isImplementHeavyStep(testee)) return true;
+    if (!detectPipelineDriving(testee)) return false;
+    return derivedSteps.some((step) => isImplementHeavyStep(step));
+}
+
+export interface GateResult {
+    pipelineDriving: boolean;
+    mutatingFix: boolean;
+    maxRetryPresent: boolean;
+    implementHeavy: boolean;
+    refuse: boolean;
+    advisory: boolean;
+    message: string | null;
+    exitCode: 0 | 1 | 2;
+}
+
+/**
+ * Phase 1.0 + W8 gate decision. Pure — no I/O. The CLI wrapper prints and exits.
+ *
+ * Refuse condition (task 0293 R1) is the union of two **independent** mutation
+ * sources, each gated on `!maxRetryPresent`:
+ *
+ *   1. pipeline-driving testee (`--next`, `dev-run`, …) — refuses because the
+ *      testee chains lifecycle legs whose cumulative blast radius the driver
+ *      cannot pre-attribute.
+ *   2. mutating `--fix` mode (`--fix all` / `--fix blockers-first`) — refuses
+ *      because the testee itself applies Edit/Write repairs even with no
+ *      pipeline token. `--max-retry 0` bounds the **driver** only; the testee
+ *      still mutates (honesty note in MUTATING_FIX_REFUSE_MESSAGE).
+ *
+ * Pipeline-driving is reported first when both co-occur (its refuse message is
+ * the superset — chain + tree mutation).
+ */
+export function evaluateDogfoodGate(
+    testee: string,
+    options: { maxRetryPresent?: boolean; steps?: string[] } = {},
+): GateResult {
+    const maxRetryPresent = options.maxRetryPresent === true;
+    const steps = options.steps ?? [];
+    const pipelineDriving = detectPipelineDriving(testee);
+    const mutatingFix = hasMutatingFixMode(testee);
+    const implementHeavy = detectImplementHeavy(testee, steps);
+
+    if (pipelineDriving && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: PIPELINE_DRIVING_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (mutatingFix && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: MUTATING_FIX_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (implementHeavy) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: false,
+            advisory: true,
+            message: IMPLEMENT_HEAVY_ADVISORY_MESSAGE,
+            exitCode: 0,
+        };
+    }
+
+    return {
+        pipelineDriving,
+        mutatingFix,
+        maxRetryPresent,
+        implementHeavy,
+        refuse: false,
+        advisory: false,
+        message: null,
+        exitCode: 0,
+    };
+}
+
+export { PIPELINE_TOKENS };