@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/_lib/skill_origin.ts

@@ -0,0 +1,254 @@
+/**
+ * Who put a ranked skill on disk, and whether its body has been looked at.
+ *
+ * SPLIT OUT OF `neighbour_census.ts` FOR ONE CONCRETE REASON. The ranker
+ * (`skill_tools/score_skill_relevance`) needs these primitives, and the ranker
+ * runs inside the shared hook bundle on `user_prompt_submit`. The census module
+ * reaches the host-hook merger, the secret detector and the install-ownership
+ * reader; every byte of that would be inlined into one bundle that every concern
+ * loads on every dispatch, under a ceiling `check_hook_bundle_composition` holds.
+ * So the primitives live here, importing only the manifest reader, and the census
+ * re-exports them — one definition, two call sites, no second module graph.
+ *
+ * ORIGIN IS READ FROM A CLAIM RECORD, NEVER INFERRED FROM A ROOT. The temptation
+ * is to call `~/.claude/skills` foreign and the workspace ours. That is wrong in
+ * both directions: `agent-config install` writes this package's own skills into
+ * the host-global root, and a consumer's hand-written skills sit in the project
+ * root. The one artifact that records what this package actually wrote is the
+ * installed-tools manifest, so the manifest is the authority and the root is only
+ * a tie-break between the two NON-package labels.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { manifest_path } from './installed_tools.js';
+
+/**
+ * Where a RANKED skill came from — a question about AUTHORSHIP.
+ *
+ * Deliberately not the census's `origin` id segment, which is WHERE a file was
+ * found (`project`, `user`, `cursor`, …). Location does not answer authorship in
+ * either direction, which is the whole reason this type exists beside that one.
+ *
+ * `home` is spelled `home` rather than the census's `user` because this value is
+ * printed on a ROUTE LINE beside a skill name, where it has to read as a place a
+ * reader can go and look.
+ */
+export type SkillOrigin = 'package' | 'project' | 'home';
+
+/** One `compat` label per neighbour skill. Order decided in {@link classifyCompat}. */
+export type Compat = 'shadowed' | 'overlapping' | 'unscanned' | 'unclassified';
+
+/** The authored source tree, relative to a maintainer checkout's root. */
+export const AUTHORED_SKILL_ROOT = path.join('src', 'skills');
+
+/** Where the scan verdicts the ranker reads are written, relative to the root. */
+export const SCAN_CACHE_RELATIVE = path.join('agents', 'reports', 'neighbour-scan.json');
+
+/** Default scan-cache path for a project root. */
+export function scanCachePath(projectRoot: string): string {
+    return path.join(projectRoot, SCAN_CACHE_RELATIVE);
+}
+
+/**
+ * What a route line prints: bare for ours, `origin:name` for a neighbour.
+ *
+ * One function, so the ranker, the census and every report agree on the
+ * spelling. Two spellings of one name is how a collision stops being visible,
+ * which is the defect this whole step exists to close.
+ */
+export function qualifiedSkillName(name: string, origin: SkillOrigin): string {
+    return origin === 'package' ? name : `${origin}:${name}`;
+}
+
+/** Split a qualified name back apart. A bare name resolves to `package`. */
+export function splitQualifiedName(qualified: string): { origin: SkillOrigin; name: string } {
+    const m = /^(project|home):([\s\S]*)$/.exec(qualified);
+    if (m) return { origin: m[1] as SkillOrigin, name: m[2] as string };
+    return { origin: 'package', name: qualified };
+}
+
+/**
+ * Every absolute path this package's installed-tools manifest claims, or `null`
+ * when there is no manifest to claim anything.
+ *
+ * `null` and an empty set are different answers and callers must keep them
+ * apart. An empty set means the manifest was read and claims nothing; `null`
+ * means nothing recorded a claim at all, which is a tree that has never run an
+ * install — this repository, for one.
+ *
+ * WHY THIS PARSES THE MANIFEST ITSELF, which is a thing to justify rather than
+ * do quietly. Three readers of this file already exist and none answers this
+ * question at a cost this path can pay. `installed_tools.read_manifest` drops
+ * the nested `tools[].files[]` rows by design — its own header says so, and
+ * those rows are the entire input here. `install_drift.collect_drift` and
+ * `recordedOwnership.readRecordedHashes` both parse the YAML directly FOR THAT
+ * REASON, so parsing it directly is the established answer rather than a new
+ * idea; what is new is the fourth question — the PATHS only, with no sha, no
+ * tool grouping and no hash map. `readRecordedHashes` would have answered it
+ * and was measured costing 1,706 bytes of the shared hook bundle, which is the
+ * budget this whole module was split out to protect. The `~` expansion below is
+ * the same one all three use.
+ */
+export function packageClaimedPaths(projectRoot: string): ReadonlySet<string> | null {
+    const manifest = manifest_path(projectRoot);
+    let doc: unknown;
+    try {
+        doc = parseYaml(fs.readFileSync(manifest, 'utf-8'), { version: '1.1' });
+    } catch {
+        // Unreadable and absent are the same answer: nothing recorded a claim.
+        return null;
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return null;
+    const tools = (doc as Record<string, unknown>)['tools'];
+    const out = new Set<string>();
+    if (!Array.isArray(tools)) return out;
+    for (const tool of tools) {
+        if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) continue;
+        const files = (tool as Record<string, unknown>)['files'];
+        if (!Array.isArray(files)) continue;
+        for (const entry of files) {
+            if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+            const raw = (entry as Record<string, unknown>)['path'];
+            if (typeof raw !== 'string' || raw === '') continue;
+            out.add(path.resolve(projectRoot, _expanduser(raw)));
+        }
+    }
+    return out;
+}
+
+/** Expand a leading `~`, matching the three sibling manifest readers. */
+function _expanduser(p: string): string {
+    if (p === '~') return os.homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+
+export interface SkillOriginOptions {
+    /** Pre-read claim set, to avoid a second manifest read. `null` = no manifest. */
+    claims?: ReadonlySet<string> | null;
+    /** Maintainer checkout root whose `src/skills` is the authored tree. */
+    packageRoot?: string;
+}
+
+/**
+ * Resolve one `SKILL.md` path to the origin of the skill it defines.
+ *
+ * NO CLAIM RECORD MEANS NO QUALIFIER. With no manifest, nothing on disk carries
+ * evidence that any skill is foreign, so everything resolves to `package`, the
+ * ranker qualifies nothing, and its output is exactly what it was before this
+ * function existed. That is deliberate rather than a gap being tolerated: a
+ * `home:` prefix asserted without a claim record is a guess printed in the shape
+ * of a fact, and a reader cannot tell the two apart. The cost is stated rather
+ * than hidden — where no manifest exists a foreign skill is invisible here, and
+ * the thing that fixes it is running an install, not loosening this rule.
+ *
+ * The authored tree is the one exception, and it is a construction rather than a
+ * guess: `<root>/src/skills` exists only in a maintainer checkout of THIS
+ * package and holds its source of truth, so nothing foreign can be under it.
+ */
+export function makeSkillOriginResolver(
+    projectRoot: string,
+    opts: SkillOriginOptions = {},
+): (skillMdPath: string) => SkillOrigin {
+    const claims = opts.claims !== undefined ? opts.claims : packageClaimedPaths(projectRoot);
+    const root = path.resolve(projectRoot);
+    const authored = path.join(path.resolve(opts.packageRoot ?? projectRoot), AUTHORED_SKILL_ROOT);
+    const under = (abs: string, dir: string): boolean =>
+        abs === dir || abs.startsWith(dir + path.sep);
+    return (skillMdPath: string): SkillOrigin => {
+        const abs = path.resolve(skillMdPath);
+        if (under(abs, authored)) return 'package';
+        if (claims === null) return 'package';
+        if (claims.has(abs)) return 'package';
+        return under(abs, root) ? 'project' : 'home';
+    };
+}
+
+/**
+ * The one label, and the order it is decided in.
+ *
+ *   `unscanned`    — the shape scan refused the body. FIRST, because an overlap
+ *                    score is derived FROM a body this census declined to read,
+ *                    and publishing it would be the refusal cancelling itself.
+ *   `shadowed`     — one of ours carries the same bare name. Name-derived, so it
+ *                    stays true under `unscanned`; it loses the slot only
+ *                    because `unscanned` is the stronger call to action.
+ *   `overlapping`  — content similarity against one of ours at or above the
+ *                    threshold `audit_skill_overlap` already calibrates.
+ *   `unclassified` — none of the above fired. Not a clearance.
+ */
+export function classifyCompat(args: {
+    unscanned: string | null;
+    shadows: readonly string[];
+    overlaps: readonly string[];
+}): Compat {
+    if (args.unscanned !== null) return 'unscanned';
+    if (args.shadows.length > 0) return 'shadowed';
+    if (args.overlaps.length > 0) return 'overlapping';
+    return 'unclassified';
+}
+
+/** One recorded scan verdict. `unscanned` is `null` when every shape passed. */
+export interface ScanRecord {
+    qualified: string;
+    digest: string;
+    unscanned: string | null;
+}
+
+export interface ScanCache {
+    schema_version: 1;
+    entries: ScanRecord[];
+}
+
+/** Read the scan cache, or `null` when it is absent or unreadable. */
+export function readScanCache(file: string): ScanCache | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    const entries = (parsed as Record<string, unknown>)['entries'];
+    if (!Array.isArray(entries)) return null;
+    return { schema_version: 1, entries: entries as ScanRecord[] };
+}
+
+/** sha256 of a file's bytes, or `null` when it cannot be read. */
+export function fileDigest(file: string): string | null {
+    try {
+        return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Whether a neighbour body may be indexed, and why not when it may not.
+ *
+ * THREE REFUSALS, REPORTED SEPARATELY, because they ask the maintainer for three
+ * different things: run the census, re-run it, or read the finding. A missing
+ * record is a refusal and not a pass — a gate that passes on missing evidence is
+ * satisfied by deleting the evidence, which is the opposite of a floor. The
+ * digest compare is what "a changed digest rescans first" means from the reading
+ * side: a body edited after its scan is unscanned again until the census runs.
+ */
+export function scanVerdict(
+    cache: ScanCache | null,
+    qualified: string,
+    digest: string | null,
+): { ok: true } | { ok: false; kind: string } {
+    if (cache === null) return { ok: false, kind: 'no-scan-record' };
+    const rec = cache.entries.find((e) => e.qualified === qualified);
+    if (rec === undefined) return { ok: false, kind: 'no-scan-record' };
+    if (digest === null || rec.digest !== digest) return { ok: false, kind: 'digest-changed' };
+    if (rec.unscanned !== null) return { ok: false, kind: rec.unscanned };
+    return { ok: true };
+}

package/src/scripts/_lib/structured_ask.ts

@@ -15,45 +15,74 @@
  *
  * What is observed, and what is a shape guess — the line is drawn explicitly.
  *
- * `STRUCTURED_ASK_SHAPES` is **empty**. No host in this repository's registry
- * carries an observed structured-ask tool, so there is no per-host tool name to
- * match on, and inventing one from a vendor's documentation is exactly what
- * `host-capability-manifest.md` § Observation protocol forbids.
+ * `STRUCTURED_ASK_SHAPES` carries **one** row, for `claude`, written from an
+ * observation under `host-capability-manifest.md` § Observation protocol —
+ * 48 `AskUserQuestion` `tool_use` blocks across host versions 2.1.252 to
+ * 2.1.284, 2026-09-01 to 2026-10-02. Artifact:
+ * `agents/evidence/analysis/structured-ask-host-observation-2026-10.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artifact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ * Every other host has no row, which is "never looked", and inventing one from
+ * a vendor's documentation is exactly what that protocol forbids.
  *
- * `STRUCTURED_ASK_TOOL_NAME_RE` is therefore a **name-shape pattern, not a host
- * fact**. It exists so that if such a tool ever appears in a transcript, the
- * probe MEASURES it rather than missing it — and so the number it reports today
- * (zero) is a measurement rather than an absence of instrumentation. A reader
- * must not read a match as evidence that a named host ships that tool; the only
- * thing that establishes that is an observation written into
+ * `STRUCTURED_ASK_TOOL_NAME_RE` is a **name-shape pattern, not a host fact**,
+ * and stays one even now that a host fact exists beside it: the pattern is what
+ * every caller passing no host id still matches on. It exists so that a picker
+ * appearing in a transcript is MEASURED rather than missed. A reader must not
+ * read a match as evidence that a named host ships that tool; the only thing
+ * that establishes that is an observation written into
  * `STRUCTURED_ASK_SHAPES` with the protocol's four-part citation.
  *
- * Consequence, stated rather than discovered later: `native` is expected to be
- * **0** on every corpus this repo can scan today. That is the honest reading of
- * a capability nobody has observed, not a broken detector.
+ * Consequence, stated rather than discovered later: `native` is **0** on every
+ * corpus this repo can scan today — and the 2026-10 observation does NOT change
+ * that, which is worth stating because it looks like it should.
+ * `probe_unblocked_ask` partitions hand-back ask turns, and a picker call is
+ * answered by a `tool_result` rather than by a free user turn, so it was never
+ * in that probe's denominator. The zero means "no prose hand-back used a picker
+ * instead"; it never meant "no picker exists".
+ *
+ * That makes the zero DEFINITIONAL for this probe, not a measurement of
+ * scarcity, and the earlier wording claimed the opposite on both halves: it
+ * called the zero a measurement, and attributed it to the capability being
+ * unobserved. The capability is observed and the zero is unchanged, which is
+ * the cleanest available proof that the two were never connected.
  */
 
 /** The per-host shape of a structured-ask tool, once one has been OBSERVED. */
 export interface StructuredAskShape {
     /** The tool name as it appears in a transcript's `tool_use` block. */
     readonly tool: string;
-    /** How many questions one call may carry. `1` is the shape this repo wants. */
+    /**
+     * The largest question count OBSERVED in one call, never a host ceiling the
+     * host was asked for and refused. `1` is also the shape this repo wants.
+     */
     readonly max_questions: number;
-    /** How many options one question may offer. */
+    /** The largest option count OBSERVED on one question — same caveat. */
     readonly max_options_per_question: number;
-    /** Whether the host's picker admits a free-text answer alongside the options. */
+    /**
+     * Whether the host's picker admits a free-text answer alongside the options.
+     * The WEAKEST of the four to establish, because it is read by negation — an
+     * answer carrying none of the offered labels. A cancelled ask looks the same
+     * from the outside, so a `true` here is "observed at least once", never a
+     * count. The citing artifact carries the per-row basis.
+     */
     readonly free_text: boolean;
 }
 
 /**
  * Observed per-host structured-ask shapes.
  *
- * EMPTY, deliberately. A row is written only from an observation in a real
- * session under `contexts/execution/host-capability-manifest.md` § Observation
- * protocol — host · host version · transcript reference · date. Never from a
- * host's documentation, and never by analogy to another host.
+ * A row is written only from an observation in a real session under
+ * `contexts/execution/host-capability-manifest.md` § Observation protocol —
+ * host · host version · transcript reference · date. Never from a host's
+ * documentation, and never by analogy to another host.
+ *
+ * `claude`'s row is the first, and the two numeric fields are **observed
+ * maxima over 48 calls, not host ceilings**: no call carried two questions, so
+ * the host was never asked to accept two. The guard's threshold does not rest
+ * on them — one question per call is this repo's own rule either way.
  */
-export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {};
+export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {
+    claude: { tool: 'AskUserQuestion', max_questions: 1, max_options_per_question: 4, free_text: true },
+};
 
 /** The observed shape for `hostId`, or `undefined` when none has been observed. */
 export function structuredAskShape(
@@ -77,6 +106,20 @@ export const STRUCTURED_ASK_TOOL_NAME_RE = /^(ask[_-]?user[_-]?question|user[_-]
  * An observed per-host shape wins outright — that is a fact about the host. The
  * name-shape pattern is the fallback, and it is why the probe can report a
  * measured zero instead of nothing at all.
+ *
+ * KNOWN ASYMMETRY, named rather than left for the next reader to hit. With a
+ * row present, this returns `name === shape.tool`: ONE observed name becomes an
+ * exclusive allowlist, so every other picker name is answered `false` on that
+ * host — a universal negative from a single positive observation, which is the
+ * shape of inference the observation protocol refuses elsewhere. It is left as
+ * it is because the alternative (union of the row and the pattern) would make
+ * an observed row buy nothing, and because no caller is affected today. There
+ * are TWO production callers, both host-blind, enumerated rather than recalled:
+ * `hooks/one_question_per_ask_hook.ts:103` and `probe_unblocked_ask.ts:184`,
+ * each calling `isStructuredAskTool(name)` with no second argument. A caller
+ * that does start passing one inherits the asymmetry, and
+ * `tests/scripts/ask_surface.test.ts` pins it so the inheritance is visible
+ * rather than silent.
  */
 export function isStructuredAskTool(name: string, hostId?: string | null): boolean {
     const shape = structuredAskShape(hostId);