akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -59,7 +59,17 @@
  */
 // ── Reflect-size guard ───────────────────────────────────────────────────────
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, WHEN_TO_USE_MAX_CHARS, WHEN_TO_USE_MIN_CHARS, } from "../../../core/authoring-rules.js";
+import { proposalContent } from "../../../core/file-change.js";
+/**
+ * The canonical asset NAME an inputRef names, lower-cased — the tail the
+ * "just restates the ref" heuristics compare against. WI-8.5c: the ref is the
+ * conceptId (`<subdir>/<name>`), so the name is parsed off the conceptId.
+ */
+function refNameTail(inputRef) {
+    return parseRefInput(inputRef).name.toLowerCase();
+}
 import { detectTruncatedDescription, TRUNCATION_TRAILING_WORDS } from "../../../core/text-truncation.js";
 // ── Description / when_to_use shape ─────────────────────────────────────────
 export const HEADING_FRAGMENT_PATTERNS = [
@@ -122,7 +132,7 @@ export function isValidDescription(value, inputRef, options = {}) {
             severity: "warn",
         };
     if (!options.skipRefTailCheck) {
-        const refTail = inputRef.split(":").pop()?.toLowerCase() ?? "";
+        const refTail = refNameTail(inputRef);
         if (refTail.length >= 6 && v.toLowerCase().includes(refTail) && v.length < refTail.length + 40)
             return { ok: false, reason: "description appears to just name the input ref" };
     }
@@ -140,7 +150,7 @@ export function isValidWhenToUse(value, inputRef) {
         return { ok: false, reason: `when_to_use is too long (${v.length} chars; max ${WHEN_TO_USE_MAX_CHARS})` };
     if (/^when working with\b/i.test(v))
         return { ok: false, reason: "when_to_use is the circular 'When working with ...' fallback" };
-    const refTail = inputRef.split(":").pop()?.toLowerCase() ?? "";
+    const refTail = refNameTail(inputRef);
     if (refTail.length >= 6 && v.toLowerCase().includes(refTail) && v.length < refTail.length + 25)
         return { ok: false, reason: "when_to_use appears to just name the input ref" };
     return { ok: true };
@@ -267,7 +277,7 @@ const descriptionQualityValidator = {
             return [];
         let fm;
         try {
-            fm = parseFrontmatter(proposal.payload.content).data;
+            fm = parseFrontmatter(proposalContent(proposal)).data;
         }
         catch {
             return [];
@@ -293,7 +303,7 @@ const lessonContentQualityValidator = {
             return [];
         let fm;
         try {
-            fm = parseFrontmatter(proposal.payload.content).data;
+            fm = parseFrontmatter(proposalContent(proposal)).data;
         }
         catch {
             return [];
@@ -322,7 +332,7 @@ const lessonContentQualityValidator = {
                 message: `Lesson proposal ${proposal.id} (${proposal.ref}) has identical description and when_to_use.`,
             });
         }
-        const dfm = detectDoubleFrontmatter(proposal.payload.content);
+        const dfm = detectDoubleFrontmatter(proposalContent(proposal));
         if (dfm)
             findings.push({ kind: dfm.kind, message: `Lesson proposal ${proposal.id} (${proposal.ref}): ${dfm.message}` });
         return findings;
@@ -356,7 +366,7 @@ const reflectSizeGuardValidator = {
     },
     validate(proposal, ctx) {
         const sourceBody = stripFrontmatterBody(ctx.source?.content ?? "");
-        const proposedBody = typeof proposal.payload?.content === "string" ? stripFrontmatterBody(proposal.payload.content) : "";
+        const proposedBody = typeof proposal.payload?.content === "string" ? stripFrontmatterBody(proposalContent(proposal)) : "";
         const outcome = checkReflectSize(sourceBody, proposedBody);
         if (outcome.ok)
             return [];

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

@@ -1,9 +1,12 @@
 // 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 { parseAssetRef } from "../../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../../core/asset/resolve-ref.js";
+import { proposalContent } from "../../../core/file-change.js";
 import { lintLessonContent } from "../../../core/lesson-lint.js";
+import { parseTaskDocument } from "../../../tasks/parser.js";
+import { parseWorkflow } from "../../../workflows/parser.js";
 import { defaultProposalQualityValidators } from "./proposal-quality-validators.js";
 const genericProposalValidator = {
     name: "generic-proposal-validator",
@@ -14,7 +17,7 @@ const genericProposalValidator = {
             findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
         }
         try {
-            ctx.parsedRef = parseAssetRef(proposal.ref);
+            ctx.parsedRef = parseRefInput(proposal.ref);
         }
         catch (err) {
             findings.push({
@@ -24,9 +27,9 @@ const genericProposalValidator = {
             ctx.stop = true;
             return findings;
         }
-        if (proposal.payload.content.startsWith("---")) {
+        if (proposalContent(proposal).startsWith("---")) {
             try {
-                parseFrontmatter(proposal.payload.content);
+                parseFrontmatter(proposalContent(proposal));
             }
             catch (err) {
                 findings.push({
@@ -38,21 +41,67 @@ const genericProposalValidator = {
         return findings;
     },
 };
-const lessonProposalValidator = {
-    name: "lesson-proposal-validator",
-    appliesTo(_proposal, ctx) {
-        return ctx.parsedRef?.type === "lesson";
-    },
-    validate(proposal) {
-        return lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`).findings.map((finding) => ({
+const canonicalProposalValidators = {
+    lesson(proposal) {
+        return lintLessonContent(proposalContent(proposal), `proposal:${proposal.id}`).findings.map((finding) => ({
             kind: finding.kind,
             message: finding.message,
         }));
     },
+    task(proposal, ctx) {
+        const name = ctx.parsedRef?.name;
+        if (!name)
+            return [];
+        parseTaskDocument({
+            yaml: proposalContent(proposal),
+            filePath: proposal.changes[0]?.path || proposal.ref,
+            id: name,
+        });
+        return [];
+    },
+    workflow(proposal) {
+        const content = proposalContent(proposal);
+        if (!content.trim())
+            return [];
+        const changePath = proposal.changes[0]?.path ?? "";
+        const result = parseWorkflow(content, { path: changePath || proposal.ref });
+        if (result.ok)
+            return [];
+        return result.errors.map((error) => ({
+            kind: "invalid-workflow-structure",
+            message: `Workflow proposal ${proposal.id} (${proposal.ref}) is invalid at line ${error.line}: ${error.message}`,
+        }));
+    },
+};
+export function hasCanonicalProposalValidator(type) {
+    return Object.hasOwn(canonicalProposalValidators, type);
+}
+const canonicalProposalValidator = {
+    name: "canonical-asset-proposal-validator",
+    appliesTo(_proposal, ctx) {
+        return ctx.parsedRef !== undefined && hasCanonicalProposalValidator(ctx.parsedRef.type);
+    },
+    validate(proposal, ctx) {
+        const type = ctx.parsedRef?.type;
+        const validator = type ? canonicalProposalValidators[type] : undefined;
+        if (!validator)
+            return [];
+        try {
+            return validator(proposal, ctx);
+        }
+        catch (error) {
+            return [
+                {
+                    kind: `invalid-${type}-structure`,
+                    message: `${type} proposal ${proposal.id} (${proposal.ref}) is invalid: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ];
+        }
+    },
 };
 export const defaultProposalValidators = [
     genericProposalValidator,
-    lessonProposalValidator,
+    canonicalProposalValidator,
     ...defaultProposalQualityValidators,
 ];
 export function runProposalValidators(proposal, validators = defaultProposalValidators, initialContext = {}) {

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

@@ -4,19 +4,17 @@
 /**
  * Proposal validation and content repair.
  *
- * The proposal repository, domain service, and legacy filesystem import moved
- * to `../repository.ts` and `../legacy-import.ts` (#578 storage consolidation).
- * This module keeps only the two proposal *validators* — {@link validateProposal}
- * and {@link repairProposalContent}.
+ * The proposal repository and domain service moved to `../repository.ts` (#578
+ * storage consolidation). This module keeps only the two proposal *validators* — {@link validateProposal} and
+ * {@link repairProposalContent}.
  */
 import { repairTruncatedDescription } from "../../../core/text-truncation.js";
 import { runProposalValidators } from "./proposal-validators.js";
 /**
  * Validate a proposal payload before promotion. Generic by default — any
- * proposal must parse cleanly and carry a non-empty body. Lessons get the
- * extra per-type lint from {@link lintLessonContent} so the contract documented
- * in v1 spec §13 is enforced at promotion time. Other asset types can hook
- * here in the future without changing call sites.
+ * proposal must parse cleanly and carry a non-empty body. Asset types in the
+ * fail-closed canonical registry run their existing parser or validator; types
+ * without one remain on generic validation.
  */
 export function validateProposal(proposal) {
     return runProposalValidators(proposal);

package/dist/commands/read/curate.js

@@ -14,17 +14,20 @@
  * `mergeCurateSearchResponses`) by importing them directly.
  */
 import fs from "node:fs";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { computeBodyHash } from "../../indexer/db/db.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
 import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
+import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
-import { truncateDescription } from "../../output/shapes.js";
+import { truncateDescription } from "../../output/shapes/helpers.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { computeBodyHash } from "../../storage/repositories/index-llm-cache-repository.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
@@ -58,7 +61,7 @@ const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
  */
-function logCurateEvent(query, result, eventSource = "user") {
+function logCurateEvent(query, result, eventSource = "user", attributionProjection = "full") {
     const itemRefs = result.items.map((item) => ("ref" in item ? item.ref : `registry:${item.id}`));
     appendEvent({
         eventType: "curate",
@@ -66,25 +69,39 @@ function logCurateEvent(query, result, eventSource = "user") {
     });
     try {
         withIndexDb((db) => {
-            insertUsageEvent(db, {
-                event_type: "curate",
-                query,
-                metadata: JSON.stringify({
-                    itemCount: result.items.length,
-                    itemRefs,
-                }),
-                source: eventSource,
+            // Resolve each curated item's DURABLE fully-qualified `item_ref` (D-R3)
+            // + entry_id from index.db (`db`); the usage_events writes land in
+            // state.db (Chunk-8 WI-8.3).
+            const perItem = result.items
+                .filter((item) => "ref" in item && typeof item.ref === "string")
+                .flatMap((item) => {
+                const entryId = findEntryIdByRef(db, item.ref);
+                if (entryId === undefined)
+                    return [];
+                const itemRef = getItemRefById(db, entryId);
+                return itemRef ? [{ entryRef: itemRef, entryId, item }] : [];
             });
-            for (const item of result.items) {
-                if (!("ref" in item) || typeof item.ref !== "string")
-                    continue;
-                insertUsageEvent(db, {
+            withStateDbTelemetry((stateDb) => {
+                insertUsageEvent(stateDb, {
                     event_type: "curate",
                     query,
-                    entry_ref: item.ref,
+                    metadata: JSON.stringify({
+                        itemCount: result.items.length,
+                        itemRefs,
+                    }),
                     source: eventSource,
                 });
-            }
+                for (const { entryRef, entryId, item } of perItem) {
+                    insertUsageEvent(stateDb, {
+                        event_type: "curate",
+                        query,
+                        entry_ref: entryRef,
+                        entry_id: entryId,
+                        metadata: usageEventAttributionMetadata(getSearchHitAttribution(item), entryRef, attributionProjection),
+                        source: eventSource,
+                    });
+                }
+            }, TELEMETRY_BUSY_TIMEOUT_MS);
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
@@ -97,7 +114,7 @@ export async function akmCurate(options) {
         throw new UsageError('A curation query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT");
     }
     const limit = options.limit && options.limit > 0 ? options.limit : DEFAULT_CURATE_LIMIT;
-    const source = options.source ?? parseSearchSource("stash");
+    const source = options.source ?? parseSearchSource("local");
     const searchResponse = options.searchResponse ??
         (await searchForCuration({
             query: options.query,
@@ -105,30 +122,36 @@ export async function akmCurate(options) {
             limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
             source,
         }));
-    const result = await curateSearchResults(options.query, searchResponse, limit, options.type);
-    logCurateEvent(options.query, result, options.eventSource);
+    const result = await curateSearchResults(options.query, searchResponse, limit, options.type, options.eventSource);
+    if (!options.skipLogging) {
+        logCurateEvent(options.query, result, options.eventSource, options.attributionProjection);
+    }
     return result;
 }
-export async function curateSearchResults(query, result, limit, selectedType) {
-    const stashHits = result.hits.filter((hit) => hit.type !== "registry");
+export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
+    const allStashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
-    let selectedStashHits;
-    let supportRefsByRef = new Map();
-    if (selectedType && selectedType !== "any") {
-        selectedStashHits = stashHits.slice(0, limit);
-    }
-    else {
-        const selected = selectCuratedStashHits(query, stashHits, limit);
-        const preferred = preferBroadRootRepresentative(query, selected.selected, stashHits, selected.supportRefsByRef);
-        selectedStashHits = preferred.selected;
-        supportRefsByRef = preferred.supportRefsByRef;
-    }
-    const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, Math.min(2, limit - selectedStashHits.length));
+    // F3/R-018: `--type` must NARROW the candidate pool, not bypass curation.
+    // Previously a set `selectedType` skipped `selectCuratedStashHits` (ranking,
+    // intent nudges, score floor) entirely, taking the raw top-N of whatever
+    // order the hits arrived in. Filtering the pool down to the requested type up front and
+    // then running the SAME pipeline over it gives `--type` its intended
+    // "narrow, don't disable" semantics — and matters even when the caller's
+    // search already applied a type filter at the DB layer, because
+    // `curateSearchResults` is also driven directly (tests, `searchResponse`
+    // fixtures) with a `SearchResponse` that was never type-filtered.
+    const stashHits = selectedType && selectedType !== "any" ? allStashHits.filter((hit) => hit.type === selectedType) : allStashHits;
+    const selected = selectCuratedStashHits(query, stashHits, limit);
+    const selectedStashHits = selected.selected;
+    const supportRefsByRef = selected.supportRefsByRef;
+    // F4/R-019: respect `--limit` for registry fill instead of hard-capping it
+    // at a bare literal 2 — the remaining slots after stash hits ARE the cap.
+    const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, limit - selectedStashHits.length);
     const selectedRefs = new Set(selectedStashHits.map((hit) => hit.ref));
     const items = [
         ...(await Promise.all(selectedStashHits
             .slice(0, limit)
-            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs)))),
+            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs, eventSource)))),
         ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
     ].slice(0, limit);
     return {
@@ -139,10 +162,10 @@ export async function curateSearchResults(query, result, limit, selectedType) {
         ...(result.tip ? { tip: result.tip } : {}),
     };
 }
-async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
+async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs, eventSource) {
     let shown;
     try {
-        shown = await akmShowUnified({ ref: hit.ref });
+        shown = await akmShowUnified({ ref: hit.ref, eventSource, skipLogging: true });
     }
     catch {
         shown = undefined;
@@ -155,11 +178,16 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
     const mergedSupportRefs = mergeCurateSupportRefs(supportRefs, shown?.related?.hits, selectedRefs, hit.ref);
-    return {
-        source: "stash",
+    const item = {
+        source: "local",
         type: shown?.type ?? hit.type,
         name: shown?.name ?? hit.name,
         ref: hit.ref,
+        path: shown?.path ?? hit.path,
+        editable: shown?.editable ?? hit.editable ?? false,
+        ...((shown?.editable ?? hit.editable ?? false) === false
+            ? { editHint: shown?.editHint ?? hit.editHint ?? `This asset is read-only. Inspect it with: akm show ${hit.ref}` }
+            : {}),
         ...(description ? { description } : {}),
         ...(preview ? { preview } : {}),
         ...(shown?.keys?.length ? { keys: shown.keys } : {}),
@@ -170,6 +198,8 @@ async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
         reason: buildCuratedReason(query, shown?.type ?? hit.type),
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
+    copySearchHitAttribution(hit, item, item.description);
+    return item;
 }
 /**
  * #624-P3 — enqueue an ungraphed asset for lazy graph extraction when the
@@ -216,7 +246,7 @@ function buildCuratedRegistryItem(query, hit) {
         name: hit.name,
         id: hit.id,
         ...(hit.description ? { description: hit.description } : {}),
-        followUp: hit.action ?? `akm add ${hit.id}`,
+        followUp: hit.action ?? `akm bundle add ${hit.id}`,
         reason: `Useful external source to explore for ${query}.`,
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
@@ -254,7 +284,9 @@ function buildCurateSummary(query, items) {
     if (items.length === 0) {
         return `No curated assets were selected for "${query}".`;
     }
-    const labels = items.map((item) => `${item.type}:${item.name}`);
+    // F4b: emit the flipped conceptId ref for stash items (registry items have no
+    // ref — keep their `registry:<name>` label).
+    const labels = items.map((item) => ("ref" in item ? item.ref : `${item.type}:${item.name}`));
     return `Selected ${items.length} curated result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
 }
 export function deriveCurateFallbackQueries(query) {
@@ -423,7 +455,10 @@ function computeCurateTypeNudge(type, intent) {
 }
 function getCurateFamily(ref) {
     try {
-        const parsed = parseAssetRef(ref);
+        // F4b: `ref` is a search-hit ref in the 0.9.0 conceptId grammar — parse via
+        // the new-grammar `parseRefInput` so skill/reference family grouping still
+        // recognizes it.
+        const parsed = parseRefInput(ref);
         if (parsed.type === "skill") {
             return { key: parsed.name, role: "root" };
         }
@@ -556,36 +591,6 @@ function collapseCurateFamilies(query, hits) {
         supportRefsByRef,
     };
 }
-function preferBroadRootRepresentative(query, selected, allHits, supportRefsByRef) {
-    const first = selected[0];
-    if (!first)
-        return { selected, supportRefsByRef };
-    const match = /^knowledge:skills\/(.+?)\/references\/(.+)$/.exec(first.ref);
-    if (!match)
-        return { selected, supportRefsByRef };
-    const lower = query.toLowerCase();
-    const topicTokens = match[2].split(/[^a-z0-9]+/i).filter(Boolean);
-    const wantsReference = CURATE_REFERENCE_QUERY_RE.test(lower) ||
-        topicTokens.some((token) => token.length >= 3 && lower.includes(token.toLowerCase()));
-    if (wantsReference)
-        return { selected, supportRefsByRef };
-    const rootRef = `skill:${match[1]}`;
-    const rootHit = allHits.find((hit) => hit.ref === rootRef);
-    if (!rootHit)
-        return { selected, supportRefsByRef };
-    const next = [rootHit, ...selected.filter((hit) => hit.ref !== first.ref && hit.ref !== rootRef)];
-    const merged = new Map(supportRefsByRef);
-    const priorSupport = merged.get(first.ref) ?? [];
-    for (const entry of priorSupport)
-        appendCurateSupportRef(merged, rootRef, entry);
-    appendCurateSupportRef(merged, rootRef, {
-        ref: first.ref,
-        type: first.type,
-        reason: "Related family asset to inspect next.",
-    });
-    merged.delete(first.ref);
-    return { selected: next, supportRefsByRef: merged };
-}
 function mergeCurateSupportRefs(seeded, relatedHits, selectedRefs, ownerRef) {
     const merged = [];
     for (const entry of seeded) {