akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/commands/tasks/tasks.js

@@ -40,8 +40,12 @@ export async function akmTasksAdd(input, deps = {}) {
     if (targetCount !== 1) {
         throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
-    if (input.workflow && (input.engine !== undefined || input.model !== undefined || input.timeoutMs !== undefined)) {
-        throw new UsageError("Workflow tasks accept only --params; engine, model, and timeout are prompt-task fields.", "INVALID_FLAG_VALUE");
+    // `--timeout-ms` IS valid on a workflow task: it is the whole-run bound the
+    // task runner turns into an abort signal (issue 11), the same one
+    // `akm workflow run --timeout` applies interactively. Engine and model stay
+    // prompt-only — a workflow's engines come from its frozen plan.
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Workflow tasks accept --params and --timeout-ms; engine and model are prompt-task fields.", "INVALID_FLAG_VALUE");
     }
     if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
         throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
@@ -597,6 +601,8 @@ function renderTaskYaml(input) {
         if (input.params) {
             obj.params = parseJsonObjectArg(input.params);
         }
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;

package/dist/commands/workflow-cli.js

@@ -9,6 +9,7 @@
  */
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
+import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
@@ -152,7 +153,6 @@ const workflowRunCommand = defineJsonCommand({
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0, WORKFLOW_MAX_RETRIES);
         const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
         const controller = new AbortController();
-        let timedOut = false;
         let signalExitCode;
         const interrupt = (signal) => {
             signalExitCode = signal === "SIGINT" ? 130 : 143;
@@ -162,13 +162,12 @@ const workflowRunCommand = defineJsonCommand({
         const onSigterm = () => interrupt("SIGTERM");
         process.once("SIGINT", onSigint);
         process.once("SIGTERM", onSigterm);
-        const timer = timeoutMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                timedOut = true;
-                controller.abort(new Error(`Workflow run timed out after ${timeoutMs}ms.`));
-            }, timeoutMs);
-        timer?.unref?.();
+        // The same deadline a scheduled workflow task arms (`tasks/runner.ts`),
+        // sharing this controller with the signal handlers above.
+        const deadline = armAbortDeadline(controller, {
+            timeoutMs,
+            reason: `Workflow run timed out after ${timeoutMs}ms.`,
+        });
         try {
             const result = await runWorkflowSteps({
                 target: args.target,
@@ -177,15 +176,22 @@ const workflowRunCommand = defineJsonCommand({
                 ...(maxRetries !== undefined ? { maxRetries } : {}),
                 signal: controller.signal,
             });
+            // The abort is observed between steps, so a deadline landing in the run's
+            // final bookkeeping fires on a run that then finishes. Reporting that as
+            // timed out would send an operator to resume a run with nothing left to
+            // resume — `tasks/runner.ts` suppresses the same case.
+            const timedOut = deadline.timedOut() && result.run.status !== "completed";
             const rendered = { ...result, ...(timedOut ? { timedOut: true } : {}) };
             output("workflow-run", rendered);
-            if (result.run.status === "failed" || result.gateRejection || result.aborted) {
+            // `blocked` is a stopped, unverified run — a verification-judge failure
+            // leaves it there for `akm workflow resume` — so it must not exit 0 and
+            // read as success to a script (it maps to 1 for scheduled tasks too).
+            if (result.run.status === "failed" || result.run.status === "blocked" || result.gateRejection || result.aborted) {
                 process.exitCode = signalExitCode ?? EXIT_CODES.GENERAL;
             }
         }
         finally {
-            if (timer)
-                clearTimeout(timer);
+            deadline.disarm();
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
         }

package/dist/core/abort-deadline.js

@@ -0,0 +1,28 @@
+// 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/.
+export function armAbortDeadline(controller, options) {
+    const { timeoutMs, reason } = options;
+    if (timeoutMs === null || timeoutMs === undefined) {
+        return { disarm: () => { }, timedOut: () => false };
+    }
+    const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
+    let fired = false;
+    let timer = setTimeoutImpl(() => {
+        timer = undefined;
+        fired = true;
+        controller.abort(new Error(reason));
+    }, timeoutMs);
+    // A pending deadline must never be the reason the process stays alive.
+    timer?.unref?.();
+    return {
+        disarm: () => {
+            if (timer !== undefined) {
+                clearTimeoutImpl(timer);
+                timer = undefined;
+            }
+        },
+        timedOut: () => fired,
+    };
+}

package/dist/core/adapter/adapters/agent-skills-adapter.js

@@ -27,10 +27,13 @@
  *   - `skill-description-too-long` — description must be 1-1024 chars.
  *   - `missing-skill-md` — a package dir with no SKILL.md (edge case; git cannot
  *     commit an empty dir, so it is covered by a directory-level check, not a
- *     fixture).
+ *     fixture). Implemented by {@link missingManifestDiagnostics}, which scans
+ *     the component root through `ValidateContext.list` — the change-set loop
+ *     cannot reach it, because a change is always a file and a manifest-less
+ *     package contributes no SKILL.md change (issue #774).
  *
- * Only `missing-skill-md` is coded elsewhere today; the two field codes are
- * APPROVED-BUT-NOT-YET-CODED and are implemented here. Base checks are NOT run:
+ * The two field codes are APPROVED-BUT-NOT-YET-CODED elsewhere and are
+ * implemented here. Base checks are NOT run:
  * a SKILL.md carries no `updated` field, so `missing-updated` would fire on
  * every conformant skill and contradict the lint golden.
  *
@@ -127,6 +130,79 @@ function skillFieldDiagnostics(relPath, dirName, data) {
     }
     return diagnostics;
 }
+/**
+ * How deep below a candidate package directory the manifest probe looks. Agent
+ * Skills packages sit at the component root (`<name>/SKILL.md`), occasionally
+ * one group level down (`<group>/<name>/SKILL.md`) — this bound keeps a deep
+ * resource tree (a package's `reference/`, `assets/`, …) from turning the lint
+ * sweep into a full recursive walk.
+ */
+const MAX_PACKAGE_PROBE_DEPTH = 3;
+function missingManifestDiagnostic(dir) {
+    return { file: dir, issue: "missing-skill-md", detail: `no SKILL.md in ${dir}/`, fixed: false };
+}
+/**
+ * Classify one directory as a package, a grouping directory, or one broken
+ * package candidate. Once a real package root is found, its resource
+ * directories are never descended into. If manifests exist only below this
+ * directory, it is a group and each sibling candidate is checked independently.
+ */
+async function scanPackageCandidate(dir, entries, ctx, depth) {
+    if (entries.includes(SKILL_MANIFEST))
+        return { containsManifest: true, diagnostics: [] };
+    if (depth >= MAX_PACKAGE_PROBE_DEPTH) {
+        return { containsManifest: false, diagnostics: [missingManifestDiagnostic(dir)] };
+    }
+    const children = [];
+    for (const entry of entries) {
+        if (entry.startsWith("."))
+            continue;
+        const child = `${dir}/${entry}`;
+        // `list` on a FILE yields `[]` (the read throws and is swallowed), so an
+        // empty listing is the "not a directory worth descending" signal — no
+        // separate stat is available on ValidateContext, and none is needed.
+        const childEntries = await ctx.list(child);
+        if (childEntries.length === 0)
+            continue;
+        children.push(await scanPackageCandidate(child, childEntries, ctx, depth + 1));
+    }
+    if (children.some((child) => child.containsManifest)) {
+        return {
+            containsManifest: true,
+            diagnostics: children.flatMap((child) => child.diagnostics),
+        };
+    }
+    // No descendant establishes this as a grouping directory. Diagnose the
+    // candidate itself, not its resource subdirectories.
+    return { containsManifest: false, diagnostics: [missingManifestDiagnostic(dir)] };
+}
+/**
+ * The directory-level `missing-skill-md` check (issue #774).
+ *
+ * `validate` walks CHANGES, and a change is always a file — so a package
+ * directory carrying resources but no manifest contributes nothing the
+ * change-loop can see, and the check the spec (§4.5) and the lint golden's
+ * `missingSkillMd` edge case both name was unreachable. This scans the
+ * component root through {@link ValidateContext.list} instead, so the case is
+ * actually reported.
+ *
+ * A package's own resource dirs (`pdf-processing/reference/`) are part of the
+ * item, not candidate packages. Grouping directories are supported too, but
+ * their children are classified independently so one valid package cannot hide
+ * a manifest-less sibling.
+ */
+async function missingManifestDiagnostics(ctx) {
+    const diagnostics = [];
+    for (const name of await ctx.list(".")) {
+        if (name.startsWith("."))
+            continue; // .git, .github, … are not skill packages
+        const entries = await ctx.list(name);
+        if (entries.length === 0)
+            continue; // a root file (README.md), or an untrackable empty dir
+        diagnostics.push(...(await scanPackageCandidate(name, entries, ctx, 1)).diagnostics);
+    }
+    return diagnostics;
+}
 async function validate(_c, changes, ctx) {
     const diagnostics = [];
     const seenDirs = new Set();
@@ -142,10 +218,12 @@ async function validate(_c, changes, ctx) {
         if (seenDirs.has(pkg.conceptId))
             continue;
         seenDirs.add(pkg.conceptId);
-        // missing-skill-md is unreachable here (the change IS a SKILL.md); the empty-dir
-        // case is served by {@link directorySkillDiagnostics} for callers that scan dirs.
+        // `missing-skill-md` cannot fire here — the change IS a SKILL.md. The
+        // manifest-less package case is served by {@link missingManifestDiagnostics}
+        // below, which scans directories rather than changes.
         diagnostics.push(...skillFieldDiagnostics(toPosix(change.path), pkg.dirName, parseFrontmatter(raw).data));
     }
+    diagnostics.push(...(await missingManifestDiagnostics(ctx)));
     return diagnostics;
 }
 export const agentSkillsAdapter = {

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

@@ -80,8 +80,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, } from "../../../indexer/passes/metadata.js";
+import { parseTaskYaml, taskYamlParseDetail } from "../../../tasks/schema.js";
 import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { recognizeMatch } from "../recognize-match.js";
@@ -380,16 +380,19 @@ async function validate(c, changes, ctx) {
         // everything else → `parseFrontmatter`.
         let parsed;
         if (type === "task") {
-            let data = {};
-            try {
-                const doc = parseYaml(raw);
-                if (doc && typeof doc === "object" && !Array.isArray(doc))
-                    data = doc;
+            const task = parseTaskYaml(raw);
+            // A parse failure is its OWN finding: every task rule short-circuits on
+            // an empty mapping, so collapsing "unparseable" onto `{}` made a broken
+            // task file validate clean (issue #760). Mirrors the CLI sweep.
+            if (!task.ok) {
+                diagnostics.push({
+                    file: change.path,
+                    issue: "invalid-task-yaml",
+                    detail: taskYamlParseDetail(task.error),
+                    fixed: false,
+                });
             }
-            catch {
-                data = {};
-            }
-            parsed = { data, content: raw, frontmatter: null };
+            parsed = { data: task.data, content: raw, frontmatter: null };
         }
         else {
             const p = parseFrontmatter(raw);

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

@@ -52,7 +52,7 @@
  */
 import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
-import { taskFieldProblems } from "../../../tasks/schema.js";
+import { isPresentTarget, 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";
@@ -187,20 +187,29 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     return diagnostics;
 }
 // ── skill directory check (SkillLinter.lintDirectory) ────────────────────────
+/** The akm-native skill placement dir — the default gate for {@link skillDirectoryDiagnostics}. */
+const AKM_SKILL_DIRS = new Set(["skills"]);
 /**
  * Reproduce `SkillLinter.lintDirectory` (`skill-linter.ts:31-45`) in the
- * change-set model: for a change under `skills/<name>/…`, emit `missing-skill-md`
- * when `skills/<name>/SKILL.md` is absent from the overlay. `seen` dedups so a
- * dir with multiple changed files reports once (matching the per-subdir call).
- * `file`/`detail` mirror the live check exactly (relDir + `no SKILL.md in <relDir>/`).
+ * change-set model: for a change under `<skillDir>/<name>/…`, emit
+ * `missing-skill-md` when `<skillDir>/<name>/SKILL.md` is absent from the
+ * overlay. `seen` dedups so a dir with multiple changed files reports once
+ * (matching the per-subdir call). `file`/`detail` mirror the live check exactly
+ * (relDir + `no SKILL.md in <relDir>/`).
+ *
+ * `skillDirs` defaults to the akm-native `skills/` placement dir. The tool-dir
+ * adapters pass their OWN accepted spellings, because opencode also accepts the
+ * singular `skill/` alias on read (`opencode-adapter.ts` LAYOUT) — with the
+ * gate hardcoded to `"skills"`, an identical manifest-less package went flagged
+ * under `skills/` and unflagged under `skill/` (issue #774).
  */
-export async function skillDirectoryDiagnostics(relPath, seen, ctx) {
+export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs = AKM_SKILL_DIRS) {
     const segments = relPath
         .replace(/\\/g, "/")
         .split("/")
         .filter((s) => s.length > 0);
-    if (segments.length < 3 || segments[0] !== "skills")
-        return []; // must be skills/<name>/<file…>
+    if (segments.length < 3 || !skillDirs.has(segments[0]))
+        return []; // must be <skillDir>/<name>/<file…>
     const skillDir = `${segments[0]}/${segments[1]}`;
     if (seen.has(skillDir))
         return [];
@@ -274,7 +283,11 @@ export function taskDiagnostics(relPath, data) {
     if (data === null || Object.keys(data).length === 0)
         return [];
     const missing = taskFieldProblems(data);
-    const hasTarget = "prompt" in data || "workflow" in data || "command" in data;
+    // Presence, matching the runtime parser's rule (src/tasks/parser.ts): an
+    // empty string is NOT a target there, so a `workflow: ""` that linted clean
+    // here failed at run time with MISSING_REQUIRED_ARGUMENT — a file the linter
+    // called valid but that could never run.
+    const hasTarget = ["prompt", "workflow", "command"].some((key) => isPresentTarget(data[key]));
     if (!hasTarget)
         missing.push("prompt, workflow, or command");
     if (missing.length > 0) {
@@ -300,51 +313,94 @@ export function matchWorkflowPlaceholder(body) {
 }
 /**
  * WorkflowLinter's `invalid-workflow-structure` check (`workflow-linter.ts:48-77`):
- * 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.
+ * the ERROR half of {@link workflowFrontendDiagnostics}, for callers that only
+ * ever surface fatal findings — the read-only adapter `validate` path and
+ * `akm migrate`'s stale-workflow probe. A caller that ALSO surfaces the
+ * advisories must call {@link workflowFrontendDiagnostics} once instead of
+ * pairing this with a second view. NEVER writes.
  */
 export function workflowStructureDiagnostics(relPath, raw, parsePath) {
+    return workflowFrontendDiagnostics(relPath, raw, parsePath).errors;
+}
+/**
+ * The `Diagnostic.line` fragment for a line-anchored workflow finding. Every
+ * `WorkflowError` carries a 1-indexed `line`; this used to be DROPPED here, so
+ * an author linting a 300-line workflow got a message with no location while
+ * the same error rendered as `path:line — message` on the `workflow create`
+ * path. Spread (`...lineOf(err)`) rather than assigned, so a nonsense line
+ * never materializes the optional key on a whole-file finding.
+ */
+function lineOf(err) {
+    return typeof err.line === "number" && Number.isFinite(err.line) && err.line > 0 ? { line: err.line } : {};
+}
+/**
+ * ONE parse+compile of a workflow through the unified frontend, returning both
+ * halves of what it produces: fatal `invalid-workflow-structure` findings, and
+ * `compileWorkflowPlan`'s non-fatal `workflow-warning` advisories (a step with
+ * no `output:` schema, a reference to an undeclared param). The read-only
+ * `/.cache/` + `/registry/` cached copies are skipped, and nothing is written.
+ *
+ * `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).
+ *
+ * A caller that surfaces BOTH halves must call this once and route the result
+ * itself. The frontend is expensive — instruction bodies reach
+ * `WORKFLOW_MAX_INSTRUCTION_BYTES` — so asking for each half through its own
+ * view parses and compiles every workflow in the stash twice.
+ */
+export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
+    const none = { errors: [], warnings: [] };
     if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
-        return [];
-    const diagnostics = [];
+        return none;
+    const errors = [];
+    const warnings = [];
     try {
         const result = parseWorkflow(raw, { path: parsePath });
         if (!result.ok) {
             for (const err of result.errors ?? []) {
-                diagnostics.push({
+                errors.push({
                     file: relPath,
                     issue: "invalid-workflow-structure",
                     detail: err.message ?? String(err),
                     fixed: false,
+                    ...lineOf(err),
                 });
             }
-            return diagnostics;
+            return { errors, warnings };
         }
         const compiled = compileWorkflowPlan(result.document, path.basename(parsePath, path.extname(parsePath)));
         if (!compiled.ok) {
             for (const err of compiled.errors) {
-                diagnostics.push({
+                errors.push({
                     file: relPath,
                     issue: "invalid-workflow-structure",
                     detail: err.message,
                     fixed: false,
+                    ...lineOf(err),
                 });
             }
+            return { errors, warnings };
+        }
+        for (const warning of compiled.warnings) {
+            warnings.push({
+                file: relPath,
+                issue: "workflow-warning",
+                detail: warning.message,
+                fixed: false,
+                ...lineOf(warning),
+            });
         }
     }
     catch (e) {
-        diagnostics.push({
+        errors.push({
             file: relPath,
             issue: "invalid-workflow-structure",
             detail: `workflow parser error: ${e instanceof Error ? e.message : String(e)}`,
             fixed: false,
         });
     }
-    return diagnostics;
+    return { errors, warnings };
 }
 /**
  * WorkflowLinter extra checks (`workflow-linter.ts:22-79`), READ-ONLY:

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

@@ -10,6 +10,10 @@
  * 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 `version: 2`, a `schedule`, and EXACTLY ONE target
@@ -26,13 +30,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { taskFieldProblems } from "../../../tasks/schema.js";
+import { isPresentTarget, 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). */
@@ -59,18 +62,6 @@ 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: the shared field rules
  * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
@@ -80,7 +71,9 @@ function taskDiagnostics(relPath, data) {
     if (Object.keys(data).length === 0)
         return [];
     const problems = taskFieldProblems(data);
-    const targets = TARGET_KEYS.filter((k) => k in data && data[k] !== undefined && data[k] !== null);
+    // Shared presence rule (src/tasks/schema.ts): an empty string or empty array
+    // is not a target, matching the runtime parser.
+    const targets = TARGET_KEYS.filter((k) => isPresentTarget(data[k]));
     if (targets.length === 0)
         problems.push("exactly one target (prompt, workflow, or command)");
     else if (targets.length > 1)
@@ -99,16 +92,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;
-        diagnostics.push(...taskDiagnostics(toPosix(change.path), parseTaskYaml(raw)));
+        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(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. */
@@ -143,7 +166,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/dotenv-adapter.js

@@ -61,6 +61,25 @@ function classify(relPath) {
     }
     return null;
 }
+/**
+ * True when `--sensitive` marked this asset, via the sibling marker file that
+ * `akm env create --sensitive` / `akm secret create --sensitive` writes:
+ * `env/<name>.sensitive` for `env/<name>.env`, `secrets/<name>.sensitive` for
+ * `secrets/<name>`.
+ *
+ * The flag documents itself as excluding the asset from BOTH `env list` output
+ * and the search index. Indexing filters are adapter-owned (the walk no longer
+ * pre-filters), and the akm adapter abstains on the marker — but this adapter
+ * only skipped files whose OWN name ended in `.sensitive`. A dotenv bundle is a
+ * legal env/secret write target, so a marked `env/prod.env` there was still
+ * indexed with every KEY NAME as a hint and a marked secret still indexed by
+ * name, while `env list` / `secret list` correctly hid them. The two surfaces
+ * disagreed about a documented promise.
+ */
+function hasSensitiveMarker(absPath, type) {
+    const marker = type === "env" ? absPath.replace(/\.env$/i, ".sensitive") : `${absPath}.sensitive`;
+    return marker !== absPath && fs.existsSync(marker);
+}
 /** Extract KEY NAMES (never values) from an env file's raw content, first-appearance order, deduped. */
 function scanKeyNames(raw) {
     const keys = [];
@@ -81,6 +100,8 @@ function recognize(c, file) {
     const type = classify(file.relPath);
     if (type === null)
         return null;
+    if (hasSensitiveMarker(file.absPath, type))
+        return null;
     const posix = toPosix(file.relPath);
     const raw = file.content();
     if (type === "env") {

package/dist/core/adapter/adapters/tool-dir-shared.js

@@ -185,9 +185,11 @@ export async function validateToolDir(layout, c, changes, ctx) {
             continue;
         const relPath = toPosix(change.path);
         // The one coded skill check (missing-skill-md) fires on ANY change under a
-        // `skills/<name>/…` package (self-gated + deduped), even a bundled resource —
-        // mirrors the akm adapter's per-change SkillLinter.lintDirectory pass.
-        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx)));
+        // `<skillDir>/<name>/…` package (self-gated + deduped), even a bundled
+        // resource — mirrors the akm adapter's per-change SkillLinter.lintDirectory
+        // pass. `layout.skillDirs` is passed so opencode's singular `skill/` alias
+        // is checked identically to `skills/` (issue #774).
+        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx, layout.skillDirs)));
         const cls = classify(change.path, layout);
         if (cls === null)
             continue;

package/dist/core/asset/frontmatter.js

@@ -10,6 +10,8 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { existingFileMode, writeFileAtomic } from "../common.js";
+import { recordWrittenPath } from "../write-provenance.js";
 import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
@@ -142,7 +144,14 @@ export function mutateFrontmatter(filePath, mutator) {
     const next = parsed.frontmatter !== null
         ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
         : assembleAsset(nextFrontmatter, parsed.content);
-    fs.writeFileSync(filePath, next, "utf8");
+    // Atomic, like the canonical asset write: this rewrites a file the user
+    // authored, and a truncate-in-place left a window where a crash or a
+    // concurrent reader saw a half-written or empty asset. The existing mode is
+    // preserved so stamping frontmatter never changes an asset's permissions.
+    writeFileAtomic(filePath, next, existingFileMode(filePath));
+    // #652: in-place frontmatter stamps (belief state, contradiction markers,
+    // salience) are real asset mutations — journal them for the run's sync.
+    recordWrittenPath(filePath);
     return true;
 }
 export function parseFrontmatterBlock(raw) {