@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/mcp_server/graph_tools.ts

@@ -42,7 +42,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { changedFiles } from '../code_graph/cli.js';
-import { detectSources, graphState, NATIVE_CACHE_REL, pickSource } from '../code_graph/detect.js';
+import { detectSources, graphState, pickSource } from '../code_graph/detect.js';
+import { graphHome } from '../code_graph/graph_home.js';
+import { advisoryImpact, whereUsed } from '../code_graph/estate_cli.js';
+import { openEstate } from '../code_graph/estate_index.js';
+import { touchHome } from '../code_graph/graph_budget.js';
+import { resolveProjectRef } from '../code_graph/project_ref.js';
+import { repoIdentity } from '../code_graph/repo_identity.js';
+import { readRegistry, repoIdOf } from '../_lib/project_registry.js';
 import { resolvePath } from './path_util.js';
 import { isTestFile } from '../code_graph/build.js';
 import {
@@ -62,11 +69,52 @@ import {
     testsFor,
     untested,
 } from '../code_graph/verbs.js';
-import { areaReport, readMap } from '../code_graph/map.js';
+import { areaReport, graphGeneration, readMap } from '../code_graph/map.js';
 import type { BuiltinTool } from './tools.js';
 
-/** The `no graph here` answer, in one place so all five agree on its shape. */
+/**
+ * Registered projects whose graph exists, for a root that has none (5.2). Read
+ * from the local registry only; the graph files themselves are not opened.
+ *
+ * Any MCP caller can reach this answer, so it never names another repository's
+ * path: only another checkout of the server root's own repository is listed
+ * with its root, and other projects appear — by id and name — only while the
+ * owner has switched the estate index on (O1).
+ */
+function projectsWithGraph(root: string): Array<{ id: string; name: string; root?: string }> {
+    const reg = readRegistry();
+    const self = repoIdentity(root).repoId;
+    let real: string;
+    try {
+        real = fs.realpathSync(root);
+    } catch {
+        real = path.resolve(root);
+    }
+    const out: Array<{ id: string; name: string; root?: string }> = [];
+    for (const [id, e] of Object.entries(reg.projects)) {
+        const same = repoIdOf(id) === self;
+        if (!same && !reg.index) continue;
+        if (e.root === real || !fs.existsSync(e.root) || !fs.existsSync(graphHome(e.root).cachePath)) continue;
+        out.push(same ? { id, name: path.basename(e.root), root: e.root } : { id, name: path.basename(e.root) });
+        if (out.length === 20) break;
+    }
+    return out;
+}
+
+/** The `no graph here` answer, in one place so all the tools agree on its shape. */
 function noGraph(root: string): Record<string, unknown> {
+    const registered = projectsWithGraph(root);
+    if (registered.length) {
+        return {
+            status: 'unavailable',
+            staleness: 'absent',
+            error:
+                'no code-graph source under this root — pass `project` to ask a registered project below, ' +
+                'or run `agent-config code-graph build` here',
+            root,
+            registered_projects: registered,
+        };
+    }
     return {
         status: 'unavailable',
         staleness: 'absent',
@@ -88,9 +136,10 @@ function withGraph<T extends Record<string, unknown>>(
     root: string,
     fn: (g: LoadedGraph) => T,
 ): Record<string, unknown> {
-    const picked = pickSource(detectSources(root, path.join(root, NATIVE_CACHE_REL)));
+    const picked = pickSource(detectSources(root, graphHome(root).cachePath));
     if (!picked || picked.kind === 'scip') return noGraph(root);
-    const g = loadGraph(picked.path, `${picked.kind}:${path.relative(root, picked.path)}`);
+    touchHome(root);
+    const g = loadGraph(picked.path, `${picked.kind}:${shown(root, picked.path)}`);
     try {
         const out = fn(g);
         // `status` is DERIVED from the answer, never prefixed onto it. An
@@ -107,6 +156,12 @@ function withGraph<T extends Record<string, unknown>>(
     }
 }
 
+/** Relative inside the root, absolute for a graph home outside it (ADR-299). */
+function shown(root: string, p: string): string {
+    const rel = path.relative(root, p);
+    return rel.startsWith('..') || path.isAbsolute(rel) ? p : rel;
+}
+
 function str(args: Record<string, unknown>, key: string): string {
     const v = args[key];
     return typeof v === 'string' ? v.trim() : '';
@@ -134,6 +189,7 @@ const RELATIONS = [
     'migrates',
     'persists',
     'relates',
+    'injects',
     'documents',
 ] as const;
 
@@ -142,14 +198,49 @@ function num(args: Record<string, unknown>, key: string, dflt: number): number {
     return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : dflt;
 }
 
-export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
+/**
+ * Every graph tool takes an optional `project` (5.1): a registered repo id,
+ * name or path, resolved through the registry and its graph home. Without it
+ * the tool answers about the server root, exactly as before.
+ */
+function withProjectParam(tools: Record<string, BuiltinTool>): Record<string, BuiltinTool> {
+    const out: Record<string, BuiltinTool> = {};
+    for (const [name, t] of Object.entries(tools)) {
+        // The estate tool answers across every project already.
+        if (name === 'graph_estate') {
+            out[name] = t;
+            continue;
+        }
+        const schema = t.input_schema as { properties?: Record<string, unknown> };
+        out[name] = {
+            ...t,
+            input_schema: {
+                ...t.input_schema,
+                properties: {
+                    ...(schema.properties ?? {}),
+                    project: { type: 'string' },
+                },
+            },
+            handler: async (args, root) => {
+                const ref = str(args, 'project');
+                if (ref === '') return t.handler(args, root);
+                const r = resolveProjectRef(ref);
+                if ('error' in r) return { status: 'error', error: r.error, candidates: r.candidates };
+                return t.handler(args, r.root);
+            },
+        };
+    }
+    return out;
+}
+
+export const GRAPH_TOOLS: Record<string, BuiltinTool> = withProjectParam({
     graph_impact: {
         name: 'graph_impact',
         side_effect: 'shell',
         description:
             'What a diff can break: callers, dependents and test files reaching the ' +
-            'changed symbols. Walks only stated-fact edges, never a same-name guess, ' +
-            'and reports the guesses refused. Runs `git diff` for the rev.',
+            'changed symbols, over stated-fact edges only (refused guesses reported). ' +
+            'Runs `git diff` for the rev.',
         input_schema: {
             type: 'object',
             required: ['diff'],
@@ -169,7 +260,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             if (rev === '') return { status: 'error', error: 'diff must be a non-empty git rev' };
             const files = changedFiles(root, rev);
             if (files === null) return { status: 'error', error: `cannot resolve rev '${rev}' in ${root}` };
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) =>
                 args['untested_only'] === true
                     ? { ...untested(g, files, state), changed_files: files.length }
@@ -182,20 +273,20 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_tests_for',
         side_effect: 'ro',
         description:
-            'Which test files exercise a symbol, derived from a test file importing ' +
-            'it or its module. Empty means no test imports it — a finding, not an error.',
+            'Test files that exercise a symbol: a test file imports it or its module. ' +
+            'Empty means none does — a finding, not an error.',
         input_schema: {
             type: 'object',
             required: ['symbol'],
             properties: {
-                symbol: { type: 'string', description: 'Node id `<relpath>#<sym>`, label, or free text.' },
+                symbol: { type: 'string', description: 'Node id, label, or free text.' },
             },
             additionalProperties: false,
         },
         handler: async (args, root) => {
             const symbol = str(args, 'symbol');
             if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({ ...testsFor(g, symbol, state) }));
         },
     },
@@ -204,16 +295,15 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_dead',
         side_effect: 'ro',
         description:
-            'Symbols with no accepted reference that no declared entry point names. ' +
-            'REFUSES (status `refused`) while a source is unreadable: with no ' +
-            'exportedness recorded, an exported-but-unimported symbol is ' +
-            'indistinguishable from a dead one. Never a deletion recommendation.',
+            'Symbols no accepted reference and no declared entry point names. REFUSES ' +
+            '(status `refused`) while a source is unreadable: without recorded exportedness ' +
+            'an exported-but-unimported symbol looks dead. Never a deletion recommendation.',
         input_schema: {
             type: 'object',
             properties: {
                 entry_points: {
                     type: 'string',
-                    description: 'Path under this root to a newline-separated id/label list; `#` comments ok.',
+                    description: 'Path under this root: newline-separated ids or labels, `#` comments ok.',
                 },
                 accept_missing_exports: {
                     type: 'boolean',
@@ -224,7 +314,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             additionalProperties: false,
         },
         handler: async (args, root) => {
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             const listArg = str(args, 'entry_points');
             let sources = repoEntryPoints(root);
             if (listArg !== '') {
@@ -280,22 +370,21 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_query',
         side_effect: 'ro',
         description:
-            "A symbol's direct outgoing relations — calls, imports, uses, inherits — " +
-            'each line carrying its confidence and resolution mechanism. For "what ' +
-            'does this touch" before reading a file.',
+            "A symbol's direct outgoing relations (calls, imports, uses, inherits), each " +
+            'with its confidence and resolution mechanism: "what does this touch" before reading a file.',
         input_schema: {
             type: 'object',
             required: ['symbol'],
             properties: {
                 symbol: { type: 'string', description: 'Node id, label, or free text.' },
-                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+                budget: { type: 'integer', minimum: 1, default: 1500 },
             },
             additionalProperties: false,
         },
         handler: async (args, root) => {
             const symbol = str(args, 'symbol');
             if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({
                 staleness,
                 ...graphQueryVerb(g, symbol, num(args, 'budget', 1500)),
@@ -307,10 +396,9 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_node',
         side_effect: 'ro',
         description:
-            'One symbol in full: where it is declared, what reaches it, what it ' +
-            'reaches, and how connected it is. Resolves EXACTLY (node id, then ' +
-            'label) and refuses anything it cannot — it never scores free text, ' +
-            'so an answer is always about the node you named.',
+            'One symbol in full: where it is declared, what reaches it, what it reaches, ' +
+            'how connected it is. Resolves EXACTLY (node id, then label) and refuses ' +
+            'anything else — never scores free text.',
         input_schema: {
             type: 'object',
             required: ['id'],
@@ -320,13 +408,13 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                     type: 'string',
                     enum: ['in', 'out', 'both'],
                     default: 'both',
-                    description: 'Which edges to walk. `in` = who reaches it, `out` = what it reaches.',
+                    description: '`in` = who reaches it, `out` = what it reaches.',
                 },
                 depth: { type: 'integer', minimum: 1, maximum: 3, default: 1, description: 'Hop limit.' },
                 relation: {
                     type: 'string',
                     enum: RELATIONS,
-                    description: 'Restrict to one relation. Omit for all of them.',
+                    description: 'One relation only; omit for all.',
                 },
             },
             additionalProperties: false,
@@ -334,7 +422,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         handler: async (args, root) => {
             const id = str(args, 'id');
             if (id === '') return { status: 'error', error: 'id must be a non-empty string' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             const opts: NodeOptions = {};
             const dir = str(args, 'direction');
             if (dir === 'in' || dir === 'out' || dir === 'both') opts.direction = dir;
@@ -352,16 +440,15 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_path',
         side_effect: 'ro',
         description:
-            'The shortest relation chain between two symbols, direction preserved. ' +
-            'Answers "how does A reach B" without reading the files between. ' +
-            '`(no path found)` when unconnected is an answer.',
+            'The shortest relation chain between two symbols, direction kept: how A reaches ' +
+            'B without reading the files between. `(no path found)` is an answer.',
         input_schema: {
             type: 'object',
             required: ['from', 'to'],
             properties: {
                 from: { type: 'string', description: 'Start node id, label, or free text.' },
                 to: { type: 'string', description: 'Goal node id, label, or free text.' },
-                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+                budget: { type: 'integer', minimum: 1, default: 1500 },
             },
             additionalProperties: false,
         },
@@ -369,7 +456,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             const from = str(args, 'from');
             const to = str(args, 'to');
             if (from === '' || to === '') return { status: 'error', error: 'from and to must be non-empty strings' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({
                 staleness,
                 ...graphPathVerb(g, from, to, num(args, 'budget', 1500)),
@@ -382,7 +469,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         description: 'Is there a code map (agents/map/)? Its freshness, counts and MAP.md path.',
         input_schema: { type: 'object', properties: {}, additionalProperties: false },
         handler: async (_args, root) => {
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             const map = readMap(root);
             if (!map) {
                 return {
@@ -393,20 +480,25 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                 };
             }
             const m = map.model;
+            const home = graphHome(root);
+            const mapRel = home.kind === 'project' ? 'agents/map' : home.mapDir;
             return {
                 status: 'ok',
                 staleness,
                 map: 'present',
                 drawn_at_commit: map.meta.commit,
                 graph_state_when_drawn: map.meta.state,
+                // Same generation → the map shows exactly the graph the queries read.
+                map_matches_graph: map.meta.graph_generation !== undefined && map.meta.graph_generation === graphGeneration(home.cachePath),
                 files: m.files.length,
                 areas: m.areas.length,
                 trusted_links: m.analyses.trustedEdges,
                 guess_share: m.analyses.guessShare,
                 request_paths: m.analyses.requestPathsTotal,
+                providers: (m.providers ?? []).map((p) => `${p.id} (${p.status})`),
                 largest_areas: m.areas.slice(0, 5).map((a) => `${a.id} ${a.name} (${a.files.length})`),
-                map_md: 'agents/map/MAP.md',
-                index_html: 'agents/map/index.html',
+                map_md: `${mapRel}/MAP.md`,
+                index_html: `${mapRel}/index.html`,
             };
         },
     },
@@ -427,9 +519,41 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             if (q === '') return { status: 'error', error: 'area must be a non-empty string' };
             const map = readMap(root);
             if (!map) return { status: 'unavailable', error: 'no map — run `agent-config code-graph map`' };
-            const r = areaReport(map.model, q);
+            const home = graphHome(root);
+            const r = areaReport(map.model, q, home.kind === 'project' ? undefined : home.mapDir);
             if ('refusal' in r) return { status: 'refused', refusal: r.refusal, candidates: r.candidates };
             return { status: 'ok', drawn_at_commit: map.meta.commit, ...r };
         },
     },
-};
+    graph_estate: {
+        name: 'graph_estate',
+        side_effect: 'ro',
+        description:
+            'Estate index across registered projects: package users, where a name is used, advisory ' +
+            'reach. Other graph tools take `project`.',
+        input_schema: {
+            type: 'object',
+            required: ['query'],
+            properties: {
+                query: { type: 'string', enum: ['where-used', 'projects-using', 'advisory-impact'] },
+                name: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args) => {
+            const q = str(args, 'query');
+            const name = str(args, 'name');
+            if (q !== 'advisory-impact' && name === '') return { status: 'error', error: `${q || 'query'} needs a name` };
+            const db = openEstate();
+            if (!db) return { status: 'unavailable', error: 'no estate index — `agent-config code-graph projects index on`, then refresh each project' };
+            try {
+                if (q === 'projects-using') return { status: 'ok', projects: db.projectsUsing(name) };
+                if (q === 'where-used') return { status: 'ok', ...whereUsed(db, name) };
+                if (q === 'advisory-impact') return { status: 'ok', impact: advisoryImpact(db, name === '' ? null : name) };
+                return { status: 'error', error: `unknown query: ${q}` };
+            } finally {
+                db.close();
+            }
+        },
+    },
+});

package/src/scripts/network_sources.ts

@@ -24,6 +24,7 @@ import { isIP } from 'node:net';
 import * as path from 'node:path';
 
 import { encrypt } from './_lib/link_crypto.js';
+import { sourceId } from './_lib/source_id.js';
 import { sanitize_text } from './_lib/retrieval_sanitize.js';
 import { SourceError, resolveSource, type SourceRef } from './source_adapters.js';
 
@@ -207,26 +208,43 @@ export function quotedAnchor(text: string, needle: string): { line: number; quot
     return { line: i + 1, quote: words.slice(start, start + MAX_QUOTE_WORDS).join(' ') };
 }
 
-/** Codes source identities S1, S2, …; the identities leave only as ENC1 tokens in the round's intake.md. */
+/**
+ * Codes source identities; the identities leave only as ENC1 tokens in the round's intake.md.
+ * With an id key the codes are stable `src_…` ids (`_lib/source_id.ts`), equal across rounds;
+ * without one they are `S1, S2, …`, meaningful inside this round only.
+ */
 export class SourceCodebook {
     private readonly ids: string[] = [];
+    private readonly codes: string[] = [];
     private readonly tokens: string[] = [];
+    private readonly idKey: string | null;
 
-    constructor(private readonly key: string) {}
+    constructor(
+        private readonly key: string,
+        opts: { idKey?: string | null } = {},
+    ) {
+        this.idKey = opts.idKey ? opts.idKey : null;
+    }
 
     code(identity: string): string {
-        let i = this.ids.indexOf(identity);
+        const stable = this.idKey === null ? null : sourceId(identity, this.idKey);
+        let i = stable === null ? this.ids.indexOf(identity) : this.codes.indexOf(stable);
         if (i === -1) {
             this.ids.push(identity);
+            this.codes.push(stable ?? `S${String(this.ids.length)}`);
             this.tokens.push(encrypt(identity, this.key));
             i = this.ids.length - 1;
         }
-        return `S${String(i + 1)}`;
+        return this.codes[i] as string;
     }
 
     intakeMarkdown(): string {
-        const rows = this.tokens.map((token, i) => `- S${String(i + 1)}: ${token}`);
-        return ['# Sources', '', 'Identities are encrypted (`link_crypto`); tracked output names only the codes.', '', ...rows, ''].join('\n');
+        const rows = this.tokens.map((token, i) => `- ${this.codes[i] as string}: ${token}`);
+        const scope =
+            this.idKey === null
+                ? 'Codes are per-round (S1, S2, …) — no id key was available, so they do not match another round.'
+                : 'Codes are stable source ids (src_…), equal across rounds.';
+        return ['# Sources', '', 'Identities are encrypted (`link_crypto`); tracked output names only the codes.', scope, '', ...rows, ''].join('\n');
     }
 
     writeIntake(roundDir: string): void {

package/src/scripts/release.ts

@@ -152,8 +152,6 @@ const _HERE = fileURLToPath(import.meta.url);
 
 import {
     ArgparseExit,
-    AUGMENT_MARKETPLACE_JSON,
-    AUGMENT_PLUGIN_JSON,
     CHANGELOG,
     _set_changelog_reader,
     read_changelog_text,
@@ -169,7 +167,7 @@ import {
     REPO_ROOT,
     REPO_SLUG,
     SystemExitError,
-    set_augment_manifest_version,
+    set_plugin_manifest_versions,
     set_marketplace_version,
     set_template_pin,
     _rstrip,
@@ -939,8 +937,7 @@ function execute(
             set_package_version(PACKAGE_JSON, plan.target, plan.commits);
             set_lockfile_version(PACKAGE_LOCK_JSON, plan.target);
             set_marketplace_version(MARKETPLACE_JSON, plan.target);
-            set_augment_manifest_version(AUGMENT_PLUGIN_JSON, plan.target);
-            set_augment_manifest_version(AUGMENT_MARKETPLACE_JSON, plan.target);
+            set_plugin_manifest_versions(plan.target);
             set_template_pin(PROJECT_TEMPLATE, plan.target);
             writeReleasedSurface(plan.target);
             prepend_changelog(CHANGELOG, plan.changelog_entry);

package/src/scripts/release_drill.ts

@@ -44,6 +44,7 @@ import { releaseHoldPreflight } from './_lib/release_holds.js';
 import { SETTINGS_SURFACE_FIXTURE } from './_lib/release_settings_surface.js';
 import { die } from './release_publication.js';
 import { DERIVED_MARKER } from './_lib/release_highlights.js';
+import { listingManifestPaths } from './_lib/listing_manifests.js';
 import {
     AUGMENT_MARKETPLACE_JSON,
     AUGMENT_PLUGIN_JSON,
@@ -52,13 +53,14 @@ import {
     PACKAGE_JSON,
     PACKAGE_LOCK_JSON,
     PROJECT_TEMPLATE,
+    REPO_ROOT as ENV_REPO_ROOT,
 } from './release_env.js';
 
 /**
  * The files step 2 mutates on disk, diverted into memory for every scenario.
  *
  * The FakeWorld intercepts COMMANDS, not `fs` writes, and step 2's bump is
- * seven direct writes. Every scenario before 2026-09-03 passed `--resume` with
+ * ten direct writes. Every scenario before 2026-09-03 passed `--resume` with
  * `package.json` already at the target, so step 2 short-circuited and nothing
  * was ever written — the drill looked side-effect-free because no scenario had
  * reached the writing arm. The first `resume: false` scenario appended twelve
@@ -83,6 +85,7 @@ const _MUTATED_BY_STEP_2: readonly string[] = [
     MARKETPLACE_JSON,
     AUGMENT_PLUGIN_JSON,
     AUGMENT_MARKETPLACE_JSON,
+    ...listingManifestPaths(ENV_REPO_ROOT),
     PROJECT_TEMPLATE,
     SETTINGS_SURFACE_FIXTURE,
 ];

package/src/scripts/release_env.ts

@@ -24,6 +24,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { listingManifestPaths, setListingManifestVersion } from './_lib/listing_manifests.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // ---------------------------------------------------------------------------
@@ -293,6 +295,20 @@ function set_augment_manifest_version(p: string, version: string): void {
     fs.writeFileSync(p, jsonDumpsIndent(data, 2) + '\n', 'utf-8');
 }
 
+/**
+ * Every plugin and extension manifest the release keeps at the package
+ * version: the two `.augment-plugin/` twins and the two listing manifests that
+ * also pin the version inside their `npx` arguments. One entry point so
+ * `release.ts`, which sits past the source-size cap, spends one line on all four.
+ */
+function set_plugin_manifest_versions(version: string, root: string = REPO_ROOT): void {
+    set_augment_manifest_version(path.join(root, '.augment-plugin', 'plugin.json'), version);
+    set_augment_manifest_version(path.join(root, '.augment-plugin', 'marketplace.json'), version);
+    for (const p of listingManifestPaths(root)) {
+        setListingManifestVersion(p, version, (v) => jsonDumpsIndent(v, 2));
+    }
+}
+
 /** Update `metadata.version`; preserve 2-space indentation + UTF-8. */
 function set_marketplace_version(p: string, version: string): void {
     const data = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
@@ -374,6 +390,7 @@ export {
     commaGroup,
     jsonDumpsIndent,
     set_augment_manifest_version,
+    set_plugin_manifest_versions,
     set_marketplace_version,
     set_template_pin,
     pyLen,

package/src/scripts/release_mix_taxonomy.json

@@ -117,6 +117,9 @@
     { "prefix": "LICENSE", "category": "consumer" },
     { "prefix": "NOTICE", "category": "consumer" },
     { "prefix": "llms.txt", "category": "consumer" },
+    { "prefix": "gemini-extension.json", "category": "consumer" },
+    { "prefix": "gemini-extension-context.md", "category": "consumer" },
+    { "prefix": "assets/", "category": "consumer" },
 
     { "prefix": "AGENTS.md", "category": "governance" },
     { "prefix": "CLAUDE.md", "category": "governance" },

package/src/scripts/schemas/provenance-mechanism.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-mechanism.schema.json",
+  "title": "Provenance ledger mechanism decision",
+  "description": "One line of provenance/mechanisms.jsonl — a decision about one harvested mechanism: adopted, adapted, rejected, already present, missing, or deferred. Source-free by construction (council O5): no source id, no pin, no locator. What links a source to a mechanism lives in the local ledger under the user-global runtime/lineage/ and never in the tracked tree. Append-only; a later row for the same mechanism_id supersedes an earlier one. Contract: provenance/README.md. Enforced by src/scripts/lint_harvest_provenance.ts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mechanism_id", "verdict", "decided_at"],
+  "properties": {
+    "mechanism_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case slug naming the mechanism. A harvest citation marker may cite it; for a mechanism seeded from harvests.jsonl it equals the harvest_id."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["adopt", "adapt", "reject", "already", "gap", "deferred"],
+      "description": "adopt|adapt — realised in this repo; reject — decided against; already — present before the harvest; gap — wanted and missing; deferred — wanted, parked."
+    },
+    "realised_in": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Repo-relative paths where the mechanism lives, each optionally suffixed ':<line>'. Required for adopt and adapt; every path must exist."
+    },
+    "roadmap": {
+      "type": "string",
+      "description": "Repo-relative path of the roadmap that owns a gap or deferred mechanism, or the literal 'open' when nothing owns it yet."
+    },
+    "decided_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) of the decision."
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Why. Required for reject."
+    },
+    "reopen_if": {
+      "type": "string",
+      "minLength": 3,
+      "description": "The condition under which a rejection or deferral is reconsidered."
+    }
+  }
+}