akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/workflow-cli.js

@@ -4,8 +4,8 @@
 /**
  * `akm workflow` command family. `run` is the canonical start/resume/execute
  * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
- * Workflows are markdown-only; authoring uses `create --print` and validation
- * uses `akm lint --type workflows`.
+ * `create --print` emits Markdown; execution accepts peer `.md` and
+ * GitHub-shaped `.yml` workflow sources. Validate with `akm lint --type workflows`.
  */
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";

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

@@ -232,6 +232,9 @@ export const agentSkillsAdapter = {
     extensions: [".md"],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        return [{ path: path.join(c.root, conceptId, SKILL_MANIFEST), conceptId }];
+    },
     /** A skill places to `<name>/SKILL.md`; the conceptId IS the package directory (spec §4.5). */
     placeNew(c, conceptId) {
         return path.join(c.root, conceptId, SKILL_MANIFEST);

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

@@ -39,9 +39,10 @@
  * conceptId = `<stash-subdir>/<canonical-name>` — the placement stash-subdir
  * (`stashDirFor(type)`) followed by the winning type's canonical name
  * (`deriveCanonicalAssetNameFromStashRoot`: skill = its dir, script keeps its
- * extension, markdown strips `.md`, env/task strip their ext, secret/session
- * keep the natural path). For markdown types this IS the OKF concept ID
- * (path − `.md`); it is the same spelling {@link placeNew} consumes, so
+ * extension, Markdown strips `.md`, workflow strips its peer `.md`/`.yml`
+ * extension, env/task strip their ext, and secret/session keep the natural
+ * path). For Markdown types this IS the OKF concept ID (path − `.md`); it is
+ * the same spelling {@link placeNew} consumes, so
  * recognize/place share one identity (D-R2 resolved the earlier split). The
  * `type` is carried separately on `IndexDocument.type`, per §0.2 (type ≠
  * identity), and `entry.name` keeps the BARE canonical name for FTS parity.
@@ -81,11 +82,11 @@
 import fs from "node:fs";
 import path from "node:path";
 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";
-import { perTypeValidateChecks, skillDirectoryDiagnostics } from "./akm-lint.js";
+import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
+import { recognizeMatch, recognizePathCandidateMatches } from "../recognize-match.js";
+import { perTypeValidateChecks, skillDirectoryDiagnostics, workflowYamlSourceDiagnostics } from "./akm-lint.js";
 import { applyFoldedMetadata, foldRecognizedMetadata } from "./akm-metadata.js";
 import { hashContent, runBaseValidateChecks } from "./shared.js";
 // `recognizeMatch` + the builtin matcher list moved to the cycle-free leaf
@@ -178,7 +179,6 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "whenToUse",
     "toc",
     "parameters",
-    "bodyOpening",
     "source",
     "category",
     "supersededBy",
@@ -221,6 +221,8 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.description = entry.description;
     if (entry.tags !== undefined)
         doc.tags = entry.tags;
+    if (entry.content !== undefined)
+        doc.content = entry.content;
     if (entry.aliases !== undefined)
         doc.aliases = entry.aliases;
     if (entry.searchHints !== undefined)
@@ -243,6 +245,21 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.derivedFrom = entry.derivedFrom;
     return doc;
 }
