@miller-tech/uap 1.187.8 → 1.188.0

package/dist/delivery/scope-notice.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Warn when a mission's instruction names files it cannot reach.
+ *
+ * THE FAILURE THIS CATCHES
+ * `safePath` refuses any edit that resolves outside the project root, which is
+ * correct and stays. But refusing one path does not stop the model wanting that
+ * file — and its next move is the damaging one. Observed live on 2026-08-09 in
+ * `cognition-engine`:
+ *
+ *   projectRoot: <repo>/src/rust-pg-ext        (the crate)
+ *   instruction: "... **src/sql/setup.sql** lines 22-29: replace SQL md5 hash
+ *                 functions with Rust XXH64 versions ..."
+ *
+ * That file is `<repo>/src/sql/setup.sql` — 62KB, outside the crate. The model
+ * tried `../sql/setup.sql`, was refused, and then CREATED a 1.5KB stub at
+ * `<crate>/src/sql/setup.sql`, which safePath allows because it is inside the
+ * root. The guard deflected the model into writing a plausible file in the
+ * wrong place: untracked, unreferenced, and easy to mistake for the real edit.
+ *
+ * The mission was mis-scoped — it should have run at the repo root — and that
+ * was knowable before the first turn, from the instruction and the filesystem
+ * alone. Saying so up front turns a silent wrong-place write into a fact the
+ * model and the operator both get for free.
+ *
+ * DELIBERATELY ADVISORY. A path in an instruction can be illustrative, a file
+ * yet to be created, or prose that merely looks like a path, so refusing the
+ * run on this signal would block legitimate work. It only ever reports paths
+ * that are ABSENT under the project root and PRESENT above it — the one
+ * combination that cannot be explained by "the model will create it".
+ */
+/**
+ * The enclosing repository root ABOVE `projectRoot`, or null.
+ *
+ * Null when the project root is itself the repo root — there is nothing above
+ * to be out of scope of — and null when no repository encloses it at all.
+ * `.git` is a directory in a normal clone and a FILE in a worktree, so both
+ * count.
+ */
+export declare function findRepoRoot(projectRoot: string, exists?: (p: string) => boolean): string | null;
+/** A path the instruction asks for that this run cannot reach. */
+export interface UnreachablePath {
+    /** The path as written in the instruction. */
+    mentioned: string;
+    /** Where it actually is, relative to the search root. */
+    foundAt: string;
+}
+/** Candidate paths mentioned in free text, de-duplicated, in first-seen order. */
+export declare function mentionedPaths(instruction: string): string[];
+/**
+ * Paths the instruction names that are missing under `projectRoot` but present
+ * under `searchRoot` (normally the repo root above it).
+ *
+ * Returns [] when searchRoot is not an ancestor of projectRoot — there is no
+ * "above" to look in, so there is nothing this can be confident about.
+ */
+export declare function unreachablePaths(instruction: string, projectRoot: string, searchRoot: string, exists?: (p: string) => boolean): UnreachablePath[];
+/**
+ * The prompt/console notice, or null when there is nothing to report.
+ *
+ * Names the substitute-file failure explicitly. Telling a model only "you
+ * cannot reach it" leaves creating a same-named file inside the root as the
+ * obvious next move — which is the exact damage observed.
+ */
+export declare function formatScopeNotice(unreachable: readonly UnreachablePath[], projectRoot: string, searchRoot: string): string | null;
+//# sourceMappingURL=scope-notice.d.ts.map

package/dist/delivery/scope-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-notice.d.ts","sourceRoot":"","sources":["../../src/delivery/scope-notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAoB,GAC1C,MAAM,GAAG,IAAI,CASf;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAc5D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAoB,GAC1C,eAAe,EAAE,CAYnB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,eAAe,EAAE,EACvC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAaf"}

package/dist/delivery/scope-notice.js

