@aperant/framework 0.12.1 → 0.13.0-next.0

package/package.json

@@ -1,139 +1,139 @@
 {
-  "name": "@aperant/framework",
-  "version": "0.12.1",
-  "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
-  "author": "Mikalsen AI <hello@mikalsen.ai>",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "framework": "./bin/apt-tools.mjs",
-    "apt-tools": "./bin/apt-tools.mjs",
-    "apt-proof-video": "./bin/apt-proof-video.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
-    },
-    "./cost": {
-      "types": "./dist/cost/index.d.ts",
-      "import": "./dist/cost/index.js"
-    },
-    "./mappers": {
-      "types": "./dist/mappers/index.d.ts",
-      "import": "./dist/mappers/index.js"
-    },
-    "./schemas": {
-      "types": "./dist/schemas/index.d.ts",
-      "import": "./dist/schemas/index.js"
-    },
-    "./standalone": {
-      "types": "./dist/standalone/index.d.ts",
-      "import": "./dist/standalone/index.js"
-    },
-    "./driver-sdk": {
-      "types": "./dist/driver-sdk/index.d.ts",
-      "import": "./dist/driver-sdk/index.js"
-    },
-    "./coordination/event-schema": {
-      "types": "./src/cli/coordination/event-schema.d.ts",
-      "import": "./src/cli/coordination/event-schema.mjs"
-    },
-    "./roadmap/conductor-view": {
-      "types": "./src/cli/roadmap/conductor-view.d.ts",
-      "import": "./src/cli/roadmap/conductor-view.mjs"
-    },
-    "./design/scan": {
-      "import": "./src/cli/design/scan.mjs"
-    },
-    "./design/extract-repo": {
-      "import": "./src/cli/design/extract-repo.mjs"
-    },
-    "./design/synthesize": {
-      "import": "./src/cli/design/synthesize.mjs"
-    }
-  },
-  "files": [
-    "dist/",
-    "bin/",
-    "src/cli/",
-    "src/cost/",
-    "commands/",
-    "skills/",
-    "agents/",
-    "prompts/",
-    "templates/",
-    "context/",
-    "workflows/",
-    "drivers/",
-    "examples/",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md",
-    "!**/__tests__/**",
-    "!**/*.test.*",
-    "!**/*.spec.*",
-    "!**/*.test.d.ts.map",
-    "!**/*.test.js.map"
-  ],
-  "keywords": [
-    "ai",
-    "framework",
-    "coding-assistant",
-    "claude-code",
-    "codex",
-    "aperant"
-  ],
-  "license": "AGPL-3.0-only",
-  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-  "bugs": {
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-    "directory": "packages/framework"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.2.0",
-    "proper-lockfile": "^4.1.2",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6"
-  },
-  "optionalDependencies": {
-    "@babel/parser": "^7.29.2",
-    "@babel/traverse": "^7.29.0",
-    "@google/genai": "^1.50.1",
-    "css-tree": "^3.2.1",
-    "playwright": "^1.59.1"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.5"
-  },
-  "scripts": {
-    "build": "tsc && node scripts/extract-personas-schema.mjs",
-    "dev": "tsc --watch --preserveWatchOutput",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check . --diagnostic-level=error",
-    "lint:fix": "biome check --write . --diagnostic-level=error",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "c28:cutover": "node scripts/c28-cutover.mjs",
-    "build-plugin": "node scripts/build-plugin.mjs",
-    "publish-plugin": "node scripts/publish-plugin.mjs",
-    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-  }
-}
+	"name": "@aperant/framework",
+	"version": "0.13.0-next.0",
+	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
+	"author": "Mikalsen AI <hello@mikalsen.ai>",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"framework": "./bin/apt-tools.mjs",
+		"apt-tools": "./bin/apt-tools.mjs",
+		"apt-proof-video": "./bin/apt-proof-video.mjs"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/types/index.js"
+		},
+		"./cost": {
+			"types": "./dist/cost/index.d.ts",
+			"import": "./dist/cost/index.js"
+		},
+		"./mappers": {
+			"types": "./dist/mappers/index.d.ts",
+			"import": "./dist/mappers/index.js"
+		},
+		"./schemas": {
+			"types": "./dist/schemas/index.d.ts",
+			"import": "./dist/schemas/index.js"
+		},
+		"./standalone": {
+			"types": "./dist/standalone/index.d.ts",
+			"import": "./dist/standalone/index.js"
+		},
+		"./driver-sdk": {
+			"types": "./dist/driver-sdk/index.d.ts",
+			"import": "./dist/driver-sdk/index.js"
+		},
+		"./coordination/event-schema": {
+			"types": "./src/cli/coordination/event-schema.d.ts",
+			"import": "./src/cli/coordination/event-schema.mjs"
+		},
+		"./roadmap/conductor-view": {
+			"types": "./src/cli/roadmap/conductor-view.d.ts",
+			"import": "./src/cli/roadmap/conductor-view.mjs"
+		},
+		"./design/scan": {
+			"import": "./src/cli/design/scan.mjs"
+		},
+		"./design/extract-repo": {
+			"import": "./src/cli/design/extract-repo.mjs"
+		},
+		"./design/synthesize": {
+			"import": "./src/cli/design/synthesize.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsc && node scripts/extract-personas-schema.mjs",
+		"dev": "tsc --watch --preserveWatchOutput",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check . --diagnostic-level=error",
+		"lint:fix": "biome check --write . --diagnostic-level=error",
+		"clean": "rm -rf dist",
+		"test": "vitest run",
+		"c28:cutover": "node scripts/c28-cutover.mjs",
+		"build-plugin": "node scripts/build-plugin.mjs",
+		"publish-plugin": "node scripts/publish-plugin.mjs",
+		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+	},
+	"files": [
+		"dist/",
+		"bin/",
+		"src/cli/",
+		"src/cost/",
+		"commands/",
+		"skills/",
+		"agents/",
+		"prompts/",
+		"templates/",
+		"context/",
+		"workflows/",
+		"drivers/",
+		"examples/",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md",
+		"!**/__tests__/**",
+		"!**/*.test.*",
+		"!**/*.spec.*",
+		"!**/*.test.d.ts.map",
+		"!**/*.test.js.map"
+	],
+	"keywords": [
+		"ai",
+		"framework",
+		"coding-assistant",
+		"claude-code",
+		"codex",
+		"aperant"
+	],
+	"license": "AGPL-3.0-only",
+	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+	"bugs": {
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+		"directory": "packages/framework"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.2.0",
+		"proper-lockfile": "^4.1.2",
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"optionalDependencies": {
+		"@babel/parser": "^7.29.2",
+		"@babel/traverse": "^7.29.0",
+		"@google/genai": "^1.50.1",
+		"css-tree": "^3.2.1",
+		"playwright": "^1.59.1"
+	},
+	"devDependencies": {
+		"@vitest/coverage-v8": "^4.1.5"
+	}
+}