+function conceptIdForRecognizedType(root, filePath, type) {
+    const canonicalName = deriveCanonicalAssetNameFromStashRoot(type, root, filePath);
+    if (canonicalName === undefined)
+        return undefined;
+    const stashDir = stashDirFor(type);
+    return stashDir !== undefined ? `${stashDir}/${canonicalName}` : canonicalName;
+}
+function recognizePathCandidates(c, file) {
+    if (isReservedFileName(file.fileName) || akmStashAbstains(c.root, file.absPath))
+        return [];
+    return recognizePathCandidateMatches(file).flatMap((match) => {
+        const conceptId = conceptIdForRecognizedType(c.root, file.absPath, match.type);
+        return conceptId === undefined ? [] : [conceptId];
+    });
+}
 function recognize(c, file) {
     // D-R6 (spec §5.1): `index.md` / `log.md` are OKF reserved structural files at
     // every depth — never items. Excluded BEFORE classification so a directory
@@ -259,20 +276,20 @@ function recognize(c, file) {
         return null;
     // 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);
-    if (derived === undefined)
+    const conceptId = conceptIdForRecognizedType(c.root, file.absPath, match.type);
+    if (conceptId === undefined)
         return null;
-    const canonicalName = derived;
+    const stashDir = stashDirFor(match.type);
+    const canonicalName = stashDir !== undefined ? conceptId.slice(stashDir.length + 1) : conceptId;
     // 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
+    // (ref-grammar decision D-R2): the same form `placeNew` consumes; Markdown
+    // types use the OKF concept ID (path − .md), while workflows strip either
+    // peer source extension. Both branches feed a
     // BARE canonicalName (the abstain fallback is the basename, above), so the
     // stash-subdir is prefixed uniformly — a flat `skills/x.md` yields
     // `skills/x`, never the un-prefixed `x` or the double-prefixed
     // `skills/skills/x`. `entry.name` below keeps the BARE canonical name —
     // identity ≠ search text.
-    const stashDir = stashDirFor(match.type);
-    const conceptId = stashDir !== undefined ? `${stashDir}/${canonicalName}` : canonicalName;
     const dirPath = path.dirname(file.absPath);
     // Chunk 5 M-b: recognize now carries the FULL index-time metadata surface
     // (spec §2/§3), reproducing `buildEntryFromFile`'s flat-walk metadata
@@ -307,6 +324,30 @@ function recognize(c, file) {
         type: match.type,
     }, match.renderer);
 }
+/** Render AKM-native command/agent Markdown into the shared execution source. */
+function renderExecutionSource(c, file) {
+    const document = recognize(c, file);
+    if (document?.type !== "command" && document?.type !== "agent")
+        return null;
+    if (!document.ref)
+        return null;
+    const raw = file.content();
+    return renderMarkdownExecutionSource({
+        kind: document.type === "command" ? "command" : "persona",
+        raw,
+        identity: {
+            ref: document.ref,
+            bundle: c.id,
+            adapter: "akm",
+            file: file.relPath,
+        },
+        defaults: (data) => executionDefaultsFromFrontmatter(data, {
+            kind: document.type === "command" ? "command" : "persona",
+            allowTopLevelEngine: true,
+            toolsKeys: ["tools"],
+        }),
+    });
+}
 /**
  * A read-only {@link FileContext} backed by an OVERLAY string (a pending
  * change's content) instead of the live filesystem — the `validate` contract
@@ -357,10 +398,9 @@ function buildOverlayContext(root, relPathInput, raw) {
  *
  * Per change (non-delete, readable): the `type` is recovered by running the
  * SAME sync matcher arbitration ({@link recognizeMatch}) over an OVERLAY
- * FileContext ({@link buildOverlayContext}) — no live-FS read. `task` files are
- * parsed as pure YAML (mirroring `lint/index.ts`'s `subdir === "tasks"` branch)
- * so the TaskLinter's field checks see real data and `missing-updated` never
- * fires (frontmatter is `null`); everything else parses via `parseFrontmatter`.
+ * FileContext ({@link buildOverlayContext}) — no live-FS read. `task` files
+ * keep raw YAML for the canonical task-v3 parser and use no frontmatter;
+ * everything else parses via `parseFrontmatter`.
  * Base checks (shared) then the per-type extra checks run; a `skills/` directory
  * pass reproduces `SkillLinter.lintDirectory` across the change set.
  */
