akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/commands/improve/reflect.js

@@ -24,26 +24,28 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { assertNever } from "../../core/assert.js";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { lookup } from "../../indexer/indexer.js";
 import { runAgent, } from "../../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
 import { buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
 import { resolveImproveProcessRunnerFromProfile, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
+import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 import { chatCompletion } from "../../llm/client.js";
 import { isLlmFeatureEnabled } from "../../llm/feature-gate.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
-import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
+import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
 import { classifyReflectChange } from "./reflect-noise.js";
@@ -383,6 +385,101 @@ function splitFrontmatter(raw) {
         return { fmText: null, body: raw };
     return { fmText: m[1], body: m[2] };
 }
+/**
+ * Strip an LLM-appended duplicate frontmatter block from a body string.
+ *
+ * When the LLM echoes the original source file verbatim after its rewrite,
+ * the resulting body contains a second `---...---` YAML block. We detect it
+ * by requiring BOTH a balanced fence (opening + closing `---`) AND YAML-like
+ * `key: value` content inside, so legitimate Markdown thematic breaks and
+ * code-fence examples are never truncated.
+ */
+function stripAppendedFrontmatter(body) {
+    const fencePattern = /\n---\r?\n([\s\S]*?)\n---\r?\n/;
+    const match = body.match(fencePattern);
+    if (!match)
+        return body;
+    // Only strip when the captured block looks like YAML frontmatter.
+    if (!/^\w[\w-]*:/m.test(match[1]))
+        return body;
+    return body.slice(0, body.indexOf(match[0])).replace(/\s+$/, "");
+}
+/**
+ * #636 — deterministically derive a valid `description` from an asset's existing
+ * metadata when one is missing. Sources, in priority order: the `title:`
+ * frontmatter field, the first `# Heading` in the (proposed or source) body, and
+ * the first sentence of the opening body paragraph. The candidate is normalized
+ * (whitespace collapsed, trailing punctuation/markdown stripped, clamped to the
+ * description max) and only returned if it PASSES `isValidDescription` — so this
+ * never produces a heading-fragment, truncated, or otherwise gate-failing value.
+ * Returns `undefined` when nothing usable can be derived (caller leaves the
+ * proposal as-is rather than fabricating prose).
+ *
+ * This is intentionally deterministic and lives in the reflect proposal-build
+ * path — it does NOT touch the validators or the promote-time repair.
+ */
+function deriveDescriptionFromAsset(title, proposedBody, sourceBody, targetRef) {
+    // Each candidate is tagged with its kind. A title or `# Heading` is a bare
+    // fragment ("Paged.js — Named Page") that reads poorly as a description even
+    // when it is long enough to pass the length gate, so for those we prefer the
+    // padded sentence form. A prose sentence is already a sentence, so it is used
+    // as-is (padding it would double-wrap an already-complete sentence).
+    const candidates = [];
+    // 1. title: frontmatter
+    if (typeof title === "string" && title.trim())
+        candidates.push({ text: title.trim(), kind: "fragment" });
+    // 2. first `# Heading` (proposed body first, then source body)
+    for (const body of [proposedBody, sourceBody]) {
+        const headingMatch = body.match(/^#{1,6}\s+(.+?)\s*$/m);
+        if (headingMatch?.[1])
+            candidates.push({ text: headingMatch[1].trim(), kind: "fragment" });
+    }
+    // 3. first sentence of the opening prose paragraph (skip headings, fences,
+    //    list markers, blockquotes — those are not prose).
+    for (const body of [proposedBody, sourceBody]) {
+        const firstSentence = firstProseSentence(body);
+        if (firstSentence)
+            candidates.push({ text: firstSentence, kind: "prose" });
+    }
+    for (const { text, kind } of candidates) {
+        const normalized = normalizeDescriptionCandidate(text);
+        if (!normalized)
+            continue;
+        // For a title/heading fragment, try the padded sentence form FIRST so the
+        // result reads as a sentence rather than a bare fragment — a short but valid
+        // title like "Paged.js — Named Page" (21 chars) would otherwise be returned
+        // verbatim. Fall back to the bare form only if the padded form fails the
+        // gate. A prose candidate is already a sentence, so it is used as-is.
+        const variants = kind === "fragment" ? [`Reference notes on ${normalized}.`, normalized] : [normalized];
+        for (const v of variants) {
+            const clamped = v.length > DESCRIPTION_MAX_CHARS ? v.slice(0, DESCRIPTION_MAX_CHARS).trimEnd() : v;
+            if (isValidDescription(clamped, targetRef, { skipRefTailCheck: true }).ok)
+                return clamped;
+        }
+    }
+    return undefined;
+}
+/** Extract the first prose sentence from a markdown body, or `""` if none. */
+function firstProseSentence(body) {
+    for (const rawLine of body.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (/^(#{1,6}\s|```|~~~|[-*+]\s|\d+\.\s|>|\||<!--)/.test(line))
+            continue;
+        const sentenceMatch = line.match(/^(.+?[.!?])(\s|$)/);
+        return (sentenceMatch?.[1] ?? line).trim();
+    }
+    return "";
+}
+/** Normalize a description candidate: strip markdown markers, collapse space. */
+function normalizeDescriptionCandidate(raw) {
+    return raw
+        .replace(/`/g, "")
+        .replace(/^[#>*\-\s]+/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
 /**
  * Reflect post-processor — enforces the safety rails described at the top of
  * this file:
@@ -408,7 +505,7 @@ function splitFrontmatter(raw) {
  * from `payload.frontmatter` so identity fields can be enforced. Size guard
  * is skipped because there is no source to compare against.
  */
-function sanitizeReflectPayload(payload, sourceContent, targetRef) {
+export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
     const warnings = [];
     const { fmText: sourceFmText, body: sourceBody } = sourceContent
         ? splitFrontmatter(sourceContent)
@@ -449,7 +546,35 @@ function sanitizeReflectPayload(payload, sourceContent, targetRef) {
             mergedFm[field] = sourceFm[field];
         }
     }
-    const cleanedBody = rawLlmBody.replace(/^\s+/, "");
+    const cleanedBody = stripAppendedFrontmatter(rawLlmBody.replace(/^\s+/, ""));
+    // #636 — deterministic description fallback (reflect-side belt-and-suspenders).
+    // If the type requires a `description` and the merged frontmatter is still
+    // MISSING one (source had none AND the model didn't author one), derive a
+    // description DETERMINISTICALLY from the existing `title:` frontmatter or the
+    // first `# Heading` / opening body sentence — never free-form invention. This
+    // runs in the reflect proposal-build path, BEFORE the proposal is created, so
+    // the validator/promote path is left untouched (no gate fabricates content).
+    //
+    // Scope is the issue's target: a source asset that ALREADY carries frontmatter
+    // (e.g. scraped docs: `source`/`title`/`scraped`) but has a MISSING/empty
+    // `description`. We deliberately do NOT fire when:
+    //   - the source has no frontmatter block at all (injecting one would be a
+    //     structural change and would defeat the #580 no-op/cosmetic noise gate
+    //     for a pure body echo), or
+    //   - a present-but-otherwise-invalid description exists (too short, a heading
+    //     fragment) — overwriting authored content is out of scope; the prompt
+    //     instruction handles improving it instead.
+    const refType = targetRef.includes(":") ? (targetRef.split(":")[0] ?? "") : "";
+    const mergedDesc = mergedFm.description;
+    const descIsMissing = typeof mergedDesc !== "string" || mergedDesc.trim().length === 0;
+    const sourceHadFrontmatter = sourceFmText !== null && Object.keys(sourceFm).length > 0;
+    if (refType && requiresDescription(refType) && descIsMissing && sourceHadFrontmatter) {
+        const derived = deriveDescriptionFromAsset(mergedFm.title, cleanedBody, sourceBody, targetRef);
+        if (derived) {
+            mergedFm.description = derived;
+            warnings.push("Synthesized a deterministic `description` from title/heading (#636) — source and proposal lacked one.");
+        }
+    }
     // Size guard — only when source body is meaningfully large. The pure
     // predicate lives in `core/proposal-quality-validators` so the same check
     // also runs inside `runProposalValidators` on `proposal accept`.
@@ -585,6 +710,9 @@ export async function akmReflect(options = {}) {
         metadata: {
             ...(options.task ? { task: options.task } : {}),
             ...(options.profile ? { profile: options.profile } : {}),
+            // Attribution tagging: stamp the eligibility lane so reflect_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
         },
     });
     // Fix #3 (observability 0.8.0): every failure path below MUST emit
@@ -723,6 +851,9 @@ export async function akmReflect(options = {}) {
     // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
     // reproducing proposals that have already been reviewed and refused.
     const rejectedProposals = readRejectedProposals(stash, options.ref);
+    // Standards "rulebook" for this target — wiki schema (wiki page) or stash
+    // convention/meta facts (non-wiki asset); empty when neither fires.
+    const standardsContext = resolveStandardsContext(options.ref, stash);
     // 5. Spawn the agent — with optional Self-Refine loop (R-1 / #372).
     //
     // maxRefineIters controls how many agent invocations are made:
@@ -791,6 +922,7 @@ export async function akmReflect(options = {}) {
                 ...(schemaHints.length > 0 ? { schemaHints } : {}),
                 ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
                 ...(options.task ? { task: options.task } : {}),
+                ...(standardsContext.trim() ? { standardsContext } : {}),
                 ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
                 ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
                 // R-1: inject prior draft as self-critique target on iterations > 0
@@ -822,44 +954,39 @@ export async function akmReflect(options = {}) {
                 iterResult = await runAgent(resolvedProfile, prompt, runOptions);
             }
             else if (runnerSpec) {
-                // v2: dispatch through unified RunnerSpec
+                // v2: dispatch through the unified RunnerSpec seam (X3). The `agent` /
+                // `sdk` arms route to the default profile runners; the `llm` arm is
+                // reflect-specific (wraps `runReflectViaLlm` — its bespoke iteration
+                // shape) so it is supplied as the `llm` handler.
                 const runOptions = {
                     stdio: "captured",
                     parseOutput: "text",
                     ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
                 };
-                switch (runnerSpec.kind) {
-                    case "llm":
-                        // LLM HTTP path — `draftFilePath` is accepted for type symmetry
-                        // (see `RunReflectViaLlmOptions.draftFilePath` docstring) but is
-                        // intentionally a no-op. The prompt builder above also did not
-                        // include the file-write contract for this kind, so the LLM is
-                        // still asked for JSON via stdout.
-                        iterResult = await runReflectViaLlm({
-                            prompt,
-                            connection: runnerSpec.connection,
-                            timeoutMs: runnerSpec.timeoutMs ?? (typeof resolvedTimeoutMs === "number" ? resolvedTimeoutMs : undefined),
-                            priorDraft,
-                            iteration: iter,
-                            responseSchema: REFLECT_JSON_SCHEMA,
-                            chat: options.chat,
-                            ...(maxTokensForLlm !== undefined ? { maxTokens: maxTokensForLlm } : {}),
-                        });
-                        break;
-                    case "sdk":
-                        iterResult = await runOpencodeSdk(runnerSpec.profile, prompt ?? "", runOptions);
-                        break;
-                    case "agent":
-                        iterResult = await runAgent(runnerSpec.profile, prompt, {
-                            ...runOptions,
-                            ...(runnerSpec.timeoutMs !== undefined ? { timeoutMs: runnerSpec.timeoutMs } : {}),
-                        });
-                        break;
-                    default:
-                        // Exhaustiveness arm (H1): a 4th RunnerSpec kind becomes a compile
-                        // error here instead of leaving `iterResult` unassigned at runtime.
-                        assertNever(runnerSpec);
-                }
+                iterResult = await executeRunner(runnerSpec, prompt ?? "", runOptions, {
+                    llm: async (spec) => 
+                    // LLM HTTP path — `draftFilePath` is accepted for type symmetry
+                    // (see `RunReflectViaLlmOptions.draftFilePath` docstring) but is
+                    // intentionally a no-op. The prompt builder above also did not
+                    // include the file-write contract for this kind, so the LLM is
+                    // still asked for JSON via stdout.
+                    runReflectViaLlm({
+                        prompt,
+                        connection: spec.connection,
+                        timeoutMs: spec.timeoutMs ?? (typeof resolvedTimeoutMs === "number" ? resolvedTimeoutMs : undefined),
+                        priorDraft,
+                        iteration: iter,
+                        responseSchema: REFLECT_JSON_SCHEMA,
+                        chat: options.chat,
+                        ...(maxTokensForLlm !== undefined ? { maxTokens: maxTokensForLlm } : {}),
+                    }),
+                    // The `agent` arm (and only the agent arm — preserving prior behavior)
+                    // overlays `spec.timeoutMs` onto the base run options.
+                    runAgent: (profile, p, opts) => runAgent(profile, p, {
+                        ...opts,
+                        ...(runnerSpec.timeoutMs !== undefined ? { timeoutMs: runnerSpec.timeoutMs } : {}),
+                    }),
+                });
             }
             else {
                 // Production path (v1): dispatch directly to the appropriate runner.
@@ -1148,8 +1275,19 @@ export async function akmReflect(options = {}) {
     // (new-asset proposals have nothing to diff against).
     if (assetContent !== undefined) {
         const changeKind = classifyReflectChange(assetContent, payload.content);
-        if (changeKind !== "substantive") {
-            const subreason = changeKind === "noop" ? "reflect_skipped_noop" : "reflect_skipped_cosmetic";
+        // 'low-value' is config-gated (#639). DEFAULT OFF — absent = byte-identical
+        // pre-#639 behaviour (low-value treated the same as substantive). Resolved
+        // by the caller from the ACTIVE improve profile's
+        // `processes.reflect.lowValueFilter.enabled` and passed via options, so the
+        // running profile (not a hardcoded `profiles.improve.default`) decides.
+        const lowValueFilterEnabled = options.lowValueFilter === true;
+        const isDeferred = changeKind === "noop" || changeKind === "cosmetic" || (changeKind === "low-value" && lowValueFilterEnabled);
+        if (isDeferred) {
+            const subreason = changeKind === "noop"
+                ? "reflect_skipped_noop"
+                : changeKind === "low-value"
+                    ? "reflect_skipped_low_value"
+                    : "reflect_skipped_cosmetic";
             emitReflectFailed("no_change", subreason, options.ref, { changeKind });
             return {
                 schemaVersion: 1,
@@ -1157,7 +1295,9 @@ export async function akmReflect(options = {}) {
                 reason: "no_change",
                 error: changeKind === "noop"
                     ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
-                    : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
+                    : changeKind === "low-value"
+                        ? `Reflect skipped: proposed content for ${payload.ref} is a low-value prose micro-rewrite (few changed tokens, no structural changes); no proposal created.`
+                        : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
                 ...(options.ref ? { ref: options.ref } : {}),
                 exitCode: result.exitCode,
             };
@@ -1228,6 +1368,9 @@ export async function akmReflect(options = {}) {
         // `parseAgentProposalPayload` already clamps to [0, 1] and drops non-
         // finite values; `createProposal` runs its own sanitizer as a safety net.
         ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal so it
+        // survives to accept/reject/revert time even across runs. See EligibilitySource.
+        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
     };
     const proposalResult = createProposal(stash, createInput, options.ctx);
     if (isProposalSkipped(proposalResult)) {