akm-cli 0.9.0-beta.2 → 0.9.0-beta.26

package/dist/commands/lint/base-linter.js

@@ -39,7 +39,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getAssetTypes, resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { findSafeInsertionPoint } from "./markdown-insertion.js";
+import { findFenceRegions, findSafeInsertionPoint } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function formatDate(d) {
     const y = d.getFullYear();
@@ -65,34 +65,69 @@ function checkUnquotedColon(frontmatterText) {
     return null;
 }
 function fixUnquotedColon(raw) {
-    return raw.replace(/^(description:\s*)(.*)/m, (_match, prefix, value) => {
-        const trimmed = value.trim();
-        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-            return _match;
-        }
-        const escaped = trimmed.replace(/"/g, '\\"');
-        return `${prefix}"${escaped}"`;
-    });
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return raw;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return raw;
+    for (let i = 1; i < closeIdx; i++) {
+        const m = lines[i].match(/^(description:\s*)(.*)/);
+        if (!m)
+            continue;
+        const prefix = m[1];
+        const value = m[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length >= 2))
+            continue;
+        lines[i] = `${prefix}"${value.replace(/"/g, '\\"')}"`;
+        break;
+    }
+    return lines.join("\n");
 }
 function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
 }
 function fixMissingUpdated(raw, mtime) {
     const dateStr = formatDate(mtime);
-    return raw.replace(/^(---\n[\s\S]*?)\n---/m, `$1\nupdated: ${dateStr}\n---`);
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return raw;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return raw;
+    lines.splice(closeIdx, 0, `updated: ${dateStr}`);
+    return lines.join("\n");
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
 function checkStalePath(body) {
-    const pathRe = /\/home\/[^\s"'`)\]>,]+/g;
+    const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
     let match;
+    const stale = [];
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = pathRe.exec(body)) !== null) {
         const candidate = match[0];
         if (!fs.existsSync(candidate)) {
-            return candidate;
+            stale.push(candidate);
         }
     }
-    return null;
+    return stale;
+}
+// ── fence-strip helper ────────────────────────────────────────────────────────
+/**
+ * Returns `body` with all fenced code block lines replaced by empty strings,
+ * so that ref-shaped tokens inside ``` examples are not flagged as broken refs.
+ */
+function stripFencedBlocks(body) {
+    const lines = body.split(/\r?\n/);
+    const regions = findFenceRegions(lines);
+    if (regions.length === 0)
+        return body;
+    for (const { start, end } of regions) {
+        for (let i = start; i <= end; i++)
+            lines[i] = "";
+    }
+    return lines.join("\n");
 }
 // ── missing-ref helpers ───────────────────────────────────────────────────────
 /**
@@ -122,9 +157,8 @@ const REF_RE = new RegExp(`(?:^|[\\s\`"'(])((${buildRefTypeAlternation()}):[^\\s
  * preserved to keep pre-0.9 behaviour byte-identical:
  *   - `script`: returns null (scripts live in nested dirs with arbitrary
  *     extensions — unresolvable by the slug-based walker, as the contract pins).
- *   - `task`: the registry stores tasks as `<id>.yml`, but the missing-ref
- *     linter has always resolved `task:` refs against `tasks/<id>.md`; that
- *     behaviour is held constant here (non-env/secret behaviour is unchanged).
+ *   - `task`: M1 fix — tasks are stored as `<id>.yml` on disk, so resolve
+ *     `task:` refs against `tasks/<id>.yml` to match actual on-disk layout.
  *
  * Exported for contract testing — see header CONTRACT block.
  */
