akm-cli 0.9.25-alpha.2 → 0.9.25-alpha.4

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

@@ -99,6 +99,12 @@ export function buildSessionAccessInstructions(harness, logPath, sessionId) {
             `Parse messages: jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ${logPath}`,
         ].join("\n");
     }
+    if (harness === "codex") {
+        return [
+            `Read with: cat ${logPath}`,
+            `Parse messages: jq -r 'select(.type=="response_item" and .payload.type=="message") | .payload.content[]? | .text // empty' ${logPath}`,
+        ].join("\n");
+    }
     if (harness === "opencode") {
         return [
             `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,

package/dist/commands/improve/stage.js

@@ -269,17 +269,27 @@ function buildChangedRegion(sourceContent, candidateContent) {
  */
 function reflectJudgeToolRules(ref) {
     const asset = ref ? `The asset is \`${ref}\`: read it with akm_show, ` : "Read an asset with akm_show ";
-    return `Tools: ${asset}or an asset the changed region names, only to verify a fact the revision adds or alters; the text above already shows every change. Do not search, do not read anything else, and do not use a tool to judge structure or wording. One or two reads at most. Before scoring, check three lists: (1) every statement the revision adds: find each in the asset, or as a fact the feedback states about the subject, and score QUALITY 1-2 if any is in neither; a statement is found only when the asset or the feedback says it, in any words: a new step, cause, consequence or detail that merely seems to follow is not found; feedback says what to fix and is not content, so an added statement about how the asset was used, found or verified is unsupported; (2) every fact, caveat and field of the source: find each in the revision, and score PRESERVATION 1-3 if any is missing; (3) every point the feedback makes: find the text it is about changed in the revision, and score NEED 2-3 if any is not; a note that restates the feedback does not address it. A read that finds nothing wrong raises no score above what these lists support. Then reply with the JSON.`;
+    return `Tools: ${asset}or an asset the changed region names, only to verify a fact the revision adds or alters; the text above already shows every change. Do not search, do not read anything else, and do not use a tool to judge structure or wording. One or two reads at most. Before scoring, check two lists: (1) every statement the revision adds: find each in the asset, or as a fact the feedback states about the subject, and score QUALITY 1-2 if any is in neither; a statement is found only when the asset or the feedback says it, in any words: a new step, cause, consequence or detail that merely seems to follow is not found; feedback says what to fix and is not content, so an added statement about how the asset was used, found or verified is unsupported; (2) every fact, caveat and field of the source: find each in the revision, and score PRESERVATION 1-3 if any is missing. A read that finds nothing wrong raises no score above what these lists support. Then reply with the JSON.`;
 }
+/**
+ * The reflect judge's rubric, for the frontmatter-only revisions reflect makes, and the paragraph that says what
+ * drove the revision: negative feedback (any `[negative]` line) or maintenance. Tuned on the production model
+ * against 113 reviewed proposals (the stash's eval/judge-gate/tuning/reflect/judge-fm, rubric f07).
+ */
+const REFLECT_JUDGE_INTRO = "You are evaluating a proposed revision of an existing akm asset's frontmatter. The revision may change only the `description`, the `when_to_use` and the title (a level-1 heading added when the body has none); the body is unchanged.";
+const REFLECT_JUDGE_NEGATIVE = "This revision answers negative feedback. It cannot change the body, so it need not resolve the feedback: judge only the fields it changes, and never fault it for a field it leaves as it was. Most negative feedback says the asset did not help with a task it was retrieved for: a retrieval miss, not a defect. It justifies changing a field only when the field claims more than the body covers (narrow it to what the body covers), or when the feedback calls the asset stale, outdated, superseded or historical (a new `when_to_use` must then name the version or date the body records). Feedback about a task the asset never claims to cover justifies no change. Repairing a missing or broken field is always needed, whatever the feedback says.";
+const REFLECT_JUDGE_MAINTENANCE = "This revision is maintenance: there is no negative feedback. Only a missing or broken field needs a change; rewording a sound `description` or `when_to_use` is churn, however accurate.";
 /** Judge prompt for an in-place revision. `tools` is set when the judge runs on an agent engine. */
 export function buildReflectJudgePrompt(candidateContent, sourceContent, feedback, tools) {
     return [
-        "You are evaluating a proposed revision to an existing akm asset.",
+        REFLECT_JUDGE_INTRO,
+        "",
+        feedback.some((line) => line.startsWith("[negative]")) ? REFLECT_JUDGE_NEGATIVE : REFLECT_JUDGE_MAINTENANCE,
         "",
         "Score this revision on each criterion from 1 (poor) to 5 (excellent):",
-        "1. NEED: Does the revision fix a concrete problem in the source? Concrete problems are: something the feedback reports as wrong or missing; a factual error; broken, garbled, truncated or missing text; and a missing or broken title, description or when_to_use field. Compare the source's description with the revision's: a description with a sentence split in its middle by a stray period or line-wrap artifact (as in 'calls. asset writes'), an unbalanced or escaped quote, or a truncated ending is broken, and repairing it is a concrete problem fixed even when the rest of the revision only adds stamps or reformats; adding or removing a trailing period, or rewording a readable description, repairs nothing. A missing title, description or when_to_use is a concrete problem whether or not the feedback mentions it: empty or positive feedback does not mean the source was complete, and the frontmatter is complete only when it has all three. A when_to_use is missing when the frontmatter has none, even if the body has a 'when to use' section; moving or copying that text into the field is the fix. A missing type field or a provenance stamp such as generated or verified is not a concrete problem. Score 4-5 when the revision fixes one, even a small one, whatever else it also reformats. Score 1-2 when the source was already complete and correct and the revision only rewords, restates, reformats, adds a type field or a stamp, or adds headings, an introduction or a table of contents.",
-        "2. PRESERVATION: Does it keep every concrete fact, identifier, command, path, number, example, caveat and frontmatter field from the source, without truncation? Check the changed region line by line. Score 1-3 when any of them is dropped or weakened, even when the revision also fixes something. Trimming narrative that states no fact, or removing what the feedback asks to remove or rescope, is not a drop.",
-        "3. QUALITY: Is it coherent and accurate, with no claims, steps or details that the source or the feedback does not support? Check each added or changed statement against the source and the feedback: a statement that follows from either counts as supported, and frontmatter stamps such as type, generated, verified or quality, whatever their values, and a restatement of existing content are not claims. Score 1-2 when the revision adds a claim neither supports, turns a draft or proposal into a decision, strengthens a statement beyond the source (a preference into a requirement, a possibility into a fact, a pending fix into a done one), adds a hedge such as 'may be outdated', or a placeholder such as 'TODO' or 'verify'; a fix elsewhere in the revision does not raise this score.",
+        "1. NEED: Does every changed field fix a real problem? Real problems: a missing `description`, `when_to_use` or title; a broken description (a sentence split by a stray period at a line wrap, an escaped or unbalanced quote, a truncated ending, a heading fragment); and, for a revision answering negative feedback, a field that claims more than the body covers, or a stale note's `when_to_use` that does not name the version or date the body records. Replacing a stray period that splits a sentence with a comma, a word or nothing repairs a broken description, however small the change looks. Score 4-5 when every changed field fixes one. Score 1-2 when any changed field rewrites a sound field. Score NEED on the changed fields alone: leaving negative feedback about the body unresolved never lowers it.",
+        "2. PRESERVATION: Does the new description keep every fact the old one carried: names, identifiers, numbers, versions, paths, qualifiers and status words such as 'Proposal' or 'draft'? Are all other frontmatter fields unchanged? Score 1-3 when anything is dropped or changed.",
+        "3. QUALITY: Is every new value supported by the body, without inventing, over-claiming or misdescribing? Check each new value as a claim against the body; restating the body in other words is supported. Score only values the revision adds or changes: a field it leaves as it was, however stale, is never this revision's fault. Score 1-2 when a new value says something the body does not support or the opposite of what it says, keeps a truncated or garbled fragment, or offers a dated or historical note for current work: when the feedback calls the note stale, outdated, superseded or historical, or the body records the version or date it was true for, a new `when_to_use` that does not name that version or date, or a new value that calls a dated snapshot 'current', scores 1-2.",
         "",
         "Feedback:",
         "```",

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -333,7 +333,11 @@ const redactedContentValidator = {
         ];
     },
 };
-/** Defense in depth when a reflect proposal bypasses creation-time sanitization (#963). */
+/**
+ * The run-only "Avoid These Patterns" section (#963) in a reflect proposal: one
+ * made before reflect kept the body, or a body that already had it. Reflect
+ * keeps a body as it is, so a person accepting has no way to remove it.
+ */
 const reflectPromptScaffoldingValidator = {
     name: "reflect-prompt-scaffolding",
     appliesTo(proposal) {
@@ -361,15 +365,15 @@ function advisory(validator) {
         validate: (proposal, ctx) => validator.validate(proposal, ctx).map((finding) => ({ ...finding, severity: "warn" })),
     };
 }
-/** The quality validators `validateProposal` runs; the last three protect durable content and block. */
+/** The quality validators `validateProposal` runs; the last two protect durable content and block. */
 export const defaultProposalQualityValidators = [
     ...[
         descriptionQualityValidator,
         lessonContentQualityValidator,
         sourceNotSupersededValidator,
         reflectSizeGuardValidator,
+        reflectPromptScaffoldingValidator,
     ].map(advisory),
     reflectTruncationMarkerValidator,
     redactedContentValidator,
-    reflectPromptScaffoldingValidator,
 ];

package/dist/commands/proposal/validators/proposal-validators.js

@@ -131,14 +131,13 @@ export const defaultProposalValidators = [
  * and was previously safe to run in full there because every quality
  * validator was advisory (`advisory()` downgrades findings to `severity:
  * "warn"`, which {@link runProposalValidators}'s `ok` never treats as
- * failing). Blocking durable-content validators (the #952 truncation marker,
- * #962 redaction marker, and #963 reflected prompt scaffolding) deliberately
+ * failing). Blocking durable-content validators (the #952 truncation marker
+ * and #962 redaction marker) deliberately
  * remain outside this subset, so running the full
  * {@link defaultProposalValidators} list at mint time could throw
  * `invalid_canonical_structure` for any lesson/task/workflow reflect
- * proposal whose body leaks the truncation marker — instead of letting
- * `sanitizeReflectPayload` mint the proposal and defer it with
- * `reflect-truncation-leak`, per the #952 design. Quality validators (prose
+ * proposal whose body carries the truncation marker — instead of minting it
+ * for a person to review. Quality validators (prose
  * shape, reflect size ratio, and durable-content guards) belong at
  * `proposal accept` / drain-promotion time, which already calls
  * {@link validateProposal} (the full list) via `preflightProposalPromotion`

package/dist/core/asset/asset-serialize.js

@@ -95,7 +95,7 @@ export function assembleAsset(frontmatter, body) {
  *   - exactly one `\n` terminates the file
  *
  * This helper is the single point of truth for the fence-and-body template.
- * Three command surfaces (`reflect`, `distill`, `consolidate`) call it
+ * Two command surfaces (`distill`, `consolidate`) call it
  * directly because their inputs are pre-validated LLM payloads where the
  * full `yamlStringify` may emit shapes (`|`-block scalars, anchors) that
  * the project's hand-rolled `parseFrontmatter` subset parser cannot read.

package/dist/core/content-safety.js

@@ -6,36 +6,12 @@ export const REDACTED_CONTENT_MARKER = "[REDACTED]";
 /** Reflect prompt section that contains run diagnostics, not proposed asset content. */
 export const REFLECT_AVOID_PATTERNS_HEADING = "Avoid These Patterns";
 const REFLECT_AVOID_PATTERNS_RE = /^##[ \t]+Avoid These Patterns[ \t]*$/i;
-const SECTION_BOUNDARY_RE = /^#{1,2}(?:[ \t]+|$)/;
 export function containsRedactedContent(content) {
     return content.includes(REDACTED_CONTENT_MARKER);
 }
 export function containsReflectPromptScaffolding(content) {
     return content.split(/\r?\n/).some((line) => REFLECT_AVOID_PATTERNS_RE.test(line));
 }
-/**
- * Remove every echoed run-only "Avoid These Patterns" section while preserving
- * the next peer/top-level section. Reflect alone calls this sanitizer; authored
- * source assets are never rewritten by this helper.
- */
-export function stripReflectPromptScaffolding(content) {
-    const newline = content.includes("\r\n") ? "\r\n" : "\n";
-    const lines = content.split(/\r?\n/);
-    const kept = [];
-    let stripped = false;
-    for (let index = 0; index < lines.length;) {
-        if (!REFLECT_AVOID_PATTERNS_RE.test(lines[index] ?? "")) {
-            kept.push(lines[index] ?? "");
-            index += 1;
-            continue;
-        }
-        stripped = true;
-        index += 1;
-        while (index < lines.length && !SECTION_BOUNDARY_RE.test(lines[index] ?? ""))
-            index += 1;
-    }
-    return { content: kept.join(newline).replace(/(?:\r?\n){3,}/g, `${newline}${newline}`), stripped };
-}
 /**
  * Return a secret-free rejection reason when generated content is unsafe to
  * persist. `redactedContent` is the same body after applying the dispatch

package/dist/integrations/agent/prompts.js

@@ -70,10 +70,8 @@ function knownTypeList() {
 export const REFLECT_CONTENT_CAP = 12_000;
 /**
  * Marker appended to truncated asset content when it exceeds the active
- * content budget (#952). Exported so `sanitizeReflectPayload` can detect a
- * model that echoed this notice back into its rewrite instead of proposing
- * real content, and so the output contracts can reference the exact string
- * to forbid.
+ * content budget (#952). Exported so the proposal validators can refuse a body
+ * that still carries it.
  */
 export const REFLECT_TRUNCATION_MARKER = "... [truncated — focus on the visible portion]";
 /**
@@ -119,16 +117,12 @@ export function reflectResponseContract(mode, targetScoped) {
     if (mode === "json_schema") {
         return reflectLlmSchemaContract
             .replace("{{FIELD_RULE}}", targetScoped
-            ? "The response has exactly the required fields `content`, `confidence`, and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
-            : "The response has exactly the required fields `ref`, `content`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
-            .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
+            ? "The response has exactly the required fields `confidence` and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
+            : "The response has exactly the required fields `ref`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
             .trim();
     }
     const refLine = targetScoped ? "" : "AKM_REFLECT_REF: <selected asset ref>\n";
-    return reflectLlmFramedContract
-        .replace("{{REF_LINE}}", refLine)
-        .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
-        .trim();
+    return reflectLlmFramedContract.replace("{{REF_LINE}}", refLine).trim();
 }
 export function buildReflectOutputRepairPrompt(mode, targetScoped) {
     return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectResponseContract(mode, targetScoped)).trim();
@@ -158,23 +152,47 @@ function sourceHasNonEmptyDescription(assetContent) {
     return value.length > 0;
 }
 /**
- * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
- * existing asset (plus any negative feedback / lint findings) and propose
- * an improved version. Returns a {@link ReflectPromptResult} containing the
- * prompt string and an optional character ceiling for max-tokens enforcement.
+ * The frontmatter problems akm can see for itself, named in the prompt so the
+ * model fixes them instead of having to spot them: a description split by a
+ * stray period or carrying an escaped quote, no `when_to_use`, no title. A
+ * missing description has its own instruction (#636).
+ */
+function frontmatterProblems(assetContent) {
+    const fm = assetContent?.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!assetContent || !fm)
+        return [];
+    const block = fm[1] ?? "";
+    const problems = [];
+    const raw = block
+        .match(/^description\s*:(.*(?:\r?\n[ \t]+.*)*)/m)?.[1]
+        ?.replace(/\s+/g, " ")
+        .trim() ?? "";
+    const split = [...raw.matchAll(/[\w`)\]]\. [a-z]/g)].find((m) => !/\b(?:e\.g|i\.e|vs|etc|cf)$/i.test(raw.slice(0, (m.index ?? 0) + 1)));
+    if (split) {
+        problems.push(`the \`description\` is broken: a stray period splits a sentence ("${raw}"); repair only the break, keeping its wording and every name, number, path and status word in it`);
+    }
+    else if (raw.includes('\\"')) {
+        problems.push("the `description` is broken by an escaped quote; repair only the quoting, keeping the rest of its wording");
+    }
+    if (!/^when_to_use\s*:\s*(?:\S|\r?\n[ \t]+\S)/m.test(block)) {
+        problems.push("there is no `when_to_use`: write one, a single sentence the body supports, saying when to reach for this asset");
+    }
+    if (!/^title\s*:\s*\S/m.test(block) && !/^#[ \t]+\S/m.test(assetContent.slice(fm[0].length))) {
+        problems.push("the body has no level-1 title: give one in `title`");
+    }
+    return problems;
+}
+/**
+ * Build the prompt for `akm reflect [ref]`. Asks the agent to check an
+ * existing asset's `description`, `when_to_use` and title against its body
+ * (plus any negative feedback / lint findings) and return the fields that
+ * need a fix. Returns a {@link ReflectPromptResult} containing the prompt
+ * string.
  */
 export function buildReflectPrompt(input) {
     const sections = [];
     if (input.ref && input.type && input.name) {
-        // Change 2 — type-conditioned goal framing
-        const isLesson = input.type === "lesson";
-        const isSkill = input.type === "skill";
-        const goalSentence = isLesson
-            ? `Your task is to distill what usage signals reveal about this ${input.type} asset — when to reach for it, what goes wrong without it, and what real use has revealed that the asset itself does not say. Do not reproduce the source content; your proposal must add information the source does not contain.`
-            : isSkill
-                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge/skills/<skill>/references/<topic>`."
-                : `Your task is to review this ${input.type} asset, identify what the feedback signals as broken, missing, or unclear, and produce an improved version. Do not reproduce the source content unchanged; your proposal must correct or add something the source lacks.`;
-        sections.push(goalSentence);
+        sections.push(`Your task is to check this ${input.type} asset's \`description\`, \`when_to_use\` and title against its body and the feedback below, and fix any that is missing, broken, or claims something the body does not cover. AKM keeps the body exactly as it is: you change only these fields, and when none needs a change you return null for each.`);
         sections.push(`Target ref: ${input.ref}`);
         sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
     }
@@ -200,12 +218,9 @@ export function buildReflectPrompt(input) {
         sections.push("Recent feedback / signals:");
         sections.push("- (no feedback events recorded)");
     }
-    else if (input.type === "skill" && input.relatedLessons && input.relatedLessons.length > 0) {
-        sections.push("No direct feedback events were recorded. Limit substantive changes to what is justified by the related distilled lessons below; do not speculate beyond that evidence.");
-    }
     else {
-        // ref is set but no feedback — explicitly constrain scope to schema compliance
-        sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
+        // ref is set but no feedback — explicitly constrain scope to broken or missing fields
+        sections.push("No usage feedback recorded. Fix only a missing or broken `description`, `when_to_use` or title; otherwise return null for each.");
     }
     if (input.standardsContext?.trim()) {
         sections.push("Standards to follow (the rulebook for this target):");
@@ -253,7 +268,7 @@ export function buildReflectPrompt(input) {
         sections.push("```");
     }
     else if (input.ref) {
-        sections.push("(No existing content — propose a fresh asset that fits the ref.)");
+        sections.push("(No existing content.)");
     }
     else {
         sections.push("(No existing asset content was supplied.)");
@@ -263,23 +278,10 @@ export function buildReflectPrompt(input) {
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
-    if (input.relatedLessons && input.relatedLessons.length > 0) {
-        sections.push("Related distilled lessons to evaluate for consolidation:");
-        for (const lesson of input.relatedLessons) {
-            sections.push(`Lesson ref: ${lesson.ref}`);
-            sections.push("```");
-            sections.push(lesson.content.trimEnd());
-            sections.push("```");
-        }
-        sections.push("Evaluate whether these lessons contain strong evidence of factual, repeatable guidance that should be promoted into long-term skill documentation.");
-        sections.push("Promote only guidance that is durable, generally applicable, and supported by repeated evidence. Do not copy anecdotal details, one-off incidents, or duplicate wording verbatim.");
-        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge/skills/<skill>/references/<topic>` proposal instead.");
-    }
     if (input.rejectedProposals && input.rejectedProposals.length > 0) {
         const lines = ["## Previously Rejected Proposals"];
         lines.push("The following proposals for this ref were already reviewed and rejected. " +
-            "Do NOT reproduce the same content or the same structural shape. " +
-            "Your new proposal must meaningfully differ from each of these in its approach, framing, or evidence used.");
+            "Do not propose the same change again; if no other change is justified, return null for each field.");
         for (const rp of input.rejectedProposals) {
             lines.push(`\nRef: ${rp.ref}`);
             lines.push(`Rejection reason: ${rp.reason}`);
@@ -303,58 +305,16 @@ export function buildReflectPrompt(input) {
             "The following is your previous draft proposal. " +
             "Identify specific weaknesses: missing evidence, vague wording, incomplete frontmatter, " +
             "or claims that duplicate existing content without adding new signal. " +
-            "Then produce an improved version that addresses those weaknesses. " +
-            "The revised proposal must be meaningfully better than the draft below — " +
-            "do not return the same content unchanged.\n\n" +
+            "Then produce an improved version that addresses those weaknesses.\n\n" +
             "Previous draft:\n```\n" +
             input.priorDraft.trimEnd() +
             "\n```");
     }
-    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract. If the proposal's frontmatter is missing `when_to_use`, you MUST generate one — a one-line trigger sentence describing exactly when a user should reach for this asset.");
-    // Content-preservation safety rails (#reflect-pipeline-fixes).
-    // These rules counter the observed failure modes where reflect rewrites
-    // asset content into shorter prose, drops concrete structure, or strips
-    // load-bearing frontmatter. Loud and explicit so small models follow.
-    //
-    // Guard-audit finding 15: this used to also hand back a maxOutputChars
-    // value so an LLM-path caller could convert it into a hard `max_tokens`
-    // cap on the API request. llm/client.ts's own doc comment (and
-    // commands/improve/reflect.ts's recorded history of responses actually
-    // getting cut off) is explicit that a character-derived max_tokens causes
-    // silent truncation — a real model's output is measured in tokens, not
-    // characters, and the ratio between the two varies enough that any fixed
-    // conversion either truncates legitimate output or provides no real cap at
-    // all. The size policy below is already enforced twice more (the prompt
-    // rules the model reads, and the post-processor's own size check), so nothing
-    // is lost by not adding a THIRD, byte-derived enforcement point that can
-    // only ever cut a response off early, never usefully re-check it.
     if (input.ref && input.assetContent?.trim()) {
-        // Strip frontmatter to get source body length — mirrors checkReflectSize which
-        // compares body-only lengths. Inline regex avoids importing parseFrontmatter.
-        const rawContent = input.assetContent.trimEnd();
-        const fmBodyMatch = rawContent.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
-        const sourceBodyLen = (fmBodyMatch ? fmBodyMatch[1] : rawContent).trim().length;
-        // Compute concrete char bounds matching checkReflectSize constants:
-        //   REFLECT_SIZE_GUARD_MIN_BYTES=200, REFLECT_SHRINK_RATIO_MIN=0.5,
-        //   REFLECT_ABSOLUTE_FLOOR_BYTES=150, REFLECT_EXPAND_RATIO_MAX=2.5,
-        //   REFLECT_ABSOLUTE_CEILING_BYTES=2500, REFLECT_ABSOLUTE_MAX_BYTES=25000.
-        // Embed concrete counts only when the gate will actually fire (source >= 200 chars).
-        const showCharBounds = sourceBodyLen >= 200;
-        const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
-        // A source already past the 25000 cap may not grow, and need not shrink to the cap.
-        const maxChars = Math.max(Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000), sourceBodyLen);
-        sections.push([
-            "## Content preservation rules (MUST follow)",
-            "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
-            "2. PRESERVE the source asset's frontmatter. The post-processor reassembles the final asset from the original frontmatter plus your body. Do NOT emit `---` frontmatter delimiters at the top of `content` — start `content` with the markdown body (e.g. `# Heading` or the first paragraph). If you include frontmatter anyway, identity fields (`name`, `ref`, `id`, `slug`, `type`) will be reset to the original values.",
-            showCharBounds
-                ? `3. DO NOT shrink the asset. Your body must be at least ${minChars} characters (source body is ${sourceBodyLen} chars; floor is 50%). If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. \`<!-- removed obsolete section X because ... -->\`).`
-                : "3. DO NOT shrink the asset dramatically. The improved body must be at least 50% of the source body length. If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. `<!-- removed obsolete section X because ... -->`).",
-            showCharBounds
-                ? `4. DO NOT pad the asset with speculative material. Your body must be at most ${maxChars} characters (source body is ${sourceBodyLen} chars; ceiling is ${maxChars === sourceBodyLen ? "100%" : "250%"}). Do not add invented sections, hypothetical examples, or padding prose.`
-                : "4. DO NOT pad the asset with speculative material. The improved body must be at most 250% of the source body length unless the feedback explicitly requests added sections.",
-            "5. Improve clarity of surrounding prose, fix structural issues, add missing required frontmatter fields. Do NOT rewrite a runbook into an essay.",
-        ].join("\n"));
+        const problems = frontmatterProblems(input.assetContent);
+        sections.push(problems.length > 0
+            ? `akm found these problems in the asset; fix each one:\n${problems.map((p) => `- ${p}`).join("\n")}`
+            : "akm found no missing or broken field.");
     }
     sections.push(reflectResponseContract(input.outputMode ?? "json_schema", input.ref !== undefined));
     return { prompt: sections.join("\n\n") };

package/dist/integrations/harnesses/codex/index.js

@@ -1,23 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * OpenAI Codex CLI harness (P2 integration, plan §"The adapter contract").
- *
- * Per-harness barrel gathering the Codex integration surfaces:
- *   - agent command builder → ./agent-builder.ts    (codexBuilder)
- *   - result extractor      → ./result-extractor.ts (codexResultExtractor)
- *
- * It also defines {@link CodexHarness}, the {@link AkmHarness} descriptor that
- * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
- * config importer yet.
- */
 import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { codexBuilder } from "./agent-builder.js";
 import { codexResultExtractor } from "./result-extractor.js";
+import { CodexProvider } from "./session-log.js";
 export { codexBuilder, codexResumeArgs, writeCodexOutputSchemaFile } from "./agent-builder.js";
 export { codexResultExtractor } from "./result-extractor.js";
+export { CodexProvider } from "./session-log.js";
 /**
  * OpenAI Codex CLI.
  *
@@ -26,6 +17,8 @@ export { codexResultExtractor } from "./result-extractor.js";
 export class CodexHarness extends BaseHarness {
     id = "codex";
     displayName = "OpenAI Codex CLI";
+    // No `setupDetectionDir`: `~/.codex` holds credentials and session rollouts,
+    // not assets, so `akm setup` must not offer it as a stash source.
     agentBuilder = codexBuilder;
     resultExtractor = codexResultExtractor;
     // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
@@ -40,7 +33,9 @@ export class CodexHarness extends BaseHarness {
     // user config-dir var commonly exported in shell profiles, so it would stamp
     // identity onto manual runs (see `AkmHarness.presenceEnv`).
     presenceEnv = ["CODEX_SANDBOX"];
+    sessionLogProvider = () => new CodexProvider();
     capabilities = caps({
+        sessionLogs: true,
         agentDispatch: true,
         detection: true,
     });

package/dist/integrations/harnesses/codex/session-log.js

@@ -0,0 +1,211 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
+import { AbstractSessionLogProvider } from "../../session-logs/provider-base.js";
+/**
+ * Root directory holding Codex's rollout files, one per session, as
+ * `YYYY/MM/DD/rollout-<timestamp>-<thread-id>.jsonl`.
+ *
+ * Resolved per call (not memoized at module load) so `CODEX_HOME` — Codex's own
+ * override of `~/.codex` — can be set after import; tests point it at a fixture
+ * directory instead of the real history.
+ */
+function codexSessionsDir() {
+    return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "sessions");
+}
+/** Bytes read to get a rollout's first record, `session_meta`: its embedded base instructions make it 20-50 KB. */
+const META_PEEK_BYTES = 128 * 1024;
+/**
+ * User-role blocks Codex injects itself, which are not the person's words: the
+ * AGENTS.md instructions and the context tags it is known to wrap (environment,
+ * plugin recommendations, an invoked skill's text, ...). Any other block is kept:
+ * a stray bit of context costs less than a dropped reply.
+ */
+const INJECTED_CONTEXT_RE = /^\s*(?:# AGENTS\.md instructions[\s\S]*<\/INSTRUCTIONS>|<(environment_context|user_instructions|recommended_plugins|skill|turn_aborted)>[\s\S]*<\/\1>)\s*$/i;
+/** The `session_meta` record, always a rollout's first; `undefined` for any other record. */
+function parseSessionMeta(entry) {
+    const e = entry;
+    if (e?.type !== "session_meta" || !e.payload)
+        return undefined;
+    const { timestamp, cwd, source } = e.payload;
+    const startedAt = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    return {
+        ...(Number.isNaN(startedAt) ? {} : { startedAt }),
+        ...(typeof cwd === "string" ? { cwd } : {}),
+        isAgent: typeof source === "object" && source !== null && ("subagent" in source || "internal" in source),
+    };
+}
+/** The text of a message's or tool output's content: a plain string, or blocks whose images and audio carry none. */
+function blockText(blocks, keep = () => true) {
+    if (typeof blocks === "string")
+        return blocks;
+    if (!Array.isArray(blocks))
+        return "";
+    const parts = [];
+    for (const block of blocks) {
+        const text = block?.text;
+        if (typeof text === "string" && keep(text))
+            parts.push(text);
+    }
+    return parts.join("\n");
+}
+/**
+ * A tool call's input as text. A shell call surfaces its command line (`cmd`, or
+ * `command` as a string or an argv array) so the inline-ref scanner can match
+ * `akm remember "..."` without JSON-quote escaping mangling the regex; any
+ * other input stays as it was written.
+ */
+function toolInputText(input) {
+    let args = input;
+    if (typeof input === "string") {
+        try {
+            args = JSON.parse(input);
+        }
+        catch {
+            return input;
+        }
+    }
+    const fields = args && typeof args === "object" ? args : {};
+    const cmd = fields.cmd ?? fields.command;
+    if (typeof cmd === "string")
+        return cmd;
+    if (Array.isArray(cmd))
+        return cmd.join(" ");
+    return typeof input === "string" ? input : (JSON.stringify(input) ?? "");
+}
+/**
+ * Parse one rollout record into a normalized {@link SessionEvent}. The
+ * conversation lives in `response_item` records; the rest (`event_msg` UI events
+ * that repeat it, `turn_context`, `world_state`, token counts, compaction
+ * markers) and items with nothing to read (`reasoning` is encrypted) give
+ * `undefined`. Codex's `developer` messages are its own instructions, so they
+ * are skipped too.
+ *
+ * Tool calls become `[tool:<name>] <input>` and their results `[tool_result]
+ * <output>`, the shapes the Claude reader writes. A result is a `tool` event:
+ * Codex has no enclosing user message to give it.
+ */
+function parseCodexRecord(entry, sessionId, filePath, fallbackTsMs) {
+    const e = entry;
+    const item = e?.type === "response_item" ? e.payload : undefined;
+    if (!item)
+        return undefined;
+    const toolName = typeof item.name === "string" ? item.name : "tool";
+    let role = "assistant";
+    let text;
+    switch (item.type) {
+        case "message":
+            if (item.role !== "user" && item.role !== "assistant")
+                return undefined;
+            role = item.role;
+            text = blockText(item.content, item.role === "user" ? (t) => !INJECTED_CONTEXT_RE.test(t) : undefined);
+            break;
+        case "function_call":
+            text = `[tool:${toolName}] ${toolInputText(item.arguments)}`;
+            break;
+        case "custom_tool_call":
+            text = `[tool:${toolName}] ${typeof item.input === "string" ? item.input : ""}`;
+            break;
+        case "local_shell_call":
+            text = `[tool:shell] ${toolInputText(item.action)}`;
+            break;
+        case "function_call_output":
+        case "custom_tool_call_output": {
+            role = "tool";
+            const output = blockText(item.output);
+            text = output ? `[tool_result] ${output}` : "";
+            break;
+        }
+        default:
+            return undefined;
+    }
+    if (!text.trim())
+        return undefined;
+    const ts = typeof e?.timestamp === "string" ? Date.parse(e.timestamp) || fallbackTsMs : fallbackTsMs;
+    return { harness: "codex", text, ts, sessionId, role, filePath };
+}
+/**
+ * Codex native session-log reader.
+ *
+ * Events, refs, extraction keys, and the harness registry all use `codex`. The
+ * session id is the thread id in the rollout's file name (the id `codex resume`
+ * takes) and `projectHint` is the session's working directory.
+ */
+export class CodexProvider extends AbstractSessionLogProvider {
+    name = "codex";
+    availabilityRoot() {
+        return codexSessionsDir();
+    }
+    listSessions(input = {}) {
+        return this.listSessionsFromFiles({
+            sinceMs: input.sinceMs ?? 0,
+            enumerate: () => this.walkFiles(input.location ?? codexSessionsDir(), (name) => /^rollout-.+\.jsonl$/.test(name)),
+            summarize: (rolloutPath, stat) => {
+                const meta = this.#peekMeta(rolloutPath);
+                if (meta?.isAgent)
+                    return undefined;
+                return this.sessionRef({
+                    // The thread id is the 36-character UUID that ends the file name.
+                    sessionId: path.basename(rolloutPath, ".jsonl").slice(-36),
+                    filePath: rolloutPath,
+                    startedAt: meta?.startedAt ?? stat.ctimeMs,
+                    endedAt: stat.mtimeMs,
+                    projectHint: meta?.cwd,
+                });
+            },
+        });
+    }
+    readSession(ref) {
+        const stat = fs.statSync(ref.filePath);
+        const events = [];
+        const inlineRefs = [];
+        let meta;
+        for (const line of fs.readFileSync(ref.filePath, "utf8").split("\n").filter(Boolean)) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue; // a partial line (the session is still being written) or garbage
+            }
+            meta ??= parseSessionMeta(entry);
+            const parsed = parseCodexRecord(entry, ref.sessionId, ref.filePath, stat.mtimeMs);
+            if (!parsed)
+                continue;
+            events.push(parsed);
+            inlineRefs.push(...extractInlineRefMentions(parsed.text, parsed.ts));
+        }
+        return {
+            ref: this.sessionRef({
+                sessionId: ref.sessionId,
+                filePath: ref.filePath,
+                startedAt: meta?.startedAt ?? events[0]?.ts ?? stat.ctimeMs,
+                endedAt: events[events.length - 1]?.ts ?? stat.mtimeMs,
+                projectHint: meta?.cwd,
+            }),
+            events,
+            inlineRefs,
+        };
+    }
+    /** The `session_meta` record on a rollout's first line, read without loading the file. */
+    #peekMeta(filePath) {
+        try {
+            const fd = fs.openSync(filePath, "r");
+            try {
+                const head = Buffer.alloc(META_PEEK_BYTES);
+                const firstLine = head.toString("utf8", 0, fs.readSync(fd, head, 0, head.length, 0)).split("\n", 1)[0] ?? "";
+                return parseSessionMeta(JSON.parse(firstLine));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return undefined; // unreadable / vanished file, or a first line that is not one whole record
+        }
+    }
+}