@aperant/framework 0.12.0 → 0.13.0-next.0

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(),