akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -10,13 +10,19 @@
  * invalid task (e.g. two targets) is still RECOGNIZED; the `invalid-task-yaml`
  * violation surfaces only in `validate`.
  *
+ * `.yaml` is the one extension `validate` inspects but `recognize` refuses: it
+ * is not a task spelling (nothing indexes or schedules it), so it is reported
+ * as `invalid-task-yaml` rather than silently skipped (issue #760).
+ *
  * ── validate (spec §6 task validation column) ──
  *
- * A task must declare a `schedule`, an `enabled` boolean, and EXACTLY ONE
- * target (`prompt` XOR `workflow` XOR `command`). The akm adapter's
- * `TaskLinter` port checks "at least one" target; the native task family here is
- * STRICTER — declaring two targets is `invalid-task-yaml`. So this adapter owns
- * a purpose-built one-target check rather than reusing that port.
+ * A task must declare `version: 2`, a `schedule`, and EXACTLY ONE target
+ * (`prompt` XOR `workflow` XOR `command`). `enabled` is OPTIONAL — the parser
+ * defaults it to `true`, so an omitted field means an ACTIVE task — but must
+ * be a boolean when present. The akm adapter's `TaskLinter` port checks
+ * "at least one" target; the native task family here is STRICTER — declaring
+ * two targets is `invalid-task-yaml`. So this adapter owns a purpose-built
+ * one-target check rather than reusing that port.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -24,12 +30,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
+import { parseTaskYaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskFieldProblems, taskYamlParseDetail, } from "../../../tasks/schema.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
 /** The task YAML extension (spec §6 task row). */
-const TASK_EXT = ".yml";
+const TASK_EXT = TASK_EXTENSION;
 /** The mutually-exclusive task target keys (exactly one required). */
 const TARGET_KEYS = ["prompt", "workflow", "command"];
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
@@ -56,27 +62,15 @@ function recognize(c, file) {
         content: raw.length > MAX_CONTENT_CHARS ? raw.slice(0, MAX_CONTENT_CHARS) : raw,
     };
 }