@@ -132,9 +166,9 @@ export function refToRelPath(refType, refName) {
     // script is intentionally unresolvable (contract-pinned).
     if (refType === "script")
         return null;
-    // Preserve the legacy `.md` resolution for tasks.
+    // M1: tasks are stored as .yml on disk; resolve task: refs against tasks/<id>.yml.
     if (refType === "task")
-        return path.join(TYPE_DIRS.task ?? "tasks", `${refName}.md`);
+        return path.join(TYPE_DIRS.task ?? "tasks", `${refName}.yml`);
     const typeDir = TYPE_DIRS[refType];
     if (!typeDir)
         return null; // unknown type — skip
@@ -169,9 +203,11 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
             try {
                 const knowledgeDir = path.join(root, "knowledge");
                 if (fs.existsSync(knowledgeDir) && fs.statSync(knowledgeDir).isDirectory()) {
-                    const entries = fs.readdirSync(knowledgeDir);
+                    const entries = fs.readdirSync(knowledgeDir, { withFileTypes: true });
                     for (const entry of entries) {
-                        const subPath = path.join(knowledgeDir, entry, `${refName}.md`);
+                        if (!entry.isDirectory())
+                            continue;
+                        const subPath = path.join(knowledgeDir, entry.name, `${refName}.md`);
                         if (fs.existsSync(subPath))
                             return true;
                     }
@@ -207,8 +243,10 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
     const missing = [];
     let match;
     const re = new RegExp(REF_RE.source, REF_RE.flags);
+    // C1: Strip fenced code blocks so example refs inside ``` are not flagged.
+    const scanBody = stripFencedBlocks(body);
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
-    while ((match = re.exec(body)) !== null) {
+    while ((match = re.exec(scanBody)) !== null) {
         const fullRef = match[1]; // e.g. "workflow:foo" or "local//workflow:foo"
         // Skip shell variables: memory:$(cmd) or knowledge:${VAR}
         if (fullRef.includes("$(") || fullRef.includes("${")) {
@@ -241,6 +279,10 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
         if (refName.length <= 1 || refName === "**") {
             continue;
         }
+        // Skip template placeholder refs like skill:<name> or workflow:<my-workflow>
+        if (refName.startsWith("<") || refName.includes("<")) {
+            continue;
+        }
         const relPath = refToRelPath(refType, refName);
         if (relPath === null)
             continue; // type is skipped
@@ -279,7 +321,15 @@ function extractFrontmatterRefs(data, body) {
         const fromInner = readRefsArray(innerData.refs);
         if (fromInner !== null)
             return fromInner;
+        // Session-checkpoint bodies are raw transcripts; ref-shaped tokens in the
+        // body are literals (grep patterns, JSON, tool output), not live refs.
+        // Return [] so missing-ref skips the body scan entirely.
+        if (typeof innerData.akm_memory_kind === "string")
+            return [];
     }
+    // Same guard for outer frontmatter (e.g. opencode session files).
+    if (typeof data.akm_memory_kind === "string")
+        return [];
     return null;
 }
 function readRefsArray(value) {
@@ -368,6 +418,47 @@ function parseInnerFrontmatterBlock(body) {
  * (in practice the base class updates `ctx.raw` in place when `fix` is true).
  */
 export class BaseLinter {
+    /**
+     * Check for missing `name` or `type` fields in frontmatter.
+     *
+     * Returns a detail string if fields are absent/empty, `null` if all present.
+     */
+    checkMissingNameOrType(data, frontmatterText) {
+        if (!frontmatterText)
+            return null;
+        const missingFields = [];
+        if (!("name" in data) || !data.name)
+            missingFields.push("name");
+        if (!("type" in data) || !data.type)
+            missingFields.push("type");
+        if (missingFields.length === 0)
+            return null;
+        return `missing fields: ${missingFields.join(", ")}`;
+    }
+    /**
+     * Validate that the `type` field value is one of an allowed set.
+     *
+     * Returns a detail string if the value is present but invalid, `null` if valid or absent.
+     */
+    checkInvalidTypeValue(data, allowedTypes) {
+        if (!("type" in data) || !data.type)
+            return null; // absent — covered by checkMissingNameOrType
+        const value = String(data.type);
+        if (allowedTypes.includes(value))
+            return null;
+        return `type field has invalid value '${value}'; expected one of: ${allowedTypes.join(", ")}`;
+    }
+    /**
+     * Derive a URL-safe slug from a file path.
+     */
+    suggestSlug(filePath) {
+        return path
+            .basename(filePath, ".md")
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "");
+    }
     /**
      * Insert one or more lines into a markdown body at a safe location.
      *
@@ -401,30 +492,41 @@ export class BaseLinter {
         const issues = [];
         let currentRaw = ctx.raw;
         let modified = false;
+        // M8: Parse lint_skip from frontmatter for per-file rule suppression.
+        // Accept both an array (`lint_skip: [missing-ref, stale-path]`) and a
+        // single scalar (`lint_skip: missing-ref`). Non-string entries are coerced
+        // and trimmed so loosely-typed YAML still gates correctly.
+        const rawLintSkip = ctx.data?.lint_skip;
+        const lintSkip = (Array.isArray(rawLintSkip) ? rawLintSkip : rawLintSkip != null ? [rawLintSkip] : [])
+            .map((v) => String(v).trim())
+            .filter(Boolean);
+        const shouldRun = (issueType) => !lintSkip.includes(issueType);
         // ── 1. unquoted-colon ──────────────────────────────────────────────────
-        const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
-        if (unquotedColonDetail) {
-            if (ctx.fix) {
-                currentRaw = fixUnquotedColon(currentRaw);
-                modified = true;
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "unquoted-colon",
-                    detail: unquotedColonDetail,
-                    fixed: true,
-                });
-            }
-            else {
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "unquoted-colon",
-                    detail: unquotedColonDetail,
-                    fixed: false,
-                });
+        if (shouldRun("unquoted-colon")) {
+            const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
+            if (unquotedColonDetail) {
+                if (ctx.fix) {
+                    currentRaw = fixUnquotedColon(currentRaw);
+                    modified = true;
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "unquoted-colon",
+                        detail: unquotedColonDetail,
+                        fixed: true,
+                    });
+                }
+                else {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "unquoted-colon",
+                        detail: unquotedColonDetail,
+                        fixed: false,
+                    });
+                }
             }
-        }
+        } // end shouldRun("unquoted-colon")
         // ── 2. missing-updated ─────────────────────────────────────────────────
-        if (checkMissingUpdated(ctx.data, ctx.frontmatter)) {
+        if (shouldRun("missing-updated") && checkMissingUpdated(ctx.data, ctx.frontmatter)) {
             if (ctx.fix) {
                 let mtime;
                 try {
@@ -457,14 +559,23 @@ export class BaseLinter {
             ctx.raw = currentRaw;
         }
         // ── 3. stale-path ──────────────────────────────────────────────────────
-        const stalePathMatch = checkStalePath(ctx.body);
-        if (stalePathMatch) {
-            issues.push({
-                file: ctx.relPath,
-                issue: "stale-path",
-                detail: `nonexistent path: ${stalePathMatch}`,
-                fixed: false,
-            });
+        // M3: checkStalePath returns all stale matches; push one issue per path.
+        // M4: Also scan ctx.frontmatter for stale paths (absolute paths in frontmatter).
+        if (shouldRun("stale-path")) {
+            const staleInBody = checkStalePath(ctx.body);
+            const staleInFrontmatter = ctx.frontmatter ? checkStalePath(ctx.frontmatter) : [];
+            for (const candidate of [...staleInBody, ...staleInFrontmatter]) {
+                // M4: Suggest portable replacement when path is under stashRoot.
+                const portableHint = candidate.startsWith(ctx.stashRoot)
+                    ? ` (portable form: $AKM_STASH_DIR${candidate.slice(ctx.stashRoot.length)})`
+                    : "";
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "stale-path",
+                    detail: `nonexistent path: ${candidate}${portableHint}`,
+                    fixed: false,
+                });
+            }
         }
         // ── 4. missing-ref ─────────────────────────────────────────────────────
         // Carve-out for assets that declare an explicit `refs:` array in
@@ -481,16 +592,18 @@ export class BaseLinter {
         // still run `checkMissingRefs` against the array itself to catch
         // refs that were valid at capture time but later removed from the
         // stash.
-        const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
-        const refSource = explicitRefs !== null ? explicitRefs.join("\n") : ctx.body;
-        const missingRefs = checkMissingRefs(refSource, ctx.stashRoot, ctx.extraStashRoots);
-        for (const { ref, resolvedRelPath } of missingRefs) {
-            issues.push({
-                file: ctx.relPath,
-                issue: "missing-ref",
-                detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
-                fixed: false,
-            });
+        if (shouldRun("missing-ref")) {
+            const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
+            const refSource = explicitRefs !== null ? explicitRefs.join("\n") : ctx.body;
+            const missingRefs = checkMissingRefs(refSource, ctx.stashRoot, ctx.extraStashRoots);
+            for (const { ref, resolvedRelPath } of missingRefs) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "missing-ref",
+                    detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
+                    fixed: false,
+                });
+            }
         }
         return issues;
     }

package/dist/commands/lint/command-linter.js

@@ -1,22 +1,25 @@
 // 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 path from "node:path";
 import { BaseLinter } from "./base-linter.js";
+/** Valid values for the `type` field in command frontmatter. */
+const VALID_COMMAND_TYPES = ["command"];
 /**
  * Linter for `commands/` assets.
  *
- * Extra check beyond base:
+ * Extra checks beyond base:
  *   - `missing-name-or-type`: frontmatter exists but `name` or `type` field is
  *     absent. Not auto-fixable; detail includes a suggested slug.
+ *   - `missing-name-or-type` (invalid value): `type` is present but not a
+ *     recognised command type value.
  */
 export class CommandLinter extends BaseLinter {
     types = ["commands"];
     lint(ctx) {
         const issues = this.runBaseChecks(ctx);
-        const missingFieldDetail = this.#checkMissingNameOrType(ctx.data, ctx.frontmatter);
+        const missingFieldDetail = this.checkMissingNameOrType(ctx.data, ctx.frontmatter);
         if (missingFieldDetail) {
-            const slug = this.#suggestSlug(ctx.filePath);
+            const slug = this.suggestSlug(ctx.filePath);
             issues.push({
                 file: ctx.relPath,
                 issue: "missing-name-or-type",
@@ -24,26 +27,18 @@ export class CommandLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        else {
+            // Only validate the value when the field is actually present.
+            const invalidTypeDetail = this.checkInvalidTypeValue(ctx.data, VALID_COMMAND_TYPES);
+            if (invalidTypeDetail) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "missing-name-or-type",
+                    detail: invalidTypeDetail,
+                    fixed: false,
+                });
+            }
+        }
         return issues;
     }
-    #checkMissingNameOrType(data, frontmatterText) {
-        if (!frontmatterText)
-            return null;
-        const missingFields = [];
-        if (!("name" in data) || !data.name)
-            missingFields.push("name");
-        if (!("type" in data) || !data.type)
-            missingFields.push("type");
-        if (missingFields.length === 0)
-            return null;
-        return `missing fields: ${missingFields.join(", ")}`;
-    }
-    #suggestSlug(filePath) {
-        return path
-            .basename(filePath, ".md")
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-")
-            .replace(/-+/g, "-")
-            .replace(/^-|-$/g, "");
-    }
 }

package/dist/commands/lint/env-key-rules.js

@@ -24,6 +24,7 @@
  *   where the operator legitimately wants to set their editor — accept the
  *   FP and bypass with `--allow-insecure` after review.
  */
+import fs from "node:fs";
 import { listKeys } from "../env/env.js";
 // ── Dangerous key set ─────────────────────────────────────────────────────────
 export const DANGEROUS_VAULT_KEYS = new Set([
@@ -122,16 +123,48 @@ export function isDangerousVaultKey(key) {
  * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
  *                   the finding message.
  */
+/** Suppression comment token checked case-insensitively on the preceding non-empty line. */
+const SUPPRESSION_COMMENT = "# akm-lint-ok: dangerous-vault-key";
+/**
+ * Returns the set of keys suppressed by an inline `# akm-lint-ok: dangerous-vault-key`
+ * comment on the line immediately preceding the key assignment in the `.env` file.
+ */
+function collectSuppressedKeys(vaultPath) {
+    const suppressed = new Set();
+    let raw;
+    try {
+        raw = fs.readFileSync(vaultPath, "utf8");
+    }
+    catch {
+        return suppressed;
+    }
+    const lines = raw.split(/\r?\n/);
+    let prevNonEmpty = "";
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        const keyMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (keyMatch && prevNonEmpty.toLowerCase() === SUPPRESSION_COMMENT) {
+            suppressed.add(keyMatch[1]);
+        }
+        prevNonEmpty = trimmed;
+    }
+    return suppressed;
+}
 export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
     const { keys } = listKeys(vaultPath);
+    const suppressed = collectSuppressedKeys(vaultPath);
     const issues = [];
     for (const key of keys) {
         if (!isDangerousVaultKey(key))
             continue;
+        if (suppressed.has(key))
+            continue;
         issues.push({
             file: relPath,
             issue: "dangerous-vault-key",
-            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${vaultRef}. Review this file before running \`akm env run\` commands against untrusted stashes.`,
+            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${vaultRef}. Review this file before running \`akm env run\` commands against untrusted stashes. (suppress with: ${SUPPRESSION_COMMENT} on previous line)`,
             fixed: false,
         });
     }

package/dist/commands/lint/index.js

@@ -85,7 +85,8 @@ export function akmLint(options = {}) {
     const fix = options.fix ?? false;
     const fixed = [];
     const flagged = [];
-    for (const subdir of STASH_SUBDIRS) {
+    const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
+    for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
         // Tasks are .yml files; everything else is .md
         const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath);
@@ -97,7 +98,9 @@ export function akmLint(options = {}) {
                 if (entry.isDirectory()) {
                     const subdirIssues = linter.lintDirectory(path.join(dirPath, entry.name), stashRoot);
                     for (const issue of subdirIssues) {
-                        if (issue.fixed) {
+                        // Tristate-safe: only `true` counts as fixed; `false` and "failed"
+                        // are both flagged.
+                        if (issue.fixed === true) {
                             fixed.push(issue);
                         }
                         else {
@@ -108,6 +111,9 @@ export function akmLint(options = {}) {
             }
         }
         for (const filePath of files) {
+            // Skip registry-cached read-only files — --fix must not mutate them.
+            if (filePath.includes("/.cache/") || filePath.includes("/registry/"))
+                continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;
             try {
@@ -142,10 +148,11 @@ export function akmLint(options = {}) {
                     fileDeleted = true;
                     fixed.push(issue);
                 }
-                else if (issue.fixed) {
+                else if (issue.fixed === true) {
                     fixed.push(issue);
                 }
                 else {
+                    // fixed === false (not fixable / no fix requested) or "failed" (fix attempted but threw)
                     flagged.push(issue);
                 }
             }
@@ -159,16 +166,26 @@ export function akmLint(options = {}) {
     // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
     for (const root of envRoots) {
-        const dir = path.join(root, "env");
-        if (!fs.existsSync(dir))
-            continue;
-        for (const envPath of collectEnvFiles(dir)) {
-            const baseName = path.basename(envPath, ".env");
-            // "default" (or empty) maps to ".env" → env:default
-            const ref = baseName === "" ? "env:default" : `env:${baseName}`;
-            const relPath = path.relative(root, envPath);
-            for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
-                flagged.push(issue);
+        // The `env` assets live under `env/` (ref prefix `env:`); whole-file
+        // `secret` assets live under `secrets/` (canonical ref prefix `secret:`,
+        // singular). Map the scan directory to its canonical ref prefix so the
+        // finding's `Ref:` field matches what `akm show`/`akm secret` accept.
+        for (const { scanSubdir, refPrefix } of [
+            { scanSubdir: "env", refPrefix: "env" },
+            { scanSubdir: "secrets", refPrefix: "secret" },
+        ]) {
+            const dir = path.join(root, scanSubdir);
+            if (!fs.existsSync(dir))
+                continue;
+            for (const envPath of collectEnvFiles(dir)) {
+                const baseName = path.basename(envPath, ".env");
+                // A dotfile literally named `.env` has an empty baseName — use the full
+                // basename so it doesn't collide with `default.env` → refPrefix:default.
+                const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+                const relPath = path.relative(root, envPath);
+                for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                    flagged.push(issue);
+                }
             }
         }
     }

package/dist/commands/lint/memory-linter.js

@@ -33,7 +33,7 @@ export class MemoryLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "orphaned-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 // Signal caller to skip remaining checks via a sentinel issue

package/dist/commands/lint/registry.js

@@ -18,15 +18,18 @@ const LINTERS = [
     new KnowledgeLinter(),
     new SkillLinter(),
     new TaskLinter(),
-    new DefaultLinter(),
 ];
+// Single shared DefaultLinter instance — used both as the explicit "lessons"
+// handler and as the fallback for any unrecognised asset type.
+const DEFAULT_LINTER = new DefaultLinter();
 const LINTER_MAP = new Map();
 for (const linter of LINTERS) {
     for (const t of linter.types) {
         LINTER_MAP.set(t, linter);
     }
 }
-const DEFAULT_LINTER = new DefaultLinter();
+// Register "lessons" explicitly so there is only one DefaultLinter instance.
+LINTER_MAP.set("lessons", DEFAULT_LINTER);
 /**
  * Return the appropriate linter for the given stash subdirectory name.
  * Falls back to `DefaultLinter` for unknown types.

package/dist/commands/lint/task-linter.js

@@ -28,9 +28,9 @@ export class TaskLinter extends BaseLinter {
         if (!("schedule" in ctx.data) || typeof ctx.data.schedule !== "string" || ctx.data.schedule.trim() === "") {
             missing.push("schedule");
         }
-        // enabled: must be present (boolean — value of false is valid)
-        if (!("enabled" in ctx.data)) {
-            missing.push("enabled");
+        // enabled: must be present AND a boolean (value of false is valid, but "yes" / 1 are not)
+        if (!("enabled" in ctx.data) || typeof ctx.data.enabled !== "boolean") {
+            missing.push("enabled (must be a boolean)");
         }
         // At least one of: prompt, workflow, or command
         const hasTarget = "prompt" in ctx.data || "workflow" in ctx.data || "command" in ctx.data;

package/dist/commands/lint/workflow-linter.js

@@ -2,6 +2,7 @@
 // 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 fs from "node:fs";
+import { parseWorkflow } from "../../workflows/parser.js";
 import { BaseLinter } from "./base-linter.js";
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /**
@@ -32,7 +33,7 @@ export class WorkflowLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "placeholder-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 return issues;
@@ -44,6 +45,30 @@ export class WorkflowLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        const isReadOnly = ctx.filePath.includes("/.cache/") || ctx.filePath.includes("/registry/");
+        if (!isReadOnly) {
+            try {
+                const result = parseWorkflow(ctx.raw, { path: ctx.filePath });
+                if (!result.ok) {
+                    for (const err of result.errors ?? []) {
+                        issues.push({
+                            file: ctx.relPath,
+                            issue: "invalid-workflow-structure",
+                            detail: err.message ?? String(err),
+                            fixed: false,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "invalid-workflow-structure",
+                    detail: `workflow parser error: ${e instanceof Error ? e.message : String(e)}`,
+                    fixed: false,
+                });
+            }
+        }
         return issues;
     }
     #checkPlaceholderStub(body) {