@@ -376,23 +416,17 @@ async function validate(c, changes, ctx) {
         const overlay = buildOverlayContext(c.root, change.path, raw);
         const match = recognizeMatch(overlay);
         const type = match?.type;
-        // Parse strategy per `lint/index.ts`: `task` → pure YAML (frontmatter null),
-        // everything else → `parseFrontmatter`.
+        // A complete GitHub-shaped `on` + `jobs` document is workflow-owned. It
+        // never flows through task-v3 parsing or Markdown base/frontmatter checks.
+        if (type === "workflow" && overlay.ext === ".yml") {
+            diagnostics.push(...workflowYamlSourceDiagnostics(change.path, raw, change.path, c.root).errors);
+            continue;
+        }
+        // Task parsing belongs to perTypeValidateChecks' canonical v3 parser. Base
+        // checks need only a frontmatter-free placeholder here.
         let parsed;
         if (type === "task") {
-            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,
-                });
-            }
-            parsed = { data: task.data, content: raw, frontmatter: null };
+            parsed = { data: {}, content: raw, frontmatter: null };
         }
         else {
             const p = parseFrontmatter(raw);
@@ -408,6 +442,7 @@ async function validate(c, changes, ctx) {
             body: parsed.content,
             ext: overlay.ext,
             ctx,
+            workspaceRoot: c.root,
         })));
         diagnostics.push(...(await skillDirectoryDiagnostics(change.path, seenSkillDirs, ctx)));
     }
@@ -417,8 +452,9 @@ 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` (task YAML), `.env` (env
-    // files), and the 16 SCRIPT_EXTENSIONS. This is a
+    // `.md` (Markdown types + workflow peer), `.yml` (task and workflow YAML),
+    // `.yaml` (task near-miss diagnostics), `.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.
@@ -445,7 +481,21 @@ export const akmAdapter = {
         ".kts",
     ],
     recognize,
+    recognizePathCandidates,
+    renderExecutionSource,
     validate,
+    readCandidates(c, conceptId) {
+        const posix = conceptId.replace(/\\/g, "/");
+        const slash = posix.indexOf("/");
+        if (slash <= 0)
+            return [{ path: path.join(c.root, `${posix}.md`), conceptId: posix }];
+        const head = posix.slice(0, slash);
+        const rest = posix.slice(slash + 1);
+        const type = stashDirToType(head);
+        return type === undefined || rest.length === 0
+            ? []
+            : [{ path: assetPathForName(type, path.join(c.root, head), rest), conceptId: posix }];
+    },
     /**
      * Type-driven placement (§5.1), reproducing `path-resolver.ts#buildDiskCandidates`:
      * the primary candidate is

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

@@ -40,8 +40,8 @@
  * ── Cycle-safety (chunk-2 ratchet, baseline 18) ──
  *
  * 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 `isDangerousEnvKey`
+ * cycle. It VALUE-imports the one `compileWorkflowSource` frontend 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
@@ -52,9 +52,9 @@
  */
 import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
-import { isPresentTarget, taskFieldProblems } from "../../../tasks/schema.js";
+import { parseTaskV3Yaml, taskV3SourceErrorDetail } from "../../../tasks/source-v3.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
-import { parseWorkflow } from "../../../workflows/parser.js";
+import { compileWorkflowSource } from "../../../workflows/source-ir/compile.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"]);
@@ -197,11 +197,8 @@ const AKM_SKILL_DIRS = new Set(["skills"]);
  * (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).