-/** Parse a task YAML into a plain record (tolerant: malformed / non-mapping → {}). */
-function parseTaskYaml(raw) {
-    try {
-        const doc = parseYaml(raw);
-        if (doc && typeof doc === "object" && !Array.isArray(doc))
-            return doc;
-    }
-    catch {
-        // malformed YAML
-    }
-    return {};
-}
-/** The native `invalid-task-yaml` check: schedule + enabled(boolean) + EXACTLY ONE target. */
+/**
+ * The native `invalid-task-yaml` check: the shared field rules
+ * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
+ * reconciliation story) plus this adapter's stricter EXACTLY-ONE-target rule.
+ */
 function taskDiagnostics(relPath, data) {
     if (Object.keys(data).length === 0)
         return [];
-    const problems = [];
-    if (typeof data.schedule !== "string" || data.schedule.trim() === "")
-        problems.push("schedule");
-    if (typeof data.enabled !== "boolean")
-        problems.push("enabled (must be a boolean)");
+    const problems = taskFieldProblems(data);
     const targets = TARGET_KEYS.filter((k) => k in data && data[k] !== undefined && data[k] !== null);
     if (targets.length === 0)
         problems.push("exactly one target (prompt, workflow, or command)");
@@ -96,16 +90,46 @@ async function validate(_c, changes, ctx) {
         const raw = change.after ?? (await ctx.readFile(change.path));
         if (typeof raw !== "string")
             continue;
-        if (path.extname(change.path).toLowerCase() !== TASK_EXT)
+        const ext = path.extname(change.path).toLowerCase();
+        // `.yaml` is NOT a task extension — the file never indexes and never runs.
+        // It is validated here purely so the near miss is REPORTED rather than
+        // skipped the way every other extension is (issue #760).
+        if (ext !== TASK_EXT && ext !== TASK_NEAR_MISS_EXTENSION)
+            continue;
+        const relPath = toPosix(change.path);
+        if (ext === TASK_NEAR_MISS_EXTENSION) {
+            diagnostics.push({
+                file: relPath,
+                issue: "invalid-task-yaml",
+                detail: taskExtensionDetail(relPath),
+                fixed: false,
+            });
+        }
+        const parsed = parseTaskYaml(raw);
+        if (!parsed.ok) {
+            // Distinguish "unparseable" from "empty": `taskDiagnostics` returns []
+            // for an empty mapping, so collapsing a parse failure onto `{}` made a
+            // broken task file lint clean.
+            diagnostics.push({
+                file: relPath,
+                issue: "invalid-task-yaml",
+                detail: taskYamlParseDetail(parsed.error),
+                fixed: false,
+            });
             continue;
-        diagnostics.push(...taskDiagnostics(toPosix(change.path), parseTaskYaml(raw)));
+        }
+        diagnostics.push(...taskDiagnostics(relPath, parsed.data));
     }
     return diagnostics;
 }
 export const akmTaskAdapter = {
     id: "akm-task",
     version: "0.9.0",
-    extensions: [TASK_EXT],
+    // `.yaml` is listed as a COLLECTION hint only — `recognize` still gates on
+    // `.yml`, so a `.yaml` file is never indexed as a task. Listing it is what
+    // routes the near-miss file into `validate`, where it is reported instead of
+    // silently skipped (issue #760).
+    extensions: [TASK_EXT, TASK_NEAR_MISS_EXTENSION],
     recognize,
     validate,
     /** A task places to `<conceptId>.yml`; an already-suffixed conceptId is idempotent. */
@@ -120,8 +144,7 @@ export const akmTaskAdapter = {
     /**
      * Install-time probe (§1.2): a root holding a top-level `.yml` file that
      * parses as a task (a `schedule` key). The task-shape probe keeps it disjoint
-     * from the `akm-workflow` YAML program (`version` + `steps`, no `schedule`)
-     * and from any non-task YAML.
+     * from non-task YAML.
      */
     looksLikeRoot(root) {
         let entries;
@@ -141,7 +164,7 @@ export const akmTaskAdapter = {
             catch {
                 continue;
             }
-            const data = parseTaskYaml(raw);
+            const { data } = parseTaskYaml(raw);
             if (typeof data.schedule === "string" && data.schedule.trim() !== "")
                 return true;
         }

package/dist/core/adapter/adapters/akm-workflow-adapter.js

@@ -4,27 +4,20 @@
 /**
  * The `akm-workflow` adapter — akm 0.9.0 format-family work item (#46).
  *
- * A native akm workflow bundle (spec §6/§7). Both workflow forms derive
- * `type: workflow`:
- *   - MARKDOWN (`.md`, ≈ an OKF concept) — the classic linear workflow
- *     (`# Workflow:` / `## Step:` / `Step ID:` / `### Instructions`), detected
- *     by the shared `looksLikeWorkflow` probe so the matcher and parser cannot
- *     drift;
- *   - YAML PROGRAM (`.yaml`/`.yml`, an AKM extension) — `version` + `steps`,
- *     detected by `looksLikeWorkflowProgram`.
- * conceptId strips the recognized workflow extension (`.md`/`.yaml`/`.yml`). A
- * plain `.md` that is NOT workflow-shaped (a README, an OKF reserved listing/log
- * file) is abstained on — the content probe subsumes the D-R6 reserved-file
- * exclusion, so no reserved-basename literal is needed here.
+ * A native akm workflow bundle (spec §6/§7). One format now (workflow-format-
+ * unification): `.md` files, orchestration graph in frontmatter, per-step
+ * prose in the body. Recognition is frontmatter `type: workflow`, or — since
+ * this adapter's whole domain IS workflows — simply residing under this
+ * bundle's root; no content sniffing. conceptId strips the `.md` extension. A
+ * plain `.md` that opts out via an explicit non-workflow `type:` frontmatter
+ * key is abstained on.
  *
  * ── validate (spec §6 workflow row) ──
  *
  * Reuses the akm adapter's per-type workflow checks (shared base checks +
- * `placeholder-stub` + `invalid-workflow-structure`, markdown only — the YAML
- * program's correctness is `parseWorkflowProgram`'s own result, not a
- * markdown-lint path). Delegates to the SAME `perTypeValidateChecks` /
- * `runBaseValidateChecks` the `akm` adapter uses, so workflow validation has
- * one home.
+ * `placeholder-stub` + `invalid-workflow-structure`). Delegates to the SAME
+ * `perTypeValidateChecks` / `runBaseValidateChecks` the `akm` adapter uses, so
+ * workflow validation has one home.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-workflow/` + goldens
@@ -32,60 +25,52 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { looksLikeWorkflow } from "../../../workflows/parser.js";
-import { looksLikeWorkflowProgram } from "../../../workflows/program/parser.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { perTypeValidateChecks } from "./akm-lint.js";
 import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
 /** A native workflow bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
-/** Recognized workflow extensions (matcher parity with recognition-util WORKFLOW_EXTENSIONS). */
-const WORKFLOW_EXTS = new Set([".md", ".yaml", ".yml"]);
+/** One recognized workflow extension now (workflow-format-unification): `.md`. */
+const WORKFLOW_EXTS = new Set([".md"]);
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
 const MAX_CONTENT_CHARS = 100_000;
 function toPosix(p) {
     return p.replace(/\\/g, "/");
 }
-/** Strip a recognized workflow extension from a component-root-relative path → conceptId. */
+/** Strip the recognized workflow extension from a component-root-relative path → conceptId. */
 function conceptIdOf(relPath) {
-    return toPosix(relPath).replace(/\.(md|ya?ml)$/i, "");
+    return toPosix(relPath).replace(/\.md$/i, "");
 }
-/** Which workflow form (if any) `file` is — the recognition gate. */
-function workflowForm(ext, raw) {
-    if (ext === ".md")
-        return looksLikeWorkflow(parseFrontmatter(raw).content) ? "markdown" : null;
-    if (ext === ".yaml" || ext === ".yml")
-        return looksLikeWorkflowProgram(raw) ? "yaml-program" : null;
-    return null;
+/** `README.md` (case-insensitive) is documentation, never the typed asset — mirrors the akm matcher stack's D-R6 reserved-file exclusion (`TYPED_DIR_DOC_FILES`). */
+function isReservedDocFile(fileName) {
+    return fileName.toLowerCase() === "readme.md";
 }
-/** The workflow's projected `description` — frontmatter for markdown, the program `description:` for YAML. */
-function workflowDescription(form, raw) {
-    if (form === "markdown")
-        return nonEmptyString(parseFrontmatter(raw).data.description);
-    try {
-        const doc = parseYaml(raw);
-        if (doc && typeof doc === "object" && !Array.isArray(doc)) {
-            return nonEmptyString(doc.description);
-        }
-    }
-    catch {
-        // malformed YAML — no description
-    }
-    return undefined;
+/**
+ * Recognition gate: any `.md` file in this bundle IS a workflow (this
+ * adapter's entire domain is workflows — spec §2.5, "residence under
+ * workflows/"), UNLESS its frontmatter declares a DIFFERENT non-empty
+ * `type:` (an explicit opt-out, e.g. a README-shaped doc that wants to be
+ * something else). No content sniffing.
+ */
+function isWorkflowFile(raw) {
+    const data = parseFrontmatter(raw).data;
+    const type = data.type;
+    return type === undefined || type === "workflow";
 }
 function recognize(c, file) {
     if (!WORKFLOW_EXTS.has(file.ext))
         return null;
+    if (isReservedDocFile(file.fileName))
+        return null;
     const raw = file.content();
-    const form = workflowForm(file.ext, raw);
-    if (form === null)
+    if (!isWorkflowFile(raw))
         return null;
     const conceptId = conceptIdOf(file.relPath);
     const name = conceptId.split("/").pop() ?? conceptId;
-    const description = workflowDescription(form, raw);
-    const body = form === "markdown" ? parseFrontmatter(raw).content : raw;
-    const tags = readTags(parseFrontmatter(raw).data.tags);
+    const parsed = parseFrontmatter(raw);
+    const description = nonEmptyString(parsed.data.description);
+    const body = parsed.content;
+    const tags = readTags(parsed.data.tags);
     const doc = {
         ref: `${c.id}//${conceptId}`,
         bundle: c.id,
@@ -113,18 +98,11 @@ async function validate(c, changes, ctx) {
         if (typeof raw !== "string")
             continue;
         const ext = path.extname(change.path).toLowerCase();
-        if (!WORKFLOW_EXTS.has(ext) || workflowForm(ext, raw) === null)
+        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(path.basename(change.path)) || !isWorkflowFile(raw))
             continue;
         const relPath = toPosix(change.path);
-        // Markdown workflows parse via frontmatter; YAML programs are pure YAML (no frontmatter).
-        let parsed;
-        if (ext === ".md") {
-            const p = parseFrontmatter(raw);
-            parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
-        }
-        else {
-            parsed = { data: {}, content: raw, frontmatter: null };
-        }
+        const p = parseFrontmatter(raw);
+        const parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
         diagnostics.push(...(await runBaseValidateChecks(relPath, parsed, c.root, ctx)));
         diagnostics.push(...(await perTypeValidateChecks({
             type: "workflow",
@@ -139,13 +117,22 @@ async function validate(c, changes, ctx) {
     }
     return diagnostics;
 }
-/** True when a top-level file in `root` is workflow-shaped (used by looksLikeRoot). */
+/**
+ * True when a top-level file in `root` is workflow-shaped (used by
+ * looksLikeRoot). Unlike `isWorkflowFile` (which admits an absent `type:` —
+ * the lenient default ONCE a source is already known to be this bundle),
+ * this requires an EXPLICIT `type: workflow` — the install-time probe is
+ * choosing WHICH adapter owns an unconfigured root among several candidates
+ * (spec §1.2), and an incidental `.md` with no frontmatter type at all
+ * (common in an OKF or llm-wiki bundle) must not misclassify that root as
+ * akm-workflow's.
+ */
 function hasTopLevelWorkflowFile(root, entries) {
     for (const entry of entries) {
         if (!entry.isFile())
             continue;
         const ext = path.extname(entry.name).toLowerCase();
-        if (!WORKFLOW_EXTS.has(ext))
+        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(entry.name))
             continue;
         let raw;
         try {
@@ -154,7 +141,7 @@ function hasTopLevelWorkflowFile(root, entries) {
         catch {
             continue;
         }
-        if (workflowForm(ext, raw) !== null)
+        if (parseFrontmatter(raw).data.type === "workflow")
             return true;
     }
     return false;
@@ -162,13 +149,13 @@ function hasTopLevelWorkflowFile(root, entries) {
 export const akmWorkflowAdapter = {
     id: "akm-workflow",
     version: "0.9.0",
-    extensions: [".md", ".yaml", ".yml"],
+    extensions: [".md"],
     recognize,
     validate,
-    /** Default markdown placement; an explicit `.yaml`/`.yml`/`.md` conceptId short-circuits to that extension. */
+    /** Markdown placement; an explicit `.md` conceptId short-circuits to that extension. */
     placeNew(c, conceptId) {
         const posix = toPosix(conceptId);
-        if (/\.(md|ya?ml)$/i.test(posix))
+        if (/\.md$/i.test(posix))
             return path.join(c.root, posix);
         return path.join(c.root, `${posix}.md`);
     },
@@ -177,11 +164,8 @@ export const akmWorkflowAdapter = {
         return ["."];
     },
     /**
-     * Install-time probe (§1.2): a root holding a workflow file at top level — a
-     * `.yaml`/`.yml` program (`version` + `steps`) or a workflow-shaped `.md`. The
-     * content probe means an okf reserved listing, a wiki `schema.md`, or a README
-     * never trips it, so the probe stays disjoint from the other adapters' roots
-     * without any structural exclusion.
+     * Install-time probe (§1.2): a root holding a workflow-shaped `.md` file at
+     * top level (frontmatter `type: workflow` or no `type:` at all).
      */
     looksLikeRoot(root) {
         let entries;

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -18,7 +18,7 @@
  *
  * ── validate (spec §6 env/secret validation column) ──
  *
- * The dangerous-key scan (`dangerous-vault-key`), reusing the akm adapter's
+ * The dangerous-key scan (`dangerous-env-key`), reusing the akm adapter's
  * `dangerousEnvKeyDiagnostics` — which preserves the code-grounded narrowness:
  * it runs ONLY on `*.env`-suffixed files, so `secrets/<bare-name>` is never
  * scanned (its whole content is an opaque secret value). Reads KEY NAMES only.

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -71,6 +71,8 @@ function recognize(c, file) {
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
     };
+    if (type !== "script")
+        doc.ownsPresentation = true;
     const description = nonEmptyString(parsed.data.description);
     if (description !== undefined)
         doc.description = description;

package/dist/core/adapter/adapters/index.js

@@ -33,10 +33,10 @@ export { websiteSnapshotAdapter } from "./website-snapshot-adapter.js";
  *
  * Probe-precedence rationale (grounds "cannot shadow the existing three"):
  *
- *  - The three loosest probes — `llm-wiki` (schema.md + pages/), `okf` (root
- *    index doc), `akm` (a placement stash subdir / `.stash`) — stay LAST and in
- *    their established order (`llm-wiki` BEFORE `okf`: a wiki root also carries a
- *    root index doc, so the more-specific wiki probe must win the overlap).
+ *  - The three loosest probes — `llm-wiki`, `akm`, and `okf` — stay LAST.
+ *    Native AKM evidence wins before OKF because AKM Markdown is an OKF
+ *    superset; the AKM probe is correspondingly strict enough not to claim an
+ *    OKF bundle merely because it contains one familiar directory name.
  *  - `akm.looksLikeRoot` fires on ANY root carrying a stash-subdir-named
  *    directory — which includes a `.claude`/`.opencode` tool dir (`commands/`,
  *    `agents/`, `skills/`) and a dotenv bundle (`env/`, `secrets/`). So
@@ -62,10 +62,10 @@ export const BUILTIN_ADAPTERS = Object.freeze([
     // Native akm sub-formats (disjoint content-shape probes).
     akmWorkflowAdapter,
     akmTaskAdapter,
-    // The three established loose probes, in their established order.
+    // Loose probes: specific native layouts before the portable OKF baseline.
     llmWikiAdapter,
-    okfAdapter,
     akmAdapter,
+    okfAdapter,
     // Explicit-config fallback (never auto-selected) — last.
     genericFilesAdapter,
 ]);

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -5,8 +5,8 @@
  * The first-class `llm-wiki` adapter — akm 0.9.0 chunk-4 (DEV-7 restore).
  *
  * The `wiki` ASSET-TYPE dies in chunk 4 (plan §11 Chunk 4 / §7.4), but the LLM
- * Wiki structure stays first-class as its OWN adapter. This relocates the native
- * wiki semantics from `src/wiki/wiki.ts` + `src/wiki/wiki-templates.ts` into a
+ * Wiki structure stays first-class as its OWN adapter. This relocates the
+ * native wiki semantics from the retired `src/wiki/` module into a
  * `BundleAdapter` implementing `docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §7
  * (llm-wiki row), §6 (wiki-page row), §0.2 (the `wiki` asset-type is retired;
  * the adapter is first-class), §1.2 (probe = schema.md + pages/), §9 (links).
@@ -42,7 +42,8 @@
  *
  * ── validate (spec §6/§7, §9) — native wiki checks ONLY ──
  *
- * The native structural checks ported from `wiki.ts#lintWiki`: `broken-xref`
+ * The native structural checks ported from the retired `src/wiki/` module's
+ * `lintWiki`: `broken-xref`
  * (an xref target that does not resolve to an existing page), `uncited-raw`
  * (a `raw/` source not cited by any page's `sources:`), `missing-description`
  * (a page with no description), and `broken-source` (a page `sources:` entry
@@ -58,11 +59,15 @@
  *
  * ── Cycle-safety ──
  *
- * Imported ONLY by the test-only `adapters/index.ts` barrel (nothing in `src/`
- * imports that), so this leaf can never gain an inbound edge from a cycle
- * participant. It value-imports only pure leaves (`frontmatter`, `shared`) plus
- * Node builtins + `yaml` (already a runtime dep). Verified: `bun
- * scripts/lint-import-cycles.ts` stays within baseline (13) with this file present.
+ * Imported by the `adapters/index.ts` barrel, which is NOT test-only: `core/
+ * adapter/registry.ts:33` imports it in production for the frozen
+ * `BUILTIN_ADAPTERS` list (`installations.ts#detectAdapterId`,
+ * `provider-utils.ts#detectStashRoot`). This still can never gain an inbound
+ * edge from a cycle participant, since neither the barrel nor the registry
+ * import anything that imports back into this file. It value-imports only
+ * pure leaves (`frontmatter`, `shared`) plus Node builtins + `yaml` (already a
+ * runtime dep). Verified: `bun scripts/lint-import-cycles.ts` reports 0 cycle
+ * participants with this file present.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -272,6 +277,7 @@ function recognize(c, file) {
         path: file.absPath,
         hash: hashContent(raw),
         adapterId: "llm-wiki",
+        ownsPresentation: true,
         type: isRaw ? WIKI_SOURCE_TYPE : (fm.pageKind ?? DEFAULT_PAGE_KIND),
         name: lastSegment,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,