package/skills/apt/SKILL.md

@@ -52,9 +52,16 @@ you must follow when classifying.
 Before doing ANYTHING else, classify the user's input:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs route . --input "$ARGUMENTS"
+APT_FORCE_TTY=1 node packages/framework/bin/apt-tools.mjs route . --input "$ARGUMENTS"
 ```
 
+The `APT_FORCE_TTY=1` prefix is the EXPLICIT interactive signal — not a real
+TTY — and it is what makes the catch-up panel compute on this top-level `/apt`
+call (the Bash tool runs `route` as a captured, non-TTY subprocess, so the
+isTTY sniff alone would never open the gate). Spawned-subagent, fan-out, and
+background `route` calls deliberately OMIT this signal (or set
+`APT_CATCH_UP_DISABLE=1`) so the panel never fires inside a nested call.
+
 Parse the JSON result. The `mode` field determines what you do next. Display the routing decision to the user:
 
 ```
@@ -98,9 +105,10 @@ While you were away:
 ```
 
 This is display-only here — the Last-Seen Marker advance happens in route.mjs,
-not in this skill. The panel is computed lazily on interactive (TTY) calls
-only; non-TTY/background/spawned calls carry no `catch_up` field. Do not call
-it an "activity feed", "changelog", or "notifications" — it is the
+not in this skill. The panel is computed lazily only when the explicit
+interactive signal (`APT_FORCE_TTY=1`, set above) is present — NOT a real TTY;
+non-TTY/background/spawned calls omit the signal and carry no `catch_up` field.
+Do not call it an "activity feed", "changelog", or "notifications" — it is the
 Welcome-Back Summary + Team-Change Digest.
 
 Then proceed to the matching mode handler below. Do NOT deviate from the routing decision.

package/skills/apt-debug/SKILL.md

@@ -11,6 +11,7 @@ spawns_agent: false
 agent_name: null
 task_context: create-new
 default_track: DEBUG
+passthrough_policy: exact-only
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-improve/SKILL.md

@@ -11,6 +11,7 @@ spawns_agent: true
 agent_name: "apt-improver"
 task_context: create-new
 default_track: DEEP
+passthrough_policy: exact-only
 default_execution_mode: step
 execution_modes:
   - auto

package/skills/apt-review/SKILL.md

@@ -10,6 +10,7 @@ internal: false
 spawns_agent: true
 agent_name: "apt-reviewer"
 task_context: require-existing
+passthrough_policy: exact-only
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-triage/SKILL.md

@@ -11,6 +11,7 @@ spawns_agent: false
 agent_name: null
 task_context: require-existing
 default_track: STANDARD
+passthrough_policy: exact-only
 default_execution_mode: step
 execution_modes:
   - auto

package/src/cli/commands/route.mjs

@@ -102,12 +102,26 @@ function readUpdateCheckCache() {
 }
 
 /**
- * Is this an interactive (TTY) apt call? The catch-up panel + Last-Seen Marker
- * are gated to interactive contexts (LD-02) — exactly like the statusline
- * isTTY gate — so spawned subagents, fan-out workers, and non-TTY/piped calls
- * are strict no-ops (they neither read nor write the marker). `APT_FORCE_TTY`
- * forces the gate open for tests; `APT_CATCH_UP_DISABLE` forces it closed so a
- * background spawner can opt every nested call out.
+ * Is this an interactive `/apt` call? The catch-up panel + Last-Seen Marker
+ * are gated to interactive contexts (LD-02) so spawned subagents, fan-out
+ * workers, and background/piped calls are strict no-ops (they neither read nor
+ * write the marker).
+ *
+ * The PRODUCTION trigger is the EXPLICIT interactive signal `APT_FORCE_TTY=1`,
+ * which the top-level `/apt` skill sets on its `apt-tools route` call
+ * (`skills/apt/SKILL.md`). The skill runs `route` via the Bash tool — a
+ * captured, non-TTY subprocess whose stdout/stderr are piped, never a PTY — so
+ * the `process.stdout/stderr.isTTY` sniff below is ALWAYS false on that path.
+ * The explicit signal is therefore the load-bearing opener; the isTTY sniff is
+ * only a SECONDARY fallback so a genuinely-interactive direct `apt-tools route`
+ * CLI call (a real terminal) still computes the panel.
+ *
+ * `APT_FORCE_TTY` does double duty: the test-override role AND the production
+ * interactive signal (no new env var — keeps the schema + opt-out unchanged).
+ * `APT_CATCH_UP_DISABLE` forces the gate closed so a background spawner can opt
+ * every nested call out (it wins over the signal). Spawned / fan-out / nested
+ * route calls deliberately set NEITHER (or set APT_CATCH_UP_DISABLE), so the
+ * panel never fires inside a sub-agent.
  */
 function isInteractiveTty() {
 	if (process.env.APT_CATCH_UP_DISABLE === '1') return false
@@ -131,7 +145,7 @@ function isInteractiveTty() {
  * isInteractiveTty), so background/spawned calls never touch the marker.
  *
  * @param {string} targetDir
- * @returns {object|null} the catch_up panel, or null.
+ * @returns {{ welcome_back: object|null, team_digest: object|null }|null} the catch_up panel, or null.
  */
 function computeCatchUpForRoute(targetDir) {
 	// Setup mirrors cmdCatchUp in commands/catch-up.mjs (recompute-only variant).
@@ -223,6 +237,118 @@ function normalizeAptInvocation(input) {
  */
 const PR_REVIEW_SIGNAL = /(?:\bPR\s*#?\s*\d+|#\d+|\bpull\s*request\s*#?\s*\d+)\b/i
 
+/**
+ * English function/stop words used by `isArgShapedRemainder` (ID-04) to detect
+ * a prose-shaped remainder. Conservative on purpose: a remainder containing any
+ * of these reads like a sentence, so under `exact-only` it falls through to the
+ * host-LLM classify path instead of hijacking the slug. Hoisted to module scope
+ * (frozen) so the Set is built once at load time. Lowercase keys only — the
+ * helper lowercases tokens before lookup.
+ */
+const PASSTHROUGH_STOP_WORDS = Object.freeze(
+	new Set([
+		'the',
+		'a',
+		'an',
+		'is',
+		'are',
+		'was',
+		'were',
+		'be',
+		'been',
+		'keeps',
+		'keep',
+		'now',
+		'please',
+		'that',
+		'this',
+		'these',
+		'those',
+		'my',
+		'our',
+		'your',
+		'their',
+		'it',
+		'its',
+		'to',
+		'of',
+		'in',
+		'on',
+		'at',
+		'for',
+		'and',
+		'but',
+		'or',
+		'so',
+		'then',
+		'when',
+		'while',
+		'because',
+		'i',
+		'we',
+		'they',
+		'you',
+		'fails',
+		'failing',
+		'failed',
+		'crashing',
+		'crashed',
+		'broken',
+		'with',
+		'from',
+		'into',
+	]),
+)
+
+/**
+ * Pure, deterministic classifier (ID-04) for the remainder after a slug's first
+ * word, used by the `exact-only` passthrough policy. Returns true when the
+ * remainder is ARG-SHAPED (→ passthrough) and false when it is PROSE-SHAPED
+ * (→ fall through to the host-LLM classify path). No I/O.
+ *
+ * Arg-shaped iff:
+ *   1. empty (bare slug, e.g. `triage`), OR
+ *   2. EVERY whitespace token is flag-shaped (`--fix-all` / `-x`), path-shaped
+ *      (contains `/`, `\`, or `.` → `src/foo.ts`), or numeric/id-shaped
+ *      (`42` / `#7`), OR
+ *   3. it is a SHORT phrase (≤3 tokens) that does NOT read like a sentence:
+ *      the leading token is NOT sentence-case (`/^[A-Z]/` and not an ALL-CAPS
+ *      acronym) AND no token is an English function/stop word.
+ *
+ * Otherwise prose-shaped → false. See ID-04's case table + TD-03 for the
+ * pinned contract.
+ *
+ * @param {string} remainder  the slug's trailing args, already trimmed/joined
+ * @returns {boolean} true → arg-shaped (passthrough); false → prose (classify)
+ */
+export function isArgShapedRemainder(remainder) {
+	const trimmed = typeof remainder === 'string' ? remainder.trim() : ''
+	// 1. Empty / bare slug.
+	if (trimmed === '') return true
+
+	const tokens = trimmed.split(/\s+/)
+
+	const isFlag = (t) => /^--?[\w-]+$/.test(t)
+	const isPath = (t) => /[/\\.]/.test(t)
+	const isNumericId = (t) => /^#?\d+$/.test(t)
+
+	// 2. Every token is flag / path / numeric-id shaped.
+	if (tokens.every((t) => isFlag(t) || isPath(t) || isNumericId(t))) return true
+
+	// 3. Short phrase (≤3 tokens) that does not read like a sentence.
+	if (tokens.length > 3) return false
+	const lead = tokens[0]
+	// Sentence-case leading token (Capitalized, not an ALL-CAPS acronym) reads
+	// like the start of a prose sentence.
+	const isAllCapsAcronym = /^[A-Z0-9]+$/.test(lead)
+	if (/^[A-Z]/.test(lead) && !isAllCapsAcronym) return false
+	// Any English function/stop word anywhere → prose.
+	for (const t of tokens) {
+		if (PASSTHROUGH_STOP_WORDS.has(t.toLowerCase())) return false
+	}
+	return true
+}
+
 /**
  * Canonical skill-slug index — reads every skill's agent_name and
  * spawns_agent flag from its frontmatter so the router doesn't carry a
@@ -239,7 +365,7 @@ const PR_REVIEW_SIGNAL = /(?:\bPR\s*#?\s*\d+|#\d+|\bpull\s*request\s*#?\s*\d+)\b
  * so this keeps the two paths consistent.
  *
  * @param {import('../route/skill-discover.mjs').DiscoveredSkill[]} skills
- * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, taskContextOf: (slug: string) => string|null, defaultTrackOf: (slug: string) => string|null, knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
+ * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, taskContextOf: (slug: string) => string|null, defaultTrackOf: (slug: string) => string|null, passthroughPolicyOf: (slug: string) => 'freetext'|'exact-only'|'never', knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
  */
 function skillIndex(skills) {
 	const byName = new Map()
@@ -267,6 +393,9 @@ function skillIndex(skills) {
 		defaultTrackOf(slug) {
 			return byName.get(slug)?.default_track ?? null
 		},
+		passthroughPolicyOf(slug) {
+			return byName.get(slug)?.passthrough_policy ?? 'freetext'
+		},
 		isUserInvocable(slug) {
 			return userInvocableSlugs.has(slug)
 		},
@@ -386,11 +515,13 @@ export function cmdRoute(projectDir, extraArgs) {
 		}
 	}
 
-	// Catch-up panel (LD-11): lazy-compute on interactive (TTY) calls only, and
-	// only when config exists (init has no config yet). The compute also
-	// advances the Last-Seen Marker after panel eval (LD-02). Non-TTY calls are
-	// strict no-ops — no read, no write, no field. Folded onto every returned
-	// envelope below as a top-level `catch_up` field, mirroring update_check.
+	// Catch-up panel (LD-11): lazy-compute only on interactive `/apt` calls
+	// (explicit `APT_FORCE_TTY=1` signal preferred, TTY sniff fallback — see
+	// isInteractiveTty), and only when config exists (init has no config yet).
+	// The compute also advances the Last-Seen Marker after panel eval (LD-02).
+	// Non-interactive calls are strict no-ops — no read, no write, no field.
+	// Folded onto every returned envelope below as a top-level `catch_up` field,
+	// mirroring update_check.
 	const catch_up = hasConfig && isInteractiveTty() ? computeCatchUpForRoute(targetDir) : null
 
 	// ---------------- Deterministic branches (zero-behavior-change) ----------------
@@ -465,7 +596,36 @@ export function cmdRoute(projectDir, extraArgs) {
 	// The PR_REVIEW_SIGNAL regex itself is defined at module scope above.
 	const isPrReviewFreetext = firstWord === 'review' && PR_REVIEW_SIGNAL.test(remainingArgs)
 
-	if (!isPrReviewFreetext && index.knownSlugs.has(firstWord)) {
+	// Per-skill passthrough policy (Item 2). The policy lives in frontmatter and
+	// is read via the index — NO hardcoded slug list enters route.mjs.
+	//   - freetext   (default): always passthrough on a first-word match (today's
+	//                 behavior, byte-identical);
+	//   - exact-only: passthrough only when the remainder is arg-shaped — a prose
+	//                 remainder ('Triage the failing harness now') falls through to
+	//                 classify (the classify envelope still carries the skill, so a
+	//                 wrong fall-through self-heals, unlike a silent hijack);
+	//   - never:      always classify.
+	// When the gate fails we do NOT early-return — control falls through to the
+	// classify path below, which still surfaces the skill for re-selection.
+	//
+	// The pre-existing `review` PR-review carve-out (isPrReviewFreetext) is the
+	// authoritative prose-vs-invocation discriminator for `review` and STAYS
+	// as-is this task (spec Out-of-Scope). So when the carve-out has already
+	// governed `review` (firstWord === 'review'), the exact-only heuristic is
+	// bypassed — applying both would double-gate `review` and break the locked
+	// PR-review false-positive walls (e.g. "review the pull request feature",
+	// no-digit → passthrough). The carve-out already routed every digit-bearing
+	// PR reference to classify above.
+	const policy = index.passthroughPolicyOf(firstWord)
+	const carveOutGovernsReview = firstWord === 'review'
+	const passthroughOk =
+		policy === 'freetext' || carveOutGovernsReview
+			? true
+			: policy === 'never'
+				? false
+				: isArgShapedRemainder(remainingArgs)
+
+	if (!isPrReviewFreetext && index.knownSlugs.has(firstWord) && passthroughOk) {
 		const shouldSpawn = index.spawnsAgent(firstWord)
 		const gate_preview = previewGatesFor(firstWord)
 		const defaultTrack = index.defaultTrackOf(firstWord)

package/src/cli/route/skill-discover.mjs

@@ -50,6 +50,7 @@ const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/
  * @property {string[]} execution_modes
  * @property {'create-new'|'require-existing'|'self-managed'|'none'} task_context
  * @property {('QUICK'|'STANDARD'|'DEEP'|'DEBUG')|undefined} default_track
+ * @property {'freetext'|'exact-only'|'never'} passthrough_policy  router passthrough policy; always set (defaults to 'freetext' when the frontmatter omits it)
  * @property {string} file_path           absolute path to the SKILL.md
  */
 
@@ -170,6 +171,7 @@ function readSkill(file) {
 			execution_modes: Array.isArray(d.execution_modes) ? [...d.execution_modes] : [],
 			task_context: d.task_context,
 			default_track: d.default_track,
+			passthrough_policy: d.passthrough_policy ?? 'freetext',
 			file_path: file,
 		},
 	}

package/src/cli/skill-author/contract.mjs

@@ -100,6 +100,25 @@ export const TASK_CONTEXTS = Object.freeze([
  */
 export const TRACK_VALUES = Object.freeze(['QUICK', 'STANDARD', 'DEEP', 'DEBUG'])
 
+/**
+ * Per-skill router passthrough policy (Item-2 router fix). Controls whether the
+ * router's first-word skill-passthrough match passes through to this skill or
+ * falls through to the host-LLM classify path when the input is free-text prose:
+ *   - `freetext`   (default when omitted) — current behavior: any input whose
+ *                   first word equals the slug passes through, byte-identical.
+ *   - `exact-only` — pass through ONLY when the remainder is arg-shaped (empty /
+ *                   bare slug, all flag-or-path-or-numeric tokens, or a short
+ *                   ≤3-token lowercase noun phrase). A prose-shaped remainder
+ *                   (sentence-case opener, English stop word, or >3 tokens) falls
+ *                   through to classify. Opt-in for action-verb slugs that are
+ *                   also everyday imperatives (triage/debug/review/improve).
+ *   - `never`      — reserved: always fall through to classify. No skill uses it
+ *                   this task; the value exists for symmetry + future use.
+ * Read by route.mjs via skillIndex.passthroughPolicyOf(slug) — no hardcoded
+ * slug list enters the router.
+ */
+export const PASSTHROUGH_POLICIES = Object.freeze(['freetext', 'exact-only', 'never'])
+
 /**
  * Required XML-style section tags that MUST appear (opening + closing) in the
  * SKILL.md body. Order is not enforced — authors can lay out the sections
@@ -160,6 +179,10 @@ export const SkillFrontmatterSchema = z
 		execution_modes: z.array(ExecutionModeSchema).min(1),
 		task_context: z.enum([...TASK_CONTEXTS]),
 		default_track: z.enum([...TRACK_VALUES]).optional(),
+		// Per-skill router passthrough policy (Item-2). OPTIONAL — omission
+		// resolves to 'freetext' in skill-discover.mjs (byte-identical to
+		// today), so every existing SKILL.md validates unchanged.
+		passthrough_policy: z.enum([...PASSTHROUGH_POLICIES]).optional(),
 		// Legacy / optional pass-throughs — kept as opt-in so migrations
 		// don't immediately break skills that carry them.
 		triggers: z.array(z.string()).optional(),