+ * `skillDirs` defaults to the akm-native `skills/` placement dir. Tool-dir
+ * adapters pass their own canonical placement directory.
  */
 export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs = AKM_SKILL_DIRS) {
     const segments = relPath
@@ -225,7 +222,7 @@ export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs =
  * routes through `ctx`.
  */
 export async function perTypeValidateChecks(args) {
-    const { type, relPath, raw, data, frontmatter, body, ext, ctx } = args;
+    const { type, relPath, raw, data, frontmatter, body, ext, ctx, workspaceRoot } = args;
     switch (type) {
         case "command":
             return nameOrTypeDiagnostics(relPath, data, frontmatter, ["command"]);
@@ -234,9 +231,9 @@ export async function perTypeValidateChecks(args) {
         case "fact":
             return factDiagnostics(relPath, data);
         case "task":
-            return taskDiagnostics(relPath, data);
+            return taskDiagnostics(relPath, raw, workspaceRoot);
         case "workflow":
-            // Unified workflows are markdown-only; other extensions are not a lint path.
+            // Markdown lint handles `.md`; peer GitHub-shaped `.yml` sources enter through the workflow source adapter.
             return ext === ".md" ? workflowDiagnostics(relPath, raw, body) : [];
         case "memory":
             return memoryDiagnostics(relPath, data, body, ctx);
@@ -274,33 +271,29 @@ export function factDiagnostics(relPath, data) {
     return [];
 }
 /**
- * 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.
+ * Task validation has one semantic owner: the strict task-v3 source parser.
+ * Keeping raw YAML at this boundary preserves duplicate-key, alias/tag,
+ * source-location, descriptor, resource-bound, and migration-hint behavior.
  */
-export function taskDiagnostics(relPath, data) {
-    if (data === null || Object.keys(data).length === 0)
+export function taskDiagnostics(relPath, raw, workspaceRoot) {
+    try {
+        parseTaskV3Yaml({
+            filePath: relPath,
+            yaml: raw,
+            ...(workspaceRoot ? { workspaceRoot } : {}),
+        });
         return [];
-    const missing = taskFieldProblems(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) {
+    }
+    catch (cause) {
         return [
             {
                 file: relPath,
                 issue: "invalid-task-yaml",
-                detail: `missing required fields: ${missing.join(", ")}`,
+                detail: taskV3SourceErrorDetail(cause),
                 fixed: false,
             },
         ];
     }
-    return [];
 }
 /**
  * The first placeholder marker present in a workflow body, or `null`
@@ -313,11 +306,10 @@ export function matchWorkflowPlaceholder(body) {
 }
 /**
  * WorkflowLinter's `invalid-workflow-structure` check (`workflow-linter.ts:48-77`):
- * 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.
+ * the ERROR half of {@link workflowFrontendDiagnostics}, for the read-only
+ * adapter `validate` path. A caller that ALSO surfaces 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;
@@ -333,6 +325,30 @@ export function workflowStructureDiagnostics(relPath, raw, parsePath) {
 function lineOf(err) {
     return typeof err.line === "number" && Number.isFinite(err.line) && err.line > 0 ? { line: err.line } : {};
 }
+/**
+ * Compile one peer GitHub-shaped `.yml` source through the shared source-IR
+ * frontend. YAML has no Markdown frontmatter/base/stub pass and currently
+ * emits fatal source diagnostics only; keeping the same two-channel result
+ * shape lets the ordinary sweep and both workflow adapters route it exactly
+ * like the established Markdown frontend without inventing another parser.
+ */
+export function workflowYamlSourceDiagnostics(relPath, raw, parsePath, workspaceRoot) {
+    if (parsePath.includes("/.cache/") || parsePath.includes("/registry/"))
+        return { errors: [], warnings: [] };
+    const compiled = compileWorkflowSource(raw, { path: parsePath, workspaceRoot });
+    if (compiled.ok)
+        return { errors: [], warnings: [] };
+    return {
+        errors: compiled.errors.map((error) => ({
+            file: relPath,
+            issue: "invalid-workflow-structure",
+            detail: error.message,
+            fixed: false,
+            ...lineOf(error),
+        })),
+        warnings: [],
+    };
+}
 /**
  * ONE parse+compile of a workflow through the unified frontend, returning both
  * halves of what it produces: fatal `invalid-workflow-structure` findings, and
@@ -340,9 +356,8 @@ function lineOf(err) {
  * 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).
+ * `parsePath` is the source identity handed to `compileWorkflowSource` (the
+ * adapter passes the change relPath; the CLI passes the absolute filePath).
  *
  * A caller that surfaces BOTH halves must call this once and route the result
  * itself. The frontend is expensive — instruction bodies reach
@@ -356,7 +371,7 @@ export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
     const errors = [];
     const warnings = [];
     try {
-        const result = parseWorkflow(raw, { path: parsePath });
+        const result = compileWorkflowSource(raw, { path: parsePath });
         if (!result.ok) {
             for (const err of result.errors ?? []) {
                 errors.push({
@@ -369,7 +384,7 @@ export function workflowFrontendDiagnostics(relPath, raw, parsePath) {
             }
             return { errors, warnings };
         }
-        const compiled = compileWorkflowPlan(result.document, path.basename(parsePath, path.extname(parsePath)));
+        const compiled = compileWorkflowPlan(result.ir, path.basename(parsePath, path.extname(parsePath)));
         if (!compiled.ok) {
             for (const err of compiled.errors) {
                 errors.push({

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

@@ -14,7 +14,8 @@
  *     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` (1): workflow-document-metadata (workflow-md).
+ *   - `workflows/renderer.ts` (1): workflow-document-metadata (the historical
+ *     `workflow-md` renderer id now presents both peer workflow sources).
  *
  * ── Cycle-safety (chunk-2 ratchet, baseline 18) ──
  *
@@ -22,9 +23,9 @@
  * that file's header), so this leaf can never gain an inbound edge from a cycle
  * participant and therefore can never JOIN a cycle. It VALUE-imports the pure
  * parsers each contributor already uses so the fold cannot drift from them:
- * `parseFrontmatter`, `parseMarkdownToc`, `parseWorkflow`, `parseWorkflowProgram`,
- * `projectProgramParameters`/`programStepInstructions`, and `listKeys`
- * (env key-names). `output/renderers.ts` / `workflows/renderer.ts` are the
+ * `parseFrontmatter`, `parseMarkdownToc`, the peer-source
+ * `compileWorkflowSource` frontend/projection, and env key-name scanning.
+ * `output/renderers.ts` / `workflows/renderer.ts` are the
  * cycle-sensitive modules whose contributor bodies live in this port — their
  * ONE non-importable helper (`metadata.ts#extractDescriptionFromComments`, a
  * heavy cycle-participant module) is copied verbatim below as
@@ -46,17 +47,17 @@
  *
  * Every contributor that reads/parses content is reproduced with the SAME
  * try/catch tolerance it has today (toc/memory/session/fact/task swallow parse
- * errors). The two workflow contributors throw-to-skip in today's pipeline (a
- * broken workflow is dropped by the metadata drain); here the parse is wrapped
+ * errors). Workflow source compilation fails closed in the drain (a broken
+ * workflow is dropped); here the compile/projection is wrapped
  * so a broken workflow yields no folded metadata instead of throwing out of the
  * synchronous `recognize` — the drop-the-entry behavior is an index-drain
  * concern (Chunk 4/5), not recognition's. On the valid Chunk-0b fixture this
  * distinction never triggers.
  */
-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 { scanEnvKeyNames } from "../../../commands/env/env.js";
+import { parseTaskV3Yaml } from "../../../tasks/source-v3.js";
+import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
+import { sourceStepInstructions } from "../../../workflows/source-ir/program.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { parseMarkdownToc } from "../../asset/markdown.js";
 import { nonEmptyString } from "./shared.js";
@@ -67,14 +68,7 @@ import { nonEmptyString } from "./shared.js";
  * others are imported). Reads a leading JSDoc block or hash-comment run from the
  * script file; returns `null` on read/parse miss.
  */
-function extractDescriptionFromComments(filePath) {
-    let content;
-    try {
-        content = fs.readFileSync(filePath, "utf8");
-    }
-    catch {
-        return null;
-    }
+function extractDescriptionFromComments(content) {
     const lines = content.split(/\r?\n/).slice(0, 50);
     const blockStart = lines.findIndex((l) => /^\s*\/\*\*/.test(l));
     if (blockStart >= 0) {
@@ -210,7 +204,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         case "script-source": {
             if (file.ext === ".md")
                 return out;
-            const commentDesc = extractDescriptionFromComments(file.absPath);
+            const commentDesc = extractDescriptionFromComments(file.content());
             if (commentDesc && !out.description) {
                 out.description = commentDesc;
                 out.source = "comments";
@@ -220,7 +214,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         }
         // ── env-file-metadata (env-file) ──
         case "env-file": {
-            const { keys } = listKeys(file.absPath);
+            const keys = scanEnvKeyNames(file.content());
             if (keys.length > 0)
                 out.searchHints = keys;
             out.tags = Array.from(new Set([...(out.tags ?? []), "env", "secrets"]));
@@ -235,18 +229,25 @@ export function foldRecognizedMetadata(rendererName, file) {
         case "task-yaml": {
             out.tags = Array.from(new Set([...(out.tags ?? []), "task", "scheduled"]));
             try {
-                const doc = parseYaml(file.content());
-                const data = doc && typeof doc === "object" && !Array.isArray(doc) ? doc : {};
+                const task = parseTaskV3Yaml({ yaml: file.content(), filePath: file.absPath, workspaceRoot: file.stashRoot });
                 const hints = new Set();
-                const schedule = nonEmptyString(data.schedule);
-                if (schedule)
-                    hints.add(`schedule:${schedule}`);
-                const workflow = nonEmptyString(data.workflow);
-                if (workflow)
-                    hints.add(`workflow:${workflow}`);
-                const prompt = nonEmptyString(data.prompt);
-                if (prompt)
-                    hints.add(`prompt:${prompt}`);
+                for (const binding of task.triggers.schedules)
+                    hints.add(`schedule:${binding.cron}`);
+                if (task.target.kind === "uses") {
+                    if (task.target.uses.kind === "workflow")
+                        hints.add(`workflow:${task.target.uses.ref}`);
+                    else if (task.target.uses.kind === "command")
+                        hints.add(`prompt:${task.target.uses.ref}`);
+                    else if (task.target.command?.kind === "inline")
+                        hints.add(`prompt:${task.target.command.content}`);
+                    else if (task.target.command?.kind === "stored")
+                        hints.add(`prompt:${task.target.command.ref}`);
+                    else
+                        hints.add(`uses:${task.target.uses.ref}`);
+                }
+                else {
+                    hints.add(`run:${task.target.run}`);
+                }
                 finalizeHints(out, hints);
             }
             catch {
@@ -301,26 +302,25 @@ export function foldRecognizedMetadata(rendererName, file) {
             }
             return out;
         }
-        // ── workflow-document-metadata (workflow-md) ──
+        // ── workflow-document-metadata (historical renderer id `workflow-md`, peer sources) ──
         case "workflow-md": {
             try {
-                const result = parseWorkflow(file.content(), { path: file.relPath });
+                const result = compileWorkflowSource(file.content(), { path: file.relPath, workspaceRoot: file.stashRoot });
                 if (!result.ok)
                     return out;
-                const doc = result.document;
+                const sourceIr = result.ir;
                 const hints = new Set();
-                if (doc.preamble)
-                    hints.add(doc.preamble);
-                for (const step of doc.steps) {
+                if (sourceIr.preamble)
+                    hints.add(sourceIr.preamble);
+                for (const step of sourceIr.jobs.flatMap((job) => job.steps)) {
                     hints.add(step.id);
-                    if (step.instructions)
-                        hints.add(step.instructions.text);
-                    if (step.gateRubric)
-                        hints.add(step.gateRubric.text);
+                    hints.add(sourceStepInstructions(step));
+                    if (step.gate?.rubric)
+                        hints.add(step.gate.rubric);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
-                if (doc.params) {
-                    const parameters = Object.entries(doc.params).map(([name, schema]) => {
+                if (sourceIr.params) {
+                    const parameters = Object.entries(sourceIr.params).map(([name, schema]) => {
                         const description = schema.description;
                         return { name, ...(typeof description === "string" && description ? { description } : {}) };
                     });
@@ -348,8 +348,8 @@ export function foldRecognizedMetadata(rendererName, file) {
  * Precedence, verified against every case in {@link foldRecognizedMetadata}:
  *  - description/source/confidence travel together and only when the entry has
  *    no description yet (contributors gate on `!entry.description`); a
- *    contributor that sets description WITHOUT source/confidence
- *    (workflow-program-yaml) leaves those untouched — mirrored by the
+ *    contributor that sets description WITHOUT source/confidence leaves those
+ *    untouched — mirrored by the
  *    `folded.source`/`folded.confidence` guards below;
  *  - tags UNION into the existing set (order-preserving Set dedup), matching the
  *    contributors' `Array.from(new Set([...entry.tags, ...added]))`;