@@ -0,0 +1,134 @@
+/**
+ * Warn when a mission's instruction names files it cannot reach.
+ *
+ * THE FAILURE THIS CATCHES
+ * `safePath` refuses any edit that resolves outside the project root, which is
+ * correct and stays. But refusing one path does not stop the model wanting that
+ * file — and its next move is the damaging one. Observed live on 2026-08-09 in
+ * `cognition-engine`:
+ *
+ *   projectRoot: <repo>/src/rust-pg-ext        (the crate)
+ *   instruction: "... **src/sql/setup.sql** lines 22-29: replace SQL md5 hash
+ *                 functions with Rust XXH64 versions ..."
+ *
+ * That file is `<repo>/src/sql/setup.sql` — 62KB, outside the crate. The model
+ * tried `../sql/setup.sql`, was refused, and then CREATED a 1.5KB stub at
+ * `<crate>/src/sql/setup.sql`, which safePath allows because it is inside the
+ * root. The guard deflected the model into writing a plausible file in the
+ * wrong place: untracked, unreferenced, and easy to mistake for the real edit.
+ *
+ * The mission was mis-scoped — it should have run at the repo root — and that
+ * was knowable before the first turn, from the instruction and the filesystem
+ * alone. Saying so up front turns a silent wrong-place write into a fact the
+ * model and the operator both get for free.
+ *
+ * DELIBERATELY ADVISORY. A path in an instruction can be illustrative, a file
+ * yet to be created, or prose that merely looks like a path, so refusing the
+ * run on this signal would block legitimate work. It only ever reports paths
+ * that are ABSENT under the project root and PRESENT above it — the one
+ * combination that cannot be explained by "the model will create it".
+ */
+import { existsSync } from 'fs';
+import { isAbsolute, join, relative, resolve } from 'path';
+/**
+ * The enclosing repository root ABOVE `projectRoot`, or null.
+ *
+ * Null when the project root is itself the repo root — there is nothing above
+ * to be out of scope of — and null when no repository encloses it at all.
+ * `.git` is a directory in a normal clone and a FILE in a worktree, so both
+ * count.
+ */
+export function findRepoRoot(projectRoot, exists = existsSync) {
+    let dir = resolve(projectRoot);
+    for (let hops = 0; hops < 64; hops++) {
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null; // hit the filesystem root
+        dir = parent;
+        if (exists(join(dir, '.git')))
+            return dir;
+    }
+    return null;
+}
+/**
+ * File-like tokens: a path with a real extension. Requiring an extension is
+ * what keeps prose out — "src/sql" or "the setup" are not candidates, and a
+ * bare word never is. Markdown emphasis and surrounding punctuation are
+ * stripped by the caller before this matches.
+ */
+const PATH_TOKEN = /[\w.-]+(?:\/[\w.-]+)*\.[a-z]{1,6}\b/gi;
+/**
+ * Extensions worth checking. An open-ended match turns ordinary sentences
+ * ("v1.2", "e.g.", "node.js") into candidate paths; a fixed list keeps the
+ * signal specific to source trees.
+ */
+const SOURCE_EXT = new Set([
+    'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'rs', 'py', 'go', 'rb', 'java', 'kt',
+    'c', 'h', 'cc', 'cpp', 'hpp', 'cs', 'php', 'swift', 'sql', 'sh', 'bash',
+    'toml', 'yaml', 'yml', 'json', 'md', 'css', 'scss', 'html', 'jinja',
+]);
+/** Candidate paths mentioned in free text, de-duplicated, in first-seen order. */
+export function mentionedPaths(instruction) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of instruction.match(PATH_TOKEN) ?? []) {
+        // Strip markdown emphasis and trailing punctuation the token may have eaten.
+        const tok = raw.replace(/^[*_`]+/, '').replace(/[*_`.,;:)\]]+$/, '');
+        if (!tok.includes('/'))
+            continue; // a bare filename is too weak a signal
+        const ext = tok.split('.').pop()?.toLowerCase() ?? '';
+        if (!SOURCE_EXT.has(ext))
+            continue;
+        if (seen.has(tok))
+            continue;
+        seen.add(tok);
+        out.push(tok);
+    }
+    return out;
+}
+/**
+ * Paths the instruction names that are missing under `projectRoot` but present
+ * under `searchRoot` (normally the repo root above it).
+ *
+ * Returns [] when searchRoot is not an ancestor of projectRoot — there is no
+ * "above" to look in, so there is nothing this can be confident about.
+ */
+export function unreachablePaths(instruction, projectRoot, searchRoot, exists = existsSync) {
+    const rel = relative(resolve(searchRoot), resolve(projectRoot));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return [];
+    const found = [];
+    for (const p of mentionedPaths(instruction)) {
+        if (isAbsolute(p))
+            continue; // an absolute path is not a scope mistake
+        if (exists(join(projectRoot, p)))
+            continue; // reachable — nothing to say
+        if (!exists(join(searchRoot, p)))
+            continue; // absent everywhere: to be created
+        found.push({ mentioned: p, foundAt: join(relative(projectRoot, searchRoot), p) });
+    }
+    return found;
+}
+/**
+ * The prompt/console notice, or null when there is nothing to report.
+ *
+ * Names the substitute-file failure explicitly. Telling a model only "you
+ * cannot reach it" leaves creating a same-named file inside the root as the
+ * obvious next move — which is the exact damage observed.
+ */
+export function formatScopeNotice(unreachable, projectRoot, searchRoot) {
+    if (unreachable.length === 0)
+        return null;
+    const lines = unreachable.map((u) => `  - ${u.mentioned}  (actually at ${u.foundAt})`);
+    return [
+        'SCOPE NOTICE — this task names files that are OUTSIDE the project root you are running in.',
+        `Project root: ${projectRoot}`,
+        lines.join('\n'),
+        '',
+        'You cannot edit them: every path is resolved inside the project root, so `../` is refused.',
+        'Do NOT create a same-named file inside the project root as a substitute — it would be a new,',
+        'unreferenced file, not the edit that was asked for. Complete the parts that ARE in scope, and',
+        `report the rest as out of scope. If they are essential, the run belongs at ${searchRoot}.`,
+    ].join('\n');
+}
+//# sourceMappingURL=scope-notice.js.map

package/dist/delivery/scope-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-notice.js","sourceRoot":"","sources":["../../src/delivery/scope-notice.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.187.8",
+  "version": "1.188.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",