akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -16,9 +16,9 @@
  *
  * `file-context.ts#runMatchers` (`:242-265`) is async ONLY because of its lazy
  * `ensureBuiltinsRegistered()` dynamic import; its ARBITRATION is pure and
- * synchronous. We reproduce it here by importing the SAME five builtin matcher
+ * synchronous. We reproduce it here by importing the SAME four builtin matcher
  * functions (`matchers.ts` `extensionMatcher` / `directoryMatcher` /
- * `parentDirHintMatcher` / `smartMdMatcher` / `workflowProgramMatcher`) in the
+ * `parentDirHintMatcher` / `smartMdMatcher`) in the
  * SAME order they are registered, collecting every non-null
  * `MatchResult` and picking the winner by **specificity descending, ties broken
  * by later-registered (higher index) winning** — byte-identical to
@@ -69,10 +69,14 @@
  * logic, not re-implementing it. Neither is a taxonomy import-cycle (SCC)
  * participant: `matchers.ts` resolves renderers via `type-presentation.ts`, and
  * `asset-placement.ts` is a pure leaf (only Node builtins + `recognition-util`).
- * Nothing in `src/` imports this adapter back (only the test-only
- * `adapters/index.ts` barrel does, and nothing in `src/` imports THAT), so the
- * adapter is itself a leaf — verified: `bun scripts/lint-import-cycles.ts` stays
- * within baseline and this module is NOT a participant.
+ * Nothing in `src/` imports this adapter back except 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`).
+ * The adapter is still itself a leaf, since neither the barrel nor the
+ * registry import anything that imports back into this file — verified: `bun
+ * scripts/lint-import-cycles.ts` reports 0 cycle participants and this module
+ * is NOT one.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -115,7 +119,6 @@ const WIKI_INFRA_FILES = new Set(["schema.md", "index.md", "log.md"]);
  * invariant for sensitive env/secret files holds by construction. Returns `true`
  * when the `akm` adapter must ABSTAIN (recognize → null):
  *   - an `env/…` `.env` file with a sibling `.sensitive` marker;
- *   - anything under the frozen legacy `vaults/` dir (the `vault` type is gone);
  *   - a `secrets/` `.sensitive`/`.lock` marker, or a secret with a sibling
  *     `<name>.sensitive` marker;
  *   - a `wikis/<name>/` root-level infra file (schema.md/index.md/log.md).
@@ -132,10 +135,6 @@ function akmStashAbstains(root, absPath) {
         if (fs.existsSync(absPath.replace(/\.env$/, ".sensitive")))
             return true;
     }
-    // The legacy `vaults/` directory (frozen copy left by the 0.8 migration) is
-    // never indexed — the `vault` asset type was removed in 0.9.0.
-    if (segments[0] === "vaults")
-        return true;
     // Skip secret files that are themselves a `.sensitive` marker, or that have a
     // sibling `<name>.sensitive` marker. Secrets are otherwise indexed by name
     // only (their bytes are never read for classification here).
@@ -190,8 +189,12 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "wikiRole",
     "sources",
     "generation",
-    "sourceRefs",
     "evidenceSources",
+    // D2 (#730): the OKF v0.2 provenance `promoteProposal` stamps onto AKM-native
+    // writes (generated/verified/sources, namespaced — see `types.ts`'s
+    // `OkfProvenance` doc). Carried so the akm adapter rereads what it wrote and
+    // `akm show` surfaces it, exactly like every other field in this list.
+    "provenance",
 ];
 /**
  * Map the fully-assembled `IndexDocument` (produced by the shared metadata
@@ -254,17 +257,12 @@ function recognize(c, file) {
     const match = recognizeMatch(file);
     if (match === null)
         return null;
-    // canonical name = the winning type's per-type canonical name (§5.1:
-    // reproduce AssetSpec.toCanonicalName). Fall back to the BASENAME minus its
-    // extension only if the type's toCanonicalName abstains (e.g. a `skills/x.md`
-    // flat file, or a `SKILL.md` sitting directly at the skills/ root with no name
-    // dir). The basename fallback is byte-identical to the pre-0.9.0 flat-walk's
-    // `?? baseName` fallback (metadata.ts `generateMetadata`), so `entry.name`
-    // stays the BARE canonical name — never the stash-root-relative path, which
-    // would re-embed the `<stash-subdir>/` type prefix and double-prefix every
-    // downstream legacy `type:name` ref (e.g. `skill:skills/x`).
+    // Canonical name = the winning type's per-type canonical name (§5.1).
+    // Invalid placements are not projected onto a different identity.
     const derived = deriveCanonicalAssetNameFromStashRoot(match.type, c.root, file.absPath);
-    const canonicalName = derived ?? path.basename(file.absPath).replace(/\.[^./]+$/, "");
+    if (derived === undefined)
+        return null;
+    const canonicalName = derived;
     // conceptId = the QUALIFIED `<stash-subdir>/<canonical-name>` spelling
     // (ref-grammar decision D-R2): the same form `placeNew` consumes, and for
     // markdown types the OKF concept ID (path − .md). Both branches now feed a
@@ -416,8 +414,8 @@ export const akmAdapter = {
     id: "akm",
     version: "0.9.0",
     // Recognized-extension HINT, derived from what the matchers accept (§6):
-    // `.md` (markdown types + skill), `.yaml`/`.yml` (workflow programs,
-    // task YAML), `.env` (env files), and the 16 SCRIPT_EXTENSIONS. This is a
+    // `.md` (markdown types + skill), `.yaml`/`.yml` (task YAML), `.env` (env
+    // files), and the 16 SCRIPT_EXTENSIONS. This is a
     // NON-EXHAUSTIVE hint for the akm adapter: recognition is directory-driven
     // via `recognize()` (e.g. a bare `secrets/<anything>` file with no extension
     // is a `secret`), so `recognize()` — not this list — is the source of truth.
@@ -484,9 +482,11 @@ export const akmAdapter = {
     /**
      * Install-time probe (§1.2), reproducing today's stash-root detection
      * (`provider-utils.ts#detectStashRoot`/`hasStashDirs`): a root is an AKM
