@sabaiway/agent-workflow-kit 14.34.0 → 14.36.0

package/tools/recommendations.mjs

@@ -55,7 +55,7 @@ import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-re
 import { probeSandboxMasks, needsMasksApply, patternToRel } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
-import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, GATES_REL, LCOV_PRODUCER_KEY } from './gates-declaration.mjs';
+import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, LCOV_PRODUCER_KEY } from './gates-declaration.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 // The typed channel's READ-ONLY leaf only — never tools/mcp.mjs, which reaches the write core.
 import {
@@ -87,7 +87,8 @@ import { ATTRIBUTION_KEY, LEGACY_ATTRIBUTION_KEY, attributionHidesText, effectiv
 import { planGlobalRemoval } from './hide-footprint.mjs';
 import { NODE_EVIDENCE, NODE_EVIDENCE_SCRIPTS, probeNodeEvidence } from './node-evidence.mjs';
 // The vehicle READINESS comes from the read-only half — the same survey `recipes` and `status` read.
-import { surveyExecutorVehicle, readExecutorPosture, executorBodyDiffers, executorTemplate, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
+import { surveyExecutorVehicle, readExecutorPosture, executorBodyDiffers, executorTemplate, reviewLensTemplate, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION, REVIEW_LENS_VEHICLE } from './cheap-agents-read.mjs';
+import { readVehicles, resolveExecutor, resolveReviewLens } from './vehicle-settings.mjs';
 // The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
 // (contract: kit/ack-store) — `status` reads the same store, and a second copy is what drifts.
 import {
@@ -119,6 +120,8 @@ export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
 const q = shellQuoteArg;
+// A user variant's own step, as the lane leaf words it: the rendered apply of every user item.
+const userStepOf = (variant, root) => applySlot(variant, { toolsDir: HERE, root }).apply;
 const ABSENT_CODE = 'ENOENT';
 const ENFORCEMENT_KIT_ROOT = resolve(HERE, '..');
 const ENFORCEMENT_BUNDLE_ROOT = join(ENFORCEMENT_KIT_ROOT, 'references', 'scripts');
@@ -163,6 +166,7 @@ export const SEVERITIES = Object.freeze({
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gates-inert': SEVERITY_ATTENTION,
+  'gates-inert.unfillable': SEVERITY_ATTENTION,
   'gates-inert.no-verification': SEVERITY_ATTENTION,
   // Both third outcomes are attention, and both therefore block the flow-optimal line MECHANICALLY:
   // an added item makes the verdict non-null. One reports a pair that is dead on a tree the closed
@@ -255,6 +259,7 @@ export const composeVerdict = ({ attention, optional, skipped }) => {
 // banned tokens), never a fixture-coverage gamble. A pure-placeholder template marks a WHAT whose
 // content is fully dynamic (capped at composition by truncation-with-count) — except `profile-gap`, whose
 // WHAT is never truncated: the leaf's suite pins every composed WHAT under the cap.
+const GATES_INERT_WHAT = 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov';
 export const WHATS = Object.freeze({
   'velocity-core': 'routine read-only commands still prompt — {n} audited read-only allowlist entr(ies) not seeded',
   'velocity-core.rule': 'auto mode refuses a harness apply, so work cannot stay in auto mode — the apply ask rule is not seeded',
@@ -267,7 +272,8 @@ export const WHATS = Object.freeze({
   'sandbox-provision.installable': 'the OS sandbox is unavailable: {reason} — installable via the doctor (consent tuple {tuple})',
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
-  'gates-inert': 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov',
+  'gates-inert': GATES_INERT_WHAT,
+  'gates-inert.unfillable': GATES_INERT_WHAT,
   'gates-inert.no-verification': "all {n} declared gate(s) are the kit's own checkers — the matrix runs no project-verification command",
   'gates-inert.producer-unrecognized': 'the coverage checker ({id}) has NO producer declared and none offerable, on a tree the changed-line domain barely reaches',
   'gates-inert.coverage-domain-narrow': 'certification covers the assessable minority only — {ext} dominate(s) the tracked tree, and the changed-line domain excludes them',
@@ -286,6 +292,7 @@ export const WHATS = Object.freeze({
   'mcp-channel': "the kit's read-only MCP server is not registered here — path questions and literal searches stay shell strings",
   'mcp-channel.differing': 'an "{server}" MCP entry is already declared here and DIFFERS from the registration this kit copy would write',
   agents: '{n} bundled subagent vehicle(s) not placed (Claude Code) — {ro} read-only, {ex} the full-tool executor; the apply PREVIEWS first',
+  'agents.lens-rederive': 'the placed review-lens.md differs from its body derived from docs/ai/vehicles.json; {n} vehicle(s) to place ({ro} read-only, {ex} executor)',
   'executor-vehicle': '{n} slot(s) configured subagent but the executor vehicle is {state}{reason} — every such slot runs solo until it is usable',
   'executor-vehicle.differing': 'the placed executor vehicle differs from the body derived from docs/ai/vehicles.json — a hand edit stands until it is re-derived',
   attribution: 'AGENTS.md says attribution off but .claude/settings.json does not hide the harness trailer and PR text',
@@ -426,8 +433,8 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'delegated-execution', mode: 'set-recipe', advisorKey: 'review-recipe' },
   { id: 'agents', mode: 'agents', advisorKey: 'agents' },
   // A DISTINCT capability from the offer above: the offer converges the moment nothing is left to
-  // PLACE, which a customized-but-unusable executor also satisfies — so it can never observe the
-  // state that makes a configured subagent carrier run solo.
+  // PLACE and the review lens matches its derived body, which a customized-but-unusable executor
+  // also satisfies — so it can never observe the state that makes a configured subagent carrier run solo.
   { id: 'executor-vehicle', mode: 'agents', advisorKey: 'executor-vehicle' },
   // Exempt, not un-audited. `acceptEdits` auto-applies Edit/Write and auto-runs mkdir/touch/mv/cp:
   // a TRUST-POSTURE change. Velocity presents its full posture at its own consent moment;
@@ -588,7 +595,8 @@ const probeReviewRecipe = ({ root, deps, add, skip }) => {
       }
     }
     if (degraded.length > 0) {
-      add('review-recipe', fillTemplate(WHATS['review-recipe'], { degraded: capList(degraded, templateBudget(WHATS['review-recipe'])) }), '/agent-workflow-kit backends');
+      add('review-recipe', fillTemplate(WHATS['review-recipe'], { degraded: capList(degraded, templateBudget(WHATS['review-recipe'])) }),
+        userStepOf('review-recipe', root));
     }
   } catch (err) {
     skip('review-recipe', err);
@@ -651,8 +659,8 @@ const probeGates = ({ root, deps, add, skip, shared }) => {
 // gate is not a kit checker. Cause A's apply follows what the FILL can actually do, which the
 // D-8 placement rule changed: when the checker is the declaration's LAST gate and the project's own
 // scripts yield an offerable producer, the fill now PLACES that producer before the checker, so the
-// remedy is the ordinary consent-gated preview. HAND-APPLY remains exactly where no offerable
-// producer exists, or where the checker is not last — there the edit really is the maintainer's,
+// remedy is the ordinary consent-gated preview. Where no offerable producer exists, or the checker
+// is not last, the arm is the user item `gates-inert.unfillable` — the edit is the project's own,
 // because the fill never reorders entries it did not write.
 //
 // An ABSENT or EMPTY declaration belongs to the gates-declaration item; a malformed one throws out
@@ -765,8 +773,9 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
           add(
             'gates-inert',
             fillTemplate(WHATS['gates-inert.producer-unrecognized'], { id }),
-            `HAND-APPLY: mark the gate that actually writes the lcov with "lcovProducer": true in ${GATES_REL} (references/modes/gates.md names the key), or drop ${id} — and note the fill offers only terminating-class script NAMES, so a recognized body under another name (a "ci" script running node --test) is declared by hand, not marked`,
+            userStepOf('gates-inert.producer-unrecognized', root),
             'gates-inert.producer-unrecognized',
+            `${id} has no producer declared and none offerable — the fill offers only terminating-class script names, so a recognized body under another name (a "ci" script running node --test) is declared as its own gate entry, never marked`,
           );
           return;
         }
@@ -788,13 +797,12 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
         : colliding !== undefined
           ? `a producer IS offerable here, but its id "${colliding.id}" is already declared, so the fill refuses it as a collision — rename that gate, or repoint it at the producer form`
           : `no offerable producer exists here, and the fill never reorders entries it did not write`;
-      add(
-        'gates-inert',
-        fillTemplate(WHATS['gates-inert'], { id }),
-        checkerIsLast && producer
-          ? fillPreviewFor(root, [producer.id])
-          : `HAND-APPLY: declare or MOVE a suite gate carrying the coverage reporters BEFORE ${id} in ${GATES_REL} (references/modes/gates.md names the exact form), or drop ${id} — ${blocked}`,
-      );
+      if (checkerIsLast && producer) {
+        add('gates-inert', fillTemplate(WHATS['gates-inert'], { id }), fillPreviewFor(root, [producer.id]));
+        return;
+      }
+      add('gates-inert', fillTemplate(WHATS['gates-inert.unfillable'], { id }), userStepOf('gates-inert.unfillable', root),
+        'gates-inert.unfillable', blocked);
       return;
     }
     // The source-size checker is one of the kit's OWN checkers, and it is deliberately NOT
@@ -887,15 +895,11 @@ const probeSourceSize = ({ root, deps, add, skip }) => {
     }
     // The id SQUATTER — the id says the practice is declared, the cmd is not this checker under any
     // reading. `--adopt` here mints the record and is then refused by the fill on the id collision:
-    // correct against a squatter, and useless as a RENDERED remedy, so this arm names the two hand
-    // edits that actually resolve it instead.
+    // correct against a squatter, and useless as a RENDERED remedy, so this arm is a user item whose
+    // step names the edits that actually resolve it.
     if (gates.some((gate) => gate.id === SOURCE_SIZE_GATE_ID)) {
-      add(
-        'source-size',
-        fillTemplate(WHATS['source-size.id-squatter'], {}),
-        `HAND-APPLY: in ${GATES_REL}, either rename the "${SOURCE_SIZE_GATE_ID}" gate to an id of its own, or repoint its cmd at node ${q(tool)} --check — then re-run recommendations`,
-        'source-size.id-squatter',
-      );
+      add('source-size', fillTemplate(WHATS['source-size.id-squatter'], {}), userStepOf('source-size.id-squatter', root),
+        'source-size.id-squatter');
       return;
     }
     add('source-size', fillTemplate(WHATS['source-size'], {}), adoptLine);
@@ -1079,16 +1083,19 @@ const probeStateBlockHook = ({ root, deps, add, skip }) => {
 // surfaced its absence: `agents` is the family's SECOND `.claude/` writer, the `help` Tune tail
 // advertises it, and the advisor had no entry for it — so a user who never runs `help` never learned
 // it existed while the advisor reported the deployment optimal. Found by the guard, not by an incident.
-// Only a PLACE action counts as a gap: `already-current` is converged; a customized read-only vehicle or lens is
+// A PLACE action and the bundled review lens's `re-derive` (its placed body differs from the one derived from docs/ai/vehicles.json) count as gaps: `already-current` is converged; a customized read-only vehicle or derived lens is
 // the user's own edit the writer never clobbers and the advisor never nags about; the executor is not preserved but re-derived from docs/ai/vehicles.json (its `re-derive` answer is not a gap of this offer).
 const probeCheapAgents = ({ root, deps, add, skip }) => {
   try {
-    const { posture, reason } = readExecutorPosture(root, deps);
+    const fs = readFsDeps(deps);
+    const answer = readVehicles(root, fs.readFile, fs.lstat);
+    const { posture, reason } = resolveExecutor(answer);
     if (posture === null) {
       skip('agents', new Error(`${reason} — fix that file first`));
       return;
     }
-    const preflight = preflightCheapAgents({ cwd: root, derived: [executorTemplate(posture, deps)] }, deps);
+    const derived = [executorTemplate(posture, deps), reviewLensTemplate(resolveReviewLens(answer).posture, deps)];
+    const preflight = preflightCheapAgents({ cwd: root, derived }, deps);
     // The writer refuses below the expected lineage, so offering its command would hand the user a
     // guaranteed failure — the honest surface is a stated skip naming the recovery.
     if (!preflight.stampOk) {
@@ -1096,7 +1103,8 @@ const probeCheapAgents = ({ root, deps, add, skip }) => {
       return;
     }
     const toPlace = preflight.plan.filter((item) => item.action === 'place');
-    if (toPlace.length === 0) return; // converged
+    const lensRederive = preflight.plan.some((item) => item.name === REVIEW_LENS_VEHICLE && item.action === 're-derive');
+    if (toPlace.length === 0 && !lensRederive) return; // converged
     // The writer's contract is «--dry-run first, ALWAYS» (references/modes/agents.md, and its stated
     // invariant «preview by default»), so the rendered line is the PREVIEW — this item joins the
     // dry-run-preview class the mode doc already documents for the gates-declaration seeder, where the
@@ -1105,7 +1113,7 @@ const probeCheapAgents = ({ root, deps, add, skip }) => {
     // The hidden-mode reconcile rides the detail, never the apply line: it is wrong to run on a
     // VISIBLE deployment, and the apply slot must stay one pure executable command.
     const executors = toPlace.filter((item) => item.name === EXECUTOR_VEHICLE).length;
-    add('agents', fillTemplate(WHATS.agents, { n: toPlace.length, ex: executors, ro: toPlace.length - executors }),
+    add('agents', fillTemplate(WHATS[lensRederive ? 'agents.lens-rederive' : 'agents'], { n: toPlace.length, ex: executors, ro: toPlace.length - executors }),
       `node ${q(toolPath('cheap-agents.mjs'))} --cwd ${q(root)}`, 'agents',
       `hidden-mode deployments only: after the --apply the preview prints, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
     );
@@ -1116,8 +1124,8 @@ const probeCheapAgents = ({ root, deps, add, skip }) => {
 
 // The subagent carrier's ONE instrument (contract: kit/carriers). Neither neighbour can report this
 // state: `probeReviewRecipe` skips a slot configured `subagent` by construction, and the offer above
-// judges only what is left to PLACE — a customized-but-broken vehicle leaves nothing to place. So a
-// project could declare the carrier and have every such slot run solo, unseen.
+// judges only what is left to PLACE and the bundled lens's re-derive — a customized-but-broken executor
+// gives it neither. So a project could declare the carrier and have every such slot run solo, unseen.
 const VEHICLE_BROKEN_STATES = Object.freeze(['missing', 'unusable']);
 
 const writerBlock = (root, deps) => {
@@ -1166,7 +1174,7 @@ const renderBrokenExecutor = ({ root, deps, add, skip }) => {
     const blocked = writerBlock(root, deps);
     if (blocked) preconditions.push(`${blocked} — fix that`);
     const room = templateBudget(WHATS['executor-vehicle']) - String(configured.length).length - survey.state.length - 2;
-    return add(
+    add(
       'executor-vehicle',
       fillTemplate(WHATS['executor-vehicle'], {
         n: configured.length,
@@ -1179,9 +1187,10 @@ const renderBrokenExecutor = ({ root, deps, add, skip }) => {
       'executor-vehicle',
       `${preconditions.length ? `precondition: ${preconditions.join('; ')}; ` : ''}${HIDDEN_AGENTS_FOLLOW_UP(root)}`,
     );
+    return true;
   } catch (err) {
     skip('executor-vehicle', err);
-    return false;
+    return true;
   }
 };
 
@@ -1342,6 +1351,8 @@ export const RISK_NOTED_KEYS = Object.freeze(['bridge-tier', 'read-lane', 'workt
 // spec-check's own census; a recorded decline (the `spec-adoption` ack lane) is the fact that
 // silences the item, and an unreadable store is a stated skip so the flow-optimal line never renders
 // over it. The not-adopted apply is the spec-layer ensure; the decline preview rides the recipe line.
+// The one opening of every offer's decline alternative: a chat write the agent runs on the user's decline.
+export const DECLINE_ALTERNATIVE = 'decline alternative (asked apart, before the confirmation; on your decline the agent records it instead of the apply, never after it): ';
 export const probeSpecAdoption = ({ root, deps, add, skip }) => {
   try {
     const survey = surveySpecAdoption(root, deps);
@@ -1357,7 +1368,7 @@ export const probeSpecAdoption = ({ root, deps, add, skip }) => {
         fillTemplate(WHATS['spec-adoption'], {}),
         `node ${q(toolPath('ensure-configs.mjs'))} --reconcile --only ${SPEC_LAYER_ENSURE} --cwd ${q(root)}`,
         'spec-adoption',
-        `HAND-APPLY alternative (instead of the apply, never after it): decline the layer by recording it — ${decline}`,
+        `${DECLINE_ALTERNATIVE}${decline}`,
       );
       return;
     }
@@ -1477,13 +1488,12 @@ export const probeAdrStore = ({ root, deps, add, skip }) => {
   try {
     const shape = ADR_LAYOUT_SHAPES[surveyAdrLayoutStrict(root, deps)];
     if (!shape) return; // migrated, or no ADR substrate at all — nothing to offer
-    // HAND-APPLY, not the standard lane: the consent flow executes the apply slot against the
-    // confirmation given BEFORE the preview, and this crossing requires informed consent AFTER its
-    // dry-run. A runnable one-liner here would auto-run a tree-mutating migration on stale consent.
+    // The apply is the bare dry run: consent takes two steps, as profile-gap's does — the first yes
+    // runs it and the plan is relayed, the same line with --apply runs only on a second yes over it.
     add(
       'adr-store-migration',
       fillTemplate(WHATS['adr-store-migration'], { shape }),
-      `HAND-APPLY: node ${q(toolPath('migrate-adr-store.mjs'))} --dry-run --cwd ${q(root)} — then re-run with --apply ONLY after showing the plan and getting fresh consent`,
+      `node ${q(toolPath('migrate-adr-store.mjs'))} --dry-run --cwd ${q(root)}`,
     );
   } catch (err) {
     skip('adr-store-migration', err);
@@ -1534,7 +1544,7 @@ export const probeJevConnect = ({ root, deps, add, skip }) => {
     const place = placeOf({ env, platform: host.platform, hostname: host.hostname, container: host.container });
     const decline = `node ${q(toolPath('ack-write.mjs'))} --lane jev-connect --fingerprint ${JEV_CONNECT_DECLINE} --cwd ${q(root)}`;
     add('jev-connect', WHATS['jev-connect'], applySlot('jev-connect', { toolsDir: HERE }).apply, 'jev-connect',
-      `${place ? `run the apply in ${place}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
+      `${place ? `run the apply in ${place}; ` : ''}${DECLINE_ALTERNATIVE}${decline}`);
   } catch (err) {
     skip('jev-connect', err);
   }
@@ -1568,7 +1578,7 @@ export const probeJevSkill = ({ root, deps, add, skip }) => {
       .map(({ path, reason }) => `left untouched: ${printable(path)} — ${printable(reason)}; `).join('');
     const record = `node ${q(toolPath('ack-write.mjs'))} --lane jev-skill --fingerprint ${decline} --cwd ${q(root)}`;
     add('jev-skill', what, line, behind.length ? 'jev-skill.earlier' : 'jev-skill',
-      `${place ? `run the apply in ${place}; ` : ''}${untouched}${note ? `${note}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${record}`);
+      `${place ? `run the apply in ${place}; ` : ''}${untouched}${note ? `${note}; ` : ''}${DECLINE_ALTERNATIVE}${record}`);
   } catch (err) {
     skip('jev-skill', err);
   }
@@ -1664,10 +1674,9 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // which item fired, and only this field says which ARM of it did — so a consumer (the pre-publish
   // smoke asserting a specific false-green never returns) can assert the exact outcome instead of
   // pattern-matching prose that is free to be reworded.
-  // `detail` (optional) is an extra rendered `recipe:` line — factual context that is TOO LONG for
-  // the capped WHAT and does NOT belong in the pure-command apply (the bridge-tier missing-entries
-  // line; the worktrees-dir ack fallback; the
-  // agents hidden-mode reconcile follow-up). Single-line like apply; absent for every other item.
+  // `detail` (optional) is an extra rendered `recipe:` line — an item's own facts or its alternative,
+  // TOO LONG for the capped WHAT and outside the pure-command apply (such as the bridge-tier
+  // missing-entries line or the worktrees-dir ack fallback). Single-line like apply; absent otherwise.
   // Returns whether the item really RENDERED. One probe's disposition depends on another's having
   // spoken (the marker-stale ⟷ read-lane.stale precedence), and "the conditions still look right"
   // is not the same fact as "an item exists" — the shape backstop can refuse, and a condition read
@@ -1757,9 +1766,9 @@ Usage:
 
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
-sub-optimal · the benefit in one plain line · the lane · an optional \`recipe:\` line (the bridge-tier
-missing-entries line, the worktrees-dir ack fallback, or the agents hidden-mode reconcile
-follow-up) · the harness check line · the exact consent-gated apply one-liner}. --cwd is
+sub-optimal · the benefit in one plain line · the lane · an optional \`recipe:\` line (an item's own
+facts or its alternative, such as the bridge-tier missing-entries line or
+the worktrees-dir ack fallback) · the harness check line · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;
@@ -1770,8 +1779,8 @@ allow rules, <wrapper> * exclusions (codex-exec * where an execute slot delegate
 sandbox.network.allowedDomains and state dirs in sandbox.filesystem.allowWrite. Where the host
 honors the settings sandbox keys, an excluded wrapper runs outside the sandbox, every sandboxed
 command of the project can reach each host, and every sandboxed command can write each state dir;
-plan/diff review modes and delegated execution keep their prompt. Items marked HAND-APPLY stay
-the user's own step.
+plan/diff review modes and delegated execution keep their prompt.
+A user item stays the user's own step.
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;

package/tools/reference-profile.mjs

@@ -22,8 +22,8 @@ const target = (activity, slot, candidates) => Object.freeze({ activity, slot, c
 export const TIER_TARGETS = Object.freeze([
   target('epic', 'author', ['subagent', 'solo']),
   target('epic', 'review', ['reviewed', 'solo']),
-  target('task', 'author', ['delegated', 'subagent', 'solo']),
-  target('task', 'execute', ['delegated', 'subagent', 'solo']),
+  target('task', 'author', ['subagent', 'solo']),
+  target('task', 'execute', ['subagent', 'solo']),
 ]);
 
 const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);

package/tools/vehicle-settings.mjs

@@ -3,11 +3,14 @@ import { join } from 'node:path';
 
 export const VEHICLES_REL = 'docs/ai/vehicles.json';
 export const EXECUTOR_DEFAULTS = Object.freeze({ model: 'opus', effort: 'high', fallback: 'sonnet' });
+export const REVIEW_LENS_DEFAULTS = Object.freeze({ model: 'opus', effort: 'high' });
 
 const README_KEY = '_README';
 const EXECUTOR_KEY = 'executor';
-const TOP_LEVEL_KEYS = Object.freeze([README_KEY, EXECUTOR_KEY]);
+const LENS_KEY = 'review-lens';
+const TOP_LEVEL_KEYS = Object.freeze([README_KEY, EXECUTOR_KEY, LENS_KEY]);
 const EXECUTOR_KEYS = Object.freeze(Object.keys(EXECUTOR_DEFAULTS));
+const LENS_KEYS = Object.freeze(Object.keys(REVIEW_LENS_DEFAULTS));
 const OBJECT_TYPE = 'object';
 const STRING_TYPE = 'string';
 const EMPTY_STRING = '';
@@ -44,6 +47,25 @@ const unreadable = (reason) => ({ state: UNREADABLE, reason });
 const describeError = (error) => String(error?.code ?? error?.message ?? error);
 const formatReadError = (error) => `${VEHICLES_REL}: ${UNREADABLE} (${describeError(error)})`;
 
+const validateSection = (value, rel, name, keys) => {
+  const section = value[name];
+  if (!isPlainObject(section)) return refuseValue(rel, name, OBJECT_REQUIRED);
+  for (const key of Object.keys(section)) {
+    if (!keys.includes(key)) return refuseValue(rel, `${name}.${key}`, UNKNOWN_KEY);
+  }
+  for (const key of keys) {
+    const qualifiedKey = `${name}.${key}`;
+    if (!Object.hasOwn(section, key)) return refuseValue(rel, qualifiedKey, REQUIRED_KEY);
+    const token = section[key];
+    if (typeof token !== STRING_TYPE) return refuseValue(rel, qualifiedKey, STRING_REQUIRED);
+    if (token === EMPTY_STRING) return refuseValue(rel, qualifiedKey, NONEMPTY_REQUIRED);
+    if (!TOKEN_PATTERN.test(token) || token.trim() !== token) {
+      return refuseValue(rel, qualifiedKey, TOKEN_REQUIRED);
+    }
+  }
+  return { ok: true, values: Object.fromEntries(keys.map((key) => [key, section[key]])) };
+};
+
 export const validateVehicles = (value, rel = VEHICLES_REL) => {
   if (!isPlainObject(value)) return refuseValue(rel, BODY_NAME, OBJECT_REQUIRED);
   for (const key of Object.keys(value)) {
@@ -53,26 +75,15 @@ export const validateVehicles = (value, rel = VEHICLES_REL) => {
     return refuseValue(rel, README_KEY, STRING_REQUIRED);
   }
   if (!Object.hasOwn(value, EXECUTOR_KEY)) return refuseValue(rel, EXECUTOR_KEY, REQUIRED_KEY);
-  const executor = value[EXECUTOR_KEY];
-  if (!isPlainObject(executor)) return refuseValue(rel, EXECUTOR_KEY, OBJECT_REQUIRED);
-  for (const key of Object.keys(executor)) {
-    if (!EXECUTOR_KEYS.includes(key)) return refuseValue(rel, `${EXECUTOR_KEY}.${key}`, UNKNOWN_KEY);
-  }
-  for (const key of EXECUTOR_KEYS) {
-    const qualifiedKey = `${EXECUTOR_KEY}.${key}`;
-    if (!Object.hasOwn(executor, key)) return refuseValue(rel, qualifiedKey, REQUIRED_KEY);
-    const token = executor[key];
-    if (typeof token !== STRING_TYPE) return refuseValue(rel, qualifiedKey, STRING_REQUIRED);
-    if (token === EMPTY_STRING) return refuseValue(rel, qualifiedKey, NONEMPTY_REQUIRED);
-    if (!TOKEN_PATTERN.test(token) || token.trim() !== token) {
-      return refuseValue(rel, qualifiedKey, TOKEN_REQUIRED);
-    }
-  }
-  if (executor.fallback === executor.model) {
+  const executor = validateSection(value, rel, EXECUTOR_KEY, EXECUTOR_KEYS);
+  if (!executor.ok) return executor;
+  if (executor.values.fallback === executor.values.model) {
     return refuseValue(rel, EXECUTOR_KEY, DISTINCT_FALLBACK_REQUIRED);
   }
-  const { model, effort, fallback } = executor;
-  return { ok: true, settings: { executor: { model, effort, fallback } } };
+  const settings = { executor: executor.values };
+  if (!Object.hasOwn(value, LENS_KEY)) return { ok: true, settings };
+  const lens = validateSection(value, rel, LENS_KEY, LENS_KEYS);
+  return lens.ok ? { ok: true, settings: { ...settings, [LENS_KEY]: lens.values } } : lens;
 };
 
 const probeEntry = (path, lstat) => {
@@ -125,3 +136,14 @@ export const resolveExecutor = (answer) => {
   if (answer?.state === UNREADABLE) return { posture: null, reason: answer.reason };
   throw fail(CONFIG_EXIT_CODE, `${VEHICLES_REL}: ${UNKNOWN_STATE} ${String(answer?.state)}`);
 };
+
+export const resolveReviewLens = (answer) => {
+  if (answer?.state === PRESENT && Object.hasOwn(answer.settings, LENS_KEY)) {
+    return { posture: { ...answer.settings[LENS_KEY], source: FILE_SOURCE }, reason: null };
+  }
+  if (answer?.state === PRESENT || answer?.state === ABSENT) {
+    return { posture: { ...REVIEW_LENS_DEFAULTS, source: DEFAULT_SOURCE }, reason: null };
+  }
+  if (answer?.state === UNREADABLE) return { posture: null, reason: answer.reason };
+  throw fail(CONFIG_EXIT_CODE, `${VEHICLES_REL}: ${UNKNOWN_STATE} ${String(answer?.state)}`);
+};

package/tools/write-lanes.mjs

@@ -3,6 +3,10 @@ import { dirCovers } from './declared-paths.mjs';
 import { claudeDirOf, quoteArg, skillTargets } from './jev-facts.mjs';
 import { targetsFor } from './jev-connect.mjs';
 import { BUNDLED_SCRIPT_NAMES, INSTALLER_REL, SCRIPTS_REL } from './git-hooks.mjs';
+import { dqUnsafePath } from './checker-claim.mjs';
+import { isLineUnsafe } from './source-size-refusal.mjs';
+import { SOURCE_SIZE_GATE_ID } from './source-size-gate-cmd.mjs';
+import { GATES_REL } from './gates-declaration.mjs';
 
 export const LANE_CHAT = 'chat';
 export const LANE_HARNESS = 'harness';
@@ -16,16 +20,17 @@ export const VARIANT_LANES = Object.freeze({
   'autonomy-render': LANE_HARNESS,
   'sandbox-provision': LANE_USER,
   'sandbox-provision.installable': LANE_USER,
-  'review-recipe': LANE_CHAT,
+  'review-recipe': LANE_USER,
   'gates-declaration': LANE_CHAT,
   'gates-inert': LANE_CHAT,
+  'gates-inert.unfillable': LANE_USER,
   'gates-inert.no-verification': LANE_CHAT,
-  'gates-inert.producer-unrecognized': LANE_CHAT,
+  'gates-inert.producer-unrecognized': LANE_USER,
   'gates-inert.coverage-domain-narrow': LANE_CHAT,
   'source-size': LANE_CHAT,
   'source-size.unminted': LANE_CHAT,
   'source-size.adopted-elsewhere': LANE_CHAT,
-  'source-size.id-squatter': LANE_CHAT,
+  'source-size.id-squatter': LANE_USER,
   'gate-hook': LANE_HARNESS,
   'gate-hook.marker-stale': LANE_HARNESS,
   'commit-guard': LANE_HARNESS,
@@ -109,6 +114,15 @@ const getGuardPaths = (facts) => [preCommitOf(facts), join(facts.root, INSTALLER
 
 const formatCommand = (argv) => argv.map(quoteArg).join(' ');
 const TERMINAL_STEP = 'run in a terminal of your own: ';
+const OWN_STEP = 'your own step — ';
+const RERUN_ADVISOR = ', then run /agent-workflow-kit recommendations';
+
+const squatterStep = (facts) => {
+  const tool = join(facts.toolsDir, 'source-size-check.mjs');
+  const rename = `${OWN_STEP}in ${GATES_REL} rename the "${SOURCE_SIZE_GATE_ID}" gate to an id of its own`;
+  if (dqUnsafePath(tool) || isLineUnsafe(tool)) return `${rename}${RERUN_ADVISOR}`;
+  return `${rename}, or repoint its cmd at node "${tool}" --check${RERUN_ADVISOR}`;
+};
 
 // rejudged: the written value derives from state init's record does not watch, so init re-runs its check before the apply.
 const createForm = (file, preview, apply, writes, envDependent = false, userStep = null, rejudged = false) => Object.freeze({
@@ -155,13 +169,13 @@ const FORMS = Object.freeze({
   'jev-skill': SKILL_FORM,
   'jev-skill.earlier': SKILL_FORM,
   'jev-connect': createForm('jev-connect.mjs', null, [], getStartupPaths, true,
-    (facts, argv) => 'your own step — it asks for the key in your terminal and the key never goes into the chat — '
+    (facts, argv) => `${OWN_STEP}it asks for the key in your terminal and the key never goes into the chat — `
       + `${TERMINAL_STEP}${formatCommand(argv.apply)}`),
   'family-freshness': Object.freeze({
-    userStep: () => `your own step — ${TERMINAL_STEP}${formatCommand(['npx', '@sabaiway/agent-workflow-kit@latest', 'init'])}`,
+    userStep: () => `${OWN_STEP}${TERMINAL_STEP}${formatCommand(['npx', '@sabaiway/agent-workflow-kit@latest', 'init'])}`,
   }),
   'sandbox-provision': Object.freeze({
-    userStep: (facts) => 'your own step — the doctor has no install it can run for you here (the reason is this item\'s text) — '
+    userStep: (facts) => `${OWN_STEP}the doctor has no install it can run for you here (the reason is this item's text) — `
       + `${TERMINAL_STEP}cd ${quoteArg(facts.root)} && ${formatCommand(['node', join(facts.toolsDir, 'autonomy-doctor.mjs')])}`,
   }),
   enforcement: createForm('git-hooks.mjs',
@@ -171,7 +185,21 @@ const FORMS = Object.freeze({
   'worktrees-dir': createForm('velocity-profile.mjs',
     ['--worktrees', '--cwd', '<root>'], ['--apply', '--worktrees', '--cwd', '<root>'], LOCAL_SETTINGS_WRITES, false, null, true),
   'worktrees-dir.home': Object.freeze({
-    userStep: () => 'your own step — point docs/ai/worktrees.json parentDir at a dedicated directory, then run /agent-workflow-kit recommendations',
+    userStep: () => `${OWN_STEP}point docs/ai/worktrees.json parentDir at a dedicated directory${RERUN_ADVISOR}`,
+  }),
+  'gates-inert.unfillable': Object.freeze({
+    userStep: () => `${OWN_STEP}in ${GATES_REL} declare or move a suite gate carrying the coverage reporters before the coverage checker`
+      + ` (references/modes/gates.md names the exact form), or drop that checker${RERUN_ADVISOR}`,
+  }),
+  'gates-inert.producer-unrecognized': Object.freeze({
+    userStep: () => `${OWN_STEP}in ${GATES_REL} mark the gate that writes the lcov with "lcovProducer": true`
+      + ` (references/modes/gates.md names the key), or drop the coverage checker${RERUN_ADVISOR}`,
+  }),
+  'source-size.id-squatter': Object.freeze({ userStep: squatterStep }),
+  'review-recipe': Object.freeze({
+    userStep: () => `${OWN_STEP}set up the backend the recipe names with /agent-workflow-kit setup (it places the bridge skill`
+      + ' and links its wrappers, and names the CLI install and sign-in that stay yours; /agent-workflow-kit backends shows what is'
+      + ` missing), or re-pick the recipe with /agent-workflow-kit set-recipe${RERUN_ADVISOR}`,
   }),
 });