akm-cli 0.9.26 → 0.9.27-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,131 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.27-alpha.1] - 2026-10-06
+
+### Fixed
+
+- **A codex dispatch with an output schema no longer leaves a temp folder
+  behind.** Every build of the codex command for a request with a schema made a
+  new `akm-codex-schema-*` folder in the OS temp dir for `--output-schema` and
+  nothing ever removed it (the builder has no post-run hook, and the file is read
+  after it returns), so a machine whose `/tmp` is tmpfs held a folder in RAM per
+  dispatch until reboot. The schema is now written once to akm's cache dir, in a
+  file named by its hash: concurrent units dispatching the same schema share it,
+  a rewrite is an atomic rename of identical bytes, and the only residue is one
+  small file per distinct schema.
+- **An index that has been updated ranks like a fresh index of the same files,
+  and `akm index --full` no longer doubles the full-text totals.** `entries_fts`
+  is contentless, and FTS5 cannot take a deleted row out of a contentless
+  table's BM25 totals (its row count, and the token counts the average document
+  length comes from). Every replaced or removed row left them one row too high:
+  40 notes read 40, then 41 after one edit, then 81 after `--full`, and a delete
+  never lowered them, so scores drifted away from what a fresh index gives.
+  SQLite has no command that recomputes them (`delete` and `rebuild` are refused
+  on a contentless table), so a delete that removes a row now stamps
+  `index_meta.ftsTotalsStale` in its own transaction, whichever process made it,
+  and the next `akm index` rebuilds the table from `entries` before it finishes:
+  about a second at 25,000 entries, and only when rows have left the table. A
+  row the write-path index replaced after an accepted proposal is settled the
+  same way, and an index that has already drifted is corrected by the first run
+  that replaces or removes a row.
+- **`akm improve` runs against an API that rejects `chat_template_kwargs`,
+  OpenAI's among them.** Improve's reflect, consolidate and judge calls always
+  ask for thinking off, and the client sends that as
+  `chat_template_kwargs.enable_thinking` and a top-level `enable_thinking`. A
+  strict API answers 400 `Unknown parameter: 'chat_template_kwargs'`, the retry
+  without the response schema sent both fields again, and `akm improve judge`
+  reported `judge timeout/error — routed to review`. No engine setting could
+  stop it: the call sites override the engine's `enableThinking`, and
+  `extraParams` can only add fields. A 4xx that names either field is now
+  answered by one retry without both (which may in turn fall back without the
+  schema), and akm stops sending them to that endpoint and model for the rest
+  of the process, as it already does for `response_format`.
+- **A lesson the model wrote without a `when_to_use` is no longer thrown away
+  silently by `akm proposal extract`.** The extract schema left `when_to_use`
+  optional while the parser dropped a lesson without one (or with one under 15
+  characters) and said nothing, so a model that followed the schema could
+  write a sound lesson that akm discarded and the session reported no
+  candidates: on akm-eval's extract eval qwen3.8-27b kept 3 of 11 expected
+  insights against 9 for gpt-oss-120b. Every property of the schema is now
+  required, `when_to_use` and `rationale_if_empty` included, with an empty
+  string for none (a memory or knowledge candidate needs no trigger, a
+  non-empty answer no rationale), which is also what a strict structured-output
+  provider needs; the prompt's output contract says the same. Any candidate the
+  contract still refuses, for this reason or another, is named in its session's
+  `warnings` as `<type>:<name> dropped: <reason>`.
+- **Distill's response schemas are valid for a strict structured-output
+  provider.** The client sends a response schema `strict: true`, and OpenAI
+  refuses one whose objects leave a property out of `required`: `400 Invalid
+  schema for response_format 'akm_response': ... Missing 'tags'`. The lesson
+  schema left out `tags`, and the knowledge schema `tags` and `sources`, so
+  the first distill request on such a provider always failed. After a 4xx the
+  client retries once without the schema, but a gateway that answers the same
+  rejection with a 502 is not retried, and every distill call through it
+  failed; the workaround, `supportsJsonSchema: false`, loses the guidance that
+  keeps a model from leaving out `when_to_use`. Every property is now
+  required, and an empty array stands for none (distill already dropped an
+  empty `tags` or `sources`).
+- **`akm improve` no longer reflects on an asset whose file a proposal would not
+  write, so accepting a reflect proposal no longer adds a second file.** A
+  skill's `references/a.md` is indexed as `knowledge/skills/<name>/references/a`,
+  but a proposal writes the path derived from that ref,
+  `knowledge/skills/<name>/references/a.md`. Nothing is there, so the proposal
+  was a `create`, and accepting it wrote a copy beside the skill's own file;
+  later proposals then revised the copy while the skill's file drifted. Reflect
+  now refuses before it calls the model, naming the file and the path a
+  proposal would write, and the loop records it as a skip (`unsupported_type`,
+  `file_outside_layout` in the `reflect_completed` event). This is the rule
+  0.9.26 added to `akm feedback --replace`. An asset that another bundle owns is
+  still refused by `createProposal` (#1000).
+- **An index that 0.9.1 wrote no longer crashes akm.** Every `akm index` on it
+  exited 70 with `null is not an object (evaluating 'doc.xrefs')`, `akm migrate
+  apply` and `akm index --full` did not help, and `akm search` failed with
+  `null is not an object (evaluating 'item.entry.quality')`; the only way out
+  was moving `index.db` aside. That layout (20) keeps the transitional
+  `entry_key`, `dir_path`, `stash_dir`, `entry_json` and `entry_type` columns
+  that layout 21 removed, each NOT NULL, beside the current columns, and leaves
+  `document_json` NULL on every row. The table had every column akm checks for,
+  so it was taken for a current one: the links migration read the NULL
+  documents, and no insert could ever have succeeded (`NOT NULL constraint
+  failed: entries.entry_key`). akm now treats a table that still has a retired
+  column as older than layout 21, as the compat notes already said: the
+  writable opener recreates its entries-keyed tables (the LLM enrichment cache
+  is kept) and the next `akm index` re-walks every source, and a read rebuilds
+  inline. An index that a failed open already half-migrated (layout stamp still
+  20, `search_text` dropped, `asset_links` created) recovers the same way.
+- **Two files that claim one ref no longer trade places in the index, and `akm
+  index` says so.** A skill's `references/a.md` and a note at
+  `knowledge/skills/x/references/a.md` are both the ref
+  `knowledge/skills/x/references/a`, and the index holds one row for it. The
+  first file a run persisted held it, so a full build followed the filesystem's
+  listing order (one bundle indexed on tmpfs and on ext4 held different files),
+  and the first incremental run after a full build handed the row to the other
+  file, because it drains only the directory that lost: with no file touched,
+  the row, its search entry and the text its vector is embedded from changed,
+  and the vector was dropped and recomputed. When a smaller-path file was added
+  later and then deleted, the ref also left the index until `--full`, although
+  its other file was still on disk. The file with the smaller path (code-point
+  order, as `akm show`'s refusal lists them) now holds the ref however the
+  directories are drained and the walk is ordered, a directory that gives a ref
+  up is drained again so the ref passes back when its holder goes, and each
+  pair is reported in the `warnings` of `akm index`, naming the file indexed
+  and the one skipped.
+- **Consolidate's plan schema and the session summary schema are valid for a
+  strict structured-output provider, and a new response schema can no longer
+  skip the rule.** The client sends a response schema `strict: true`, and
+  OpenAI refuses one whose objects leave a property out of `required`. The
+  consolidate plan left out `description` and `confidence`, and the session
+  summary `tags`, so the first request of every plan and every summary to such
+  a provider was refused. The client then retries without the schema and
+  remembers that per connection (endpoint and model), not per schema, so one
+  invalid schema also switched the response schema off for every valid one
+  that followed on that connection. Every property of both is now required: an
+  empty `description` keeps the memory's own, a null `confidence` records none
+  and an empty `tags` array is no tags, which is how all three were already
+  read. A contract test runs every schema akm sends through the rule, so a
+  property added later without being required fails CI.
+
 ## [0.9.26] - 2026-10-05
 
 The stable release of the 0.9.26 line: 0.9.26-alpha.1 and alpha.2, and the

package/dist/assets/prompts/consolidate-system.md

@@ -7,10 +7,10 @@ Rules:
 Return ONLY JSON (no prose, no code fences):
 {
   "operations": [
-    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 }
+    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset, or an empty string to keep the memory's own>", "confidence": 0.92 }
   ]
 }
 
-For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Omit the field rather than guessing if you are uncertain.
+For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Use `null` rather than guessing if you are uncertain.
 
 When the merged content includes an `updated` frontmatter field, the value MUST be a real ISO date string (e.g. `updated: 2026-05-20`). NEVER emit `updated: today`, `updated: {today}`, `updated: {today: null}`, `updated: now`, or any other literal placeholder/template-variable. If you do not have a real source-of-truth date, OMIT the `updated` field entirely — the post-processor will not invent one for you.

package/dist/assets/prompts/extract-session.md

@@ -48,13 +48,13 @@ Respond with EXACTLY one JSON object matching this shape:
       "type": "memory" | "lesson" | "knowledge",
       "name": "<kebab-case name, e.g. jwt-token; optionally under one kebab-case scope, e.g. auth/jwt-token>",
       "description": "<one sentence 20-400 chars>",
-      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "when_to_use": "<one sentence 15-400 chars for a lesson; an empty string for a memory or knowledge candidate>",
       "body": "<markdown body, 200-3000 chars typical>",
       "confidence": <number 0.0-1.0>,
       "evidence": "<one-line pointer to the moment in the session>"
     }
   ],
-  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+  "rationale_if_empty": "<one sentence when candidates is empty; an empty string otherwise>"
 }
 ```
 

package/dist/commands/improve/consolidate/pair-pass.js

@@ -92,7 +92,7 @@ export const PAIR_JUDGE_JSON_SCHEMA = {
         reason: { type: "string", maxLength: 400 },
     },
 };
-const PAIR_CHECK_JSON_SCHEMA = {
+export const PAIR_CHECK_JSON_SCHEMA = {
     type: "object",
     required: ["missing"],
     additionalProperties: false,

package/dist/commands/improve/consolidate.js

@@ -93,7 +93,9 @@ export function isHotCapturedMemory(filePath) {
 /**
  * Structured-output schema for a plan. Promote-only: merge/delete/contradict
  * were removed in 0.9.17-alpha.1 (`e82eec811`) after running in production —
- * they cost thousands of completion tokens.
+ * they cost thousands of completion tokens. Every property is required, as a
+ * strict structured-output provider needs: an empty `description` keeps the
+ * memory's own, a null `confidence` is none.
  */
 export const CONSOLIDATE_PLAN_JSON_SCHEMA = {
     type: "object",
@@ -105,15 +107,23 @@ export const CONSOLIDATE_PLAN_JSON_SCHEMA = {
             description: "Ordered list of promote operations the planner proposes.",
             items: {
                 type: "object",
-                required: ["op", "ref", "knowledgeRef", "reason"],
+                required: ["op", "ref", "knowledgeRef", "reason", "description", "confidence"],
                 additionalProperties: false,
                 properties: {
                     op: { type: "string", enum: ["promote"] },
                     ref: { type: "string", minLength: 1 },
                     knowledgeRef: { type: "string", minLength: 1 },
                     reason: { type: "string", minLength: 1, maxLength: 200 },
-                    description: { type: "string" },
-                    confidence: { type: "number", minimum: 0, maximum: 1 },
+                    description: {
+                        type: "string",
+                        description: "One sentence describing the new knowledge asset; an empty string keeps the memory's own.",
+                    },
+                    confidence: {
+                        type: ["number", "null"],
+                        minimum: 0,
+                        maximum: 1,
+                        description: "Certainty in [0, 1] that the operation is correct and safe; null when unsure.",
+                    },
                 },
             },
         },

package/dist/commands/improve/distill.js

@@ -72,9 +72,13 @@ export function deriveLessonRef(inputRef) {
     return `lessons/${safeScope ? `${safeScope}/` : ""}${clean(`${parsed.type}-${parts.join("-")}`)}-lesson`;
 }
 // ── Output contract ──────────────────────────────────────────────────────────
+//
+// The client sends a response schema `strict: true`, and a strict provider
+// (OpenAI's) rejects an object whose `required` leaves out any of its
+// properties, so every property is required and "none" is an empty array (#1046).
 export const DISTILL_LESSON_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "when_to_use", "body"],
+    required: ["description", "when_to_use", "body", "tags"],
     additionalProperties: false,
     properties: {
         description: {
@@ -95,13 +99,13 @@ export const DISTILL_LESSON_JSON_SCHEMA = {
         tags: {
             type: "array",
             items: { type: "string" },
-            description: "Optional tag list. Empty array is allowed; the post-processor drops it if empty.",
+            description: "Tag list. Use an empty array for none; the post-processor drops it if empty.",
         },
     },
 };
 export const DISTILL_KNOWLEDGE_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "body"],
+    required: ["description", "body", "tags", "sources"],
     additionalProperties: false,
     properties: {
         description: { type: "string", minLength: 1, description: "One-line summary of the knowledge asset." },
@@ -113,12 +117,12 @@ export const DISTILL_KNOWLEDGE_JSON_SCHEMA = {
         tags: {
             type: "array",
             items: { type: "string" },
-            description: "Optional tag list. Empty array is allowed; the post-processor drops it if empty.",
+            description: "Tag list. Use an empty array for none; the post-processor drops it if empty.",
         },
         sources: {
             type: "array",
             items: { type: "string" },
-            description: "Optional list of source refs the knowledge was distilled from.",
+            description: "Source refs the knowledge was distilled from. Use an empty array for none.",
         },
     },
 };

package/dist/commands/improve/extract-prompt.js

@@ -24,16 +24,21 @@ const EXTRACT_CANDIDATE_NAME_RE = new RegExp(EXTRACT_CANDIDATE_NAME_PATTERN);
  *
  * Shape:
  *   {
- *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
- *     "rationale_if_empty"?: string
+ *     "candidates": [{type, name, description, when_to_use, body, confidence, evidence}, ...],
+ *     "rationale_if_empty": string
  *   }
  *
  * `additionalProperties: false` at each level so any hallucinated keys are
- * dropped before parsing.
+ * dropped before parsing. Every property is required, as a strict structured-
+ * output provider needs (#1046), and an empty string stands for "none": a
+ * `when_to_use` only a lesson needs, a `rationale_if_empty` only an empty
+ * answer needs. Before, `when_to_use` was optional, so a model that followed
+ * the schema could leave it out of a lesson and the parser dropped the lesson
+ * (#1047).
  */
 export const EXTRACT_JSON_SCHEMA = {
     type: "object",
-    required: ["candidates"],
+    required: ["candidates", "rationale_if_empty"],
     additionalProperties: false,
     properties: {
         candidates: {
@@ -41,7 +46,7 @@ export const EXTRACT_JSON_SCHEMA = {
             description: "Zero or more durable-insight candidates extracted from the session.",
             items: {
                 type: "object",
-                required: ["type", "name", "description", "body", "confidence", "evidence"],
+                required: ["type", "name", "description", "when_to_use", "body", "confidence", "evidence"],
                 additionalProperties: false,
                 properties: {
                     type: {
@@ -62,9 +67,8 @@ export const EXTRACT_JSON_SCHEMA = {
                     },
                     when_to_use: {
                         type: "string",
-                        minLength: 15,
                         maxLength: 400,
-                        description: "Trigger sentence for the candidate; REQUIRED when type=lesson.",
+                        description: "Trigger sentence of at least 15 characters; REQUIRED when type=lesson (a lesson without one is dropped). An empty string for a memory or knowledge candidate.",
                     },
                     body: {
                         type: "string",
@@ -87,8 +91,7 @@ export const EXTRACT_JSON_SCHEMA = {
         },
         rationale_if_empty: {
             type: "string",
-            minLength: 10,
-            description: "Required when `candidates` is empty — explains why nothing rose to durable-insight level.",
+            description: "When `candidates` is empty, one sentence on why nothing rose to durable-insight level; an empty string otherwise.",
         },
     },
 };
@@ -214,10 +217,47 @@ function parseFirstJsonObject(stdout) {
     }
     return { objectFound: true };
 }
+/** The candidate the model wrote when the contract keeps it, else the first rule it breaks. */
+function readCandidate(c) {
+    const { type, name, description, body, confidence, evidence } = c;
+    if (type !== "memory" && type !== "lesson" && type !== "knowledge") {
+        return { problem: "type is not memory, lesson or knowledge" };
+    }
+    if (typeof name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(name)) {
+        return { problem: "name is not a kebab-case slug" };
+    }
+    if (typeof description !== "string" || description.trim().length < 20) {
+        return { problem: "description is shorter than 20 characters" };
+    }
+    if (typeof body !== "string" || body.trim().length < 50)
+        return { problem: "body is shorter than 50 characters" };
+    if (typeof confidence !== "number" || !Number.isFinite(confidence))
+        return { problem: "confidence is not a number" };
+    if (typeof evidence !== "string" || evidence.trim().length < 5) {
+        return { problem: "evidence is shorter than 5 characters" };
+    }
+    // An empty string is how a strict-schema reply says "none".
+    const whenToUse = typeof c.when_to_use === "string" ? c.when_to_use.trim() : "";
+    if (type === "lesson" && whenToUse.length < 15) {
+        return { problem: "a lesson needs a when_to_use of at least 15 characters" };
+    }
+    return {
+        candidate: {
+            type,
+            name,
+            description: description.trim(),
+            ...(whenToUse ? { when_to_use: whenToUse } : {}),
+            body,
+            confidence: Math.max(0, Math.min(1, confidence)),
+            evidence: evidence.trim(),
+        },
+    };
+}
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
  * Defensive — drops candidates that violate the shape rather than failing
- * the whole call. Returns the empty-candidates payload when nothing parses.
+ * the whole call, and names each one in `dropped` so the run can say so.
+ * Returns the empty-candidates payload when nothing parses.
  */
 export function parseExtractPayload(stdout) {
     if (!stdout || stdout.trim().length === 0) {
@@ -238,42 +278,24 @@ export function parseExtractPayload(stdout) {
     }
     const rawCandidates = obj.candidates;
     const candidates = [];
+    const dropped = [];
     for (const raw of rawCandidates) {
-        if (!raw || typeof raw !== "object")
+        if (!raw || typeof raw !== "object") {
+            dropped.push("candidate dropped: not an object");
             continue;
+        }
         const c = raw;
-        const type = c.type;
-        if (type !== "memory" && type !== "lesson" && type !== "knowledge")
-            continue;
-        if (typeof c.name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(c.name))
-            continue;
-        if (typeof c.description !== "string" || c.description.trim().length < 20)
-            continue;
-        if (typeof c.body !== "string" || c.body.trim().length < 50)
+        const read = readCandidate(c);
+        if ("problem" in read) {
+            dropped.push(`${typeof c.type === "string" ? c.type : "candidate"}:${typeof c.name === "string" ? c.name : "(unnamed)"} dropped: ${read.problem}`);
             continue;
-        if (typeof c.confidence !== "number" || !Number.isFinite(c.confidence))
-            continue;
-        if (typeof c.evidence !== "string" || c.evidence.trim().length < 5)
-            continue;
-        if (type === "lesson") {
-            if (typeof c.when_to_use !== "string" || c.when_to_use.trim().length < 15)
-                continue;
         }
-        const confidence = Math.max(0, Math.min(1, c.confidence));
-        const candidate = {
-            type,
-            name: c.name,
-            description: c.description.trim(),
-            body: c.body,
-            confidence,
-            evidence: c.evidence.trim(),
-        };
-        if (typeof c.when_to_use === "string")
-            candidate.when_to_use = c.when_to_use.trim();
-        candidates.push(candidate);
+        candidates.push(read.candidate);
     }
     const result = { candidates };
-    if (typeof obj.rationale_if_empty === "string") {
+    if (dropped.length > 0)
+        result.dropped = dropped;
+    if (typeof obj.rationale_if_empty === "string" && obj.rationale_if_empty.trim()) {
         result.rationale_if_empty = obj.rationale_if_empty.trim();
     }
     return result;

package/dist/commands/improve/extract.js

@@ -468,7 +468,8 @@ async function processSession(run, sessionRef, gate) {
         });
     }
     const { payload } = extraction;
-    const warnings = [];
+    // A candidate the contract refused is reported, not silently lost (#1047).
+    const warnings = [...(payload.dropped ?? [])];
     // Provenance xrefs are added only after the cited session asset exists.
     const { warning, ...sessionAsset } = await maybeWriteSessionAsset(run, data);
     if (warning)

package/dist/commands/improve/reflect.js

@@ -13,11 +13,13 @@
  * pre-dispatch refusals still emit both).
  */
 import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
-import { resolveStashDir } from "../../core/common.js";
+import { isWithin, resolveStashDir, safeRealpath } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { generatedContentRejection } from "../../core/content-safety.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -248,7 +250,7 @@ export const REFLECT_JSON_SCHEMA = {
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
-const REFLECT_UNSCOPED_JSON_SCHEMA = {
+export const REFLECT_UNSCOPED_JSON_SCHEMA = {
     type: "object",
     required: ["ref", "confidence", "frontmatterPatch"],
     additionalProperties: false,
@@ -539,6 +541,24 @@ function unsupportedTypeFailure(ref, type, detail, emitFailed) {
         },
     };
 }
+/**
+ * A proposal writes the file derived from the ref's type and name under the bundle's root. An asset indexed
+ * anywhere else (a skill's `references/a.md` is `knowledge/skills/<name>/references/a`) has nothing there, so the
+ * proposal would be a `create` and accepting it would add a second file for the ref (#1052).
+ */
+function fileOutsideLayoutFailure(ref, file, writes, emitFailed) {
+    emitFailed("unsupported_type", "file_outside_layout", ref);
+    return {
+        failure: {
+            schemaVersion: 2,
+            ok: false,
+            reason: "unsupported_type",
+            error: `Reflect refused: the file for ${ref} is ${file}, but a proposal would write ${writes}. Edit the file directly.`,
+            ref,
+            exitCode: null,
+        },
+    };
+}
 /** The target's parsed ref and current content, or a refusal for a type reflect cannot patch. */
 async function resolveReflectSource(options, stash, emitFailed) {
     if (!options.ref)
@@ -549,18 +569,21 @@ async function resolveReflectSource(options, stash, emitFailed) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "secret material is never read or sent to an LLM", emitFailed);
     }
     let assetContent = options.assetContent;
+    let assetFile;
     if (assetContent === undefined) {
         try {
             const qualifiedRef = options.itemRef ?? options.ref;
             const localFilePath = await findAssetFilePath(qualifiedRef, stash);
             if (localFilePath && fs.existsSync(localFilePath)) {
-                assetContent = fs.readFileSync(localFilePath, "utf8");
+                assetFile = localFilePath;
             }
             else {
                 const entry = await lookup(parseRefInput(qualifiedRef));
                 if (entry?.filePath && fs.existsSync(entry.filePath))
-                    assetContent = fs.readFileSync(entry.filePath, "utf8");
+                    assetFile = entry.filePath;
             }
+            if (assetFile !== undefined)
+                assetContent = fs.readFileSync(assetFile, "utf8");
         }
         catch {
             // An index miss is not fatal: reflect then has no content to patch.
@@ -570,6 +593,15 @@ async function resolveReflectSource(options, stash, emitFailed) {
         (assetContent === undefined || parseFrontmatter(assetContent).frontmatter === null)) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "its content is not frontmatter + markdown", emitFailed);
     }
+    // A file in another bundle is `createProposal`'s to refuse (#1000); this one is in the proposal's own bundle.
+    const root = path.resolve(options.target?.root ?? stash);
+    const typeDir = stashDirFor(parsedRef.type);
+    if (assetFile !== undefined && typeDir !== undefined && isWithin(assetFile, root)) {
+        const writes = assetPathForName(parsedRef.type, path.join(root, typeDir), parsedRef.name);
+        if (safeRealpath(writes) !== safeRealpath(assetFile)) {
+            return fileOutsideLayoutFailure(options.ref, assetFile, writes, emitFailed);
+        }
+    }
     return { assetContent, parsedRef };
 }
 /**

package/dist/commands/improve/retrieval-gate.js

@@ -26,7 +26,7 @@ const MAX_QUERIES = 5;
 const MAX_QUERY_CHARS = 2000;
 /** The judge sees this much of the body, as in the retrieval eval. */
 const MAX_DOC_CHARS = 1500;
-const GRADE_SCHEMA = {
+export const GRADE_SCHEMA = {
     type: "object",
     required: ["grade", "reason"],
     additionalProperties: false,

package/dist/commands/improve/session-asset.js

@@ -14,9 +14,10 @@ import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
+// Every property is required, as a strict structured-output provider needs; an empty `tags` array is none.
 export const SESSION_SUMMARY_JSON_SCHEMA = {
     type: "object",
-    required: ["summary", "key_topics"],
+    required: ["summary", "key_topics", "tags"],
     additionalProperties: false,
     properties: {
         summary: { type: "string" },
@@ -61,7 +62,7 @@ export function buildSessionSummaryPrompt(data) {
         "Transcript:",
         renderTranscriptForSummary(data.events),
         "",
-        'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
+        'Respond as JSON: {"summary": string, "key_topics": string[], "tags": string[]} (an empty array for no tags).',
     ].join("\n");
 }
 /** The summary JSON, tolerating prose around it; `undefined` when nothing usable parses. */

package/dist/commands/improve/stage.js

@@ -370,7 +370,7 @@ function parseJudgeResponse(raw, keys) {
     }
     return inRange(parsed.score) ? { score: parsed.score, lowest: parsed.score, reason } : undefined;
 }
-function judgeResponseSchema(keys) {
+export function judgeResponseSchema(keys) {
     return {
         type: "object",
         required: ["scores", "reason"],