-     * workspace root when it carries a `.stash` marker directory OR any immediate
-     * subdirectory named after a placement stash subdir. Pure stat/readdir; a
-     * missing/unreadable root is not a root.
+     * workspace root when it carries a `.stash` marker, multiple native placement
+     * directories, or one native directory whose Markdown is absent or
+     * declares the matching AKM type. The final check prevents an OKF bundle with
+     * an unrelated open type under (for example) `knowledge/` from being claimed
+     * by AKM merely because the directory name overlaps.
      */
     looksLikeRoot(root) {
         try {
@@ -504,6 +504,25 @@ export const akmAdapter = {
         catch {
             return false;
         }
-        return entries.some((entry) => entry.isDirectory() && ownedDirNames.has(entry.name));
+        const ownedDirs = entries.filter((entry) => entry.isDirectory() && ownedDirNames.has(entry.name));
+        if (ownedDirs.length >= 2)
+            return true;
+        const only = ownedDirs[0];
+        if (!only)
+            return false;
+        const expectedType = stashDirToType(only.name);
+        try {
+            const markdown = fs
+                .readdirSync(path.join(root, only.name), { withFileTypes: true })
+                .find((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"));
+            if (!markdown)
+                return true;
+            const data = parseFrontmatter(fs.readFileSync(path.join(root, only.name, markdown.name), "utf8")).data;
+            const declaredType = typeof data.type === "string" ? data.type.trim() : "";
+            return !declaredType || declaredType === expectedType;
+        }
+        catch {
+            return true;
+        }
     },
 };

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

@@ -41,7 +41,7 @@
  *
  * Imported ONLY by `akm-adapter.ts` (no inbound `src/` edge) → can never join a
  * cycle. It VALUE-imports `parseWorkflow` (already transitively reachable from
- * `akm-adapter` via `matchers.ts`) and the PURE predicate `isDangerousVaultKey`
+ * `akm-adapter` via `matchers.ts`) and the pure predicate `isDangerousEnvKey`
  * from `commands/lint/env-key-rules` — the predicate is imported, not copied,
  * precisely so the 40+ security-sensitive dangerous-key names cannot drift from
  * the canonical set; importing it is ratchet-neutral (verified: 18). The small
@@ -51,14 +51,17 @@
  * adapter.
  */
 import path from "node:path";
-import { isDangerousVaultKey } from "../../../commands/lint/env-key-rules.js";
+import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
+import { taskFieldProblems } from "../../../tasks/schema.js";
+import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { parseWorkflow } from "../../../workflows/parser.js";
+import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
 const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
 /** Placeholder markers a workflow stub carries — `commands/lint/workflow-linter.ts:10`. */
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /** Inline suppression token — `commands/lint/env-key-rules.ts:138` (not exported there; reproduced verbatim). */
-const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-vault-key";
+const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-env-key";
 // ── BaseLinter protected-method ports (base-linter.ts:520-551) ───────────────
 /** Port of `BaseLinter.checkMissingNameOrType` (`:520-527`). */
 function checkMissingNameOrType(data, frontmatter) {
@@ -149,10 +152,14 @@ function collectSuppressedKeys(raw) {
     return suppressed;
 }
 /**
- * env/secret dangerous-key scan (`lint/index.ts:191-218` + `env-key-rules.ts#checkVaultForDangerousKeys`),
+ * env/secret dangerous-key scan (`lint/index.ts:191-218` + `env-key-rules.ts#checkEnvForDangerousKeys`),
  * keyed on `type` and preserving the `.env`-suffix narrowness (see file header).
- * Reads the overlay `raw`, not disk. `type`==="env" ⇒ ref prefix `env:`;
- * `type`==="secret" ⇒ `secret:` (`lint/index.ts:201-204`).
+ * Reads the overlay `raw`, not disk.
+ *
+ * The emitted `Ref:` comes from `conceptIdForStashFile` — the one place that
+ * spells a diagnostic ref the way `akm show` accepts it. It used to be
+ * hand-built as `env:<base>` / `secret:<base>`, a colon grammar the 0.9.0 ref
+ * parser rejects outright — a dead-end ref on a *security* finding.
  */
 export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     if (type !== "env" && type !== "secret")
@@ -160,20 +167,19 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     const baseNameWithExt = path.basename(relPath);
     if (!baseNameWithExt.endsWith(".env"))
         return []; // NARROWNESS: collectEnvFiles only visits *.env
-    const refPrefix = type === "env" ? "env" : "secret";
-    const baseName = path.basename(relPath, ".env");
-    const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+    // `relPath` is already stash-root-relative, so "." IS the stash root here.
+    const ref = conceptIdForStashFile(type, ".", relPath);
     const keys = scanKeys(raw);
     const suppressed = collectSuppressedKeys(raw);
     const diagnostics = [];
     for (const key of keys) {
-        if (!isDangerousVaultKey(key))
+        if (!isDangerousEnvKey(key))
             continue;
         if (suppressed.has(key))
             continue;
         diagnostics.push({
             file: relPath,
-            issue: "dangerous-vault-key",
+            issue: "dangerous-env-key",
             detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${ref}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
             fixed: false,
         });
@@ -221,10 +227,7 @@ export async function perTypeValidateChecks(args) {
         case "task":
             return taskDiagnostics(relPath, data);
         case "workflow":
-            // WorkflowLinter only ever sees `.md` in production (collectMarkdownFiles
-            // filters `.md`); YAML programs are not a lint path (lint golden pins the
-            // workflow-program via parseWorkflowProgram, not a linter). So the extra
-            // checks apply to markdown workflows only.
+            // Unified workflows are markdown-only; other extensions are not a lint path.
             return ext === ".md" ? workflowDiagnostics(relPath, raw, body) : [];
         case "memory":
             return memoryDiagnostics(relPath, data, body, ctx);
@@ -261,17 +264,16 @@ export function factDiagnostics(relPath, data) {
     }
     return [];
 }
-/** TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML. */
+/**
+ * TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML.
+ * Field rules come from the shared {@link taskFieldProblems} (see its doc for
+ * the lint-vs-parser reconciliation story); this sweep additionally requires
+ * at least one target.
+ */
 export function taskDiagnostics(relPath, data) {
     if (data === null || Object.keys(data).length === 0)
         return [];
-    const missing = [];
-    if (!("schedule" in data) || typeof data.schedule !== "string" || data.schedule.trim() === "") {
-        missing.push("schedule");
-    }
-    if (!("enabled" in data) || typeof data.enabled !== "boolean") {
-        missing.push("enabled (must be a boolean)");
-    }
+    const missing = taskFieldProblems(data);
     const hasTarget = "prompt" in data || "workflow" in data || "command" in data;
     if (!hasTarget)
         missing.push("prompt, workflow, or command");
@@ -298,8 +300,9 @@ export function matchWorkflowPlaceholder(body) {
 }
 /**
  * WorkflowLinter's `invalid-workflow-structure` check (`workflow-linter.ts:48-77`):
- * re-parse via `parseWorkflow` and surface every structural error, skipping the
- * read-only `/.cache/`+`/registry/` cached copies. Shared with the live linter;
+ * parse and compile through the unified workflow frontend, surfacing every
+ * structural or semantic error and skipping the read-only `/.cache/`+`/registry/`
+ * cached copies. Shared with the live linter;
  * `parsePath` is the path handed to `parseWorkflow` (the adapter passes the
  * change relPath, the CLI passes the absolute filePath — matching each caller's
  * legacy behavior). NEVER writes.
@@ -319,6 +322,18 @@ export function workflowStructureDiagnostics(relPath, raw, parsePath) {
                     fixed: false,
                 });
             }
+            return diagnostics;
+        }
+        const compiled = compileWorkflowPlan(result.document, path.basename(parsePath, path.extname(parsePath)));
+        if (!compiled.ok) {
+            for (const err of compiled.errors) {
+                diagnostics.push({
+                    file: relPath,
+                    issue: "invalid-workflow-structure",
+                    detail: err.message,
+                    fixed: false,
+                });
+            }
         }
     }
     catch (e) {
@@ -334,8 +349,8 @@ export function workflowStructureDiagnostics(relPath, raw, parsePath) {
 /**
  * WorkflowLinter extra checks (`workflow-linter.ts:22-79`), READ-ONLY:
  * `placeholder-stub` is NEVER deleted here (validate MUST NOT write) — emitted
- * as a non-fixable Diagnostic. `invalid-workflow-structure` re-parses via
- * `parseWorkflow` over the whole `raw` (mirroring `parseWorkflow(ctx.raw, …)`).
+ * as a non-fixable Diagnostic. `invalid-workflow-structure` parses and compiles
+ * the whole `raw` through the unified workflow frontend.
  */
 function workflowDiagnostics(relPath, raw, body) {
     const diagnostics = [];

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

@@ -4,7 +4,7 @@
 /**
  * Index-time metadata fold for the `akm` adapter's `recognize` — akm 0.9.0
  * chunk-2, WI-C, implementing spec §2 ("the nine index-time metadata
- * contributors move into recognize") + the 2 workflow contributors.
+ * contributors move into recognize") + the workflow contributor.
  *
  * This leaf reproduces the 11 `registerMetadataContributor` sites keyed on the
  * winning RENDERER name (exactly how each contributor's `appliesTo({ rendererName })`
@@ -14,8 +14,7 @@
  *     lesson-frontmatter-metadata, memory-frontmatter-metadata,
  *     script-comment-metadata, env-file-metadata, secret-file-metadata,
  *     task-yaml-metadata, session-md-metadata, fact-md-metadata;
- *   - `workflows/renderer.ts` (2): workflow-document-metadata (workflow-md),
- *     workflow-program-metadata (workflow-program-yaml).
+ *   - `workflows/renderer.ts` (1): workflow-document-metadata (workflow-md).
  *
  * ── Cycle-safety (chunk-2 ratchet, baseline 18) ──
  *
@@ -58,8 +57,6 @@ import fs from "node:fs";
 import { parse as parseYaml } from "yaml";
 import { listKeys } from "../../../commands/env/env.js";
 import { parseWorkflow } from "../../../workflows/parser.js";
-import { parseWorkflowProgram } from "../../../workflows/program/parser.js";
-import { programStepInstructions, projectProgramParameters } from "../../../workflows/program/project.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { parseMarkdownToc } from "../../asset/markdown.js";
 import { nonEmptyString } from "./shared.js";
@@ -312,20 +309,23 @@ export function foldRecognizedMetadata(rendererName, file) {
                     return out;
                 const doc = result.document;
                 const hints = new Set();
-                hints.add(doc.title);
+                if (doc.preamble)
+                    hints.add(doc.preamble);
                 for (const step of doc.steps) {
-                    hints.add(step.title);
                     hints.add(step.id);
-                    hints.add(step.instructions.text);
-                    for (const criterion of step.completionCriteria ?? [])
-                        hints.add(criterion.text);
+                    if (step.instructions)
+                        hints.add(step.instructions.text);
+                    if (step.gateRubric)
+                        hints.add(step.gateRubric.text);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
-                if (doc.parameters?.length) {
-                    out.parameters = doc.parameters.map((p) => ({
-                        name: p.name,
-                        ...(p.description ? { description: p.description } : {}),
-                    }));
+                if (doc.params) {
+                    const parameters = Object.entries(doc.params).map(([name, schema]) => {
+                        const description = schema.description;
+                        return { name, ...(typeof description === "string" && description ? { description } : {}) };
+                    });
+                    if (parameters.length)
+                        out.parameters = parameters;
                 }
             }
             catch {
@@ -333,35 +333,6 @@ export function foldRecognizedMetadata(rendererName, file) {
             }
             return out;
         }
-        // ── workflow-program-metadata (workflow-program-yaml) ──
-        case "workflow-program-yaml": {
-            try {
-                const result = parseWorkflowProgram(file.content(), { path: file.relPath });
-                if (!result.ok)
-                    return out;
-                const program = result.program;
-                const hints = new Set();
-                hints.add(program.name);
-                for (const step of program.steps) {
-                    hints.add(step.id);
-                    if (step.title)
-                        hints.add(step.title);
-                    hints.add(programStepInstructions(step));
-                    for (const criterion of step.gate?.criteria ?? [])
-                        hints.add(criterion);
-                }
-                out.searchHints = Array.from(hints).filter(Boolean);
-                if (!out.description && program.description)
-                    out.description = program.description;
-                const parameters = projectProgramParameters(program);
-                if (parameters?.length)
-                    out.parameters = parameters;
-            }
-            catch {
-                // See file header: broken programs drop at drain time, not here.
-            }
-            return out;
-        }
         default:
             // No contributor applies to this renderer (e.g. skill-md/command-md/
             // agent-md — the static-only mappings carry no metadata contributor).

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

@@ -12,11 +12,13 @@
  *
  * ── 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
@@ -25,6 +27,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { taskFieldProblems } 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";
@@ -68,15 +71,15 @@ function parseTaskYaml(raw) {
     }
     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)");
@@ -120,8 +123,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;