akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/improve/triage.js

@@ -0,0 +1,93 @@
+// 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/.
+/**
+ * Default minimum total score a session must reach to PASS the gate. Tuned
+ * conservatively: a single real narrative-lesson session, or a procedurally
+ * dense session, clears it — but pure read-only Q&A does not. Config-overridable
+ * via `processes.extract.triage.minScore`.
+ */
+export const DEFAULT_TRIAGE_MIN_SCORE = 2;
+// Decision / outcome / error narrative markers. Case-insensitive, word-bounded.
+const MARKER_RE = /\b(error|failed|fix(?:ed)?|root cause|turns out|because|decided|instead|gotcha|workaround|regress(?:ed)?|broke|TIL)\b/i;
+// Edit / commit / file-write markers in tool event text.
+const EDIT_COMMIT_RE = /\b(Edit|Write|MultiEdit|git commit|diff)\b/i;
+// A substantive turn is an assistant or tool turn whose text is non-trivial.
+const SUBSTANTIVE_MIN_CHARS = 40;
+export function scoreSessionTriage(data, minScore, options) {
+    const events = data.events;
+    const total = events.length;
+    // (a) markers — count word-bounded marker hits across all event text, capped.
+    let markerHits = 0;
+    for (const e of events) {
+        if (MARKER_RE.test(e.text))
+            markerHits += 1;
+    }
+    // Each marker-bearing event contributes 1 point, capped at 2 (a single real
+    // narrative session clears the bar on markers alone).
+    const markers = Math.min(markerHits, 2);
+    // (b) toolDensity — bounded contribution from tool-use events.
+    let toolEvents = 0;
+    for (const e of events) {
+        if (e.role === "tool")
+            toolEvents += 1;
+    }
+    // 0.25 per tool event, capped at 1.5.
+    const toolDensity = Math.min(toolEvents * 0.25, 1.5);
+    // (c) editCommit — bounded contribution from edit/write/commit markers on
+    // events (filePath present, or text matching the edit/commit regex).
+    let editCommitEvents = 0;
+    for (const e of events) {
+        if (e.filePath || EDIT_COMMIT_RE.test(e.text))
+            editCommitEvents += 1;
+    }
+    // 0.25 per edit/commit event, capped at 1.5. Together with toolDensity a
+    // procedurally dense session reaches well above the default threshold.
+    const editCommit = Math.min(editCommitEvents * 0.25, 1.5);
+    // (d) substantiveRatio — scaled fraction of non-trivial assistant+tool turns.
+    let substantive = 0;
+    for (const e of events) {
+        if ((e.role === "assistant" || e.role === "tool") && e.text.length >= SUBSTANTIVE_MIN_CHARS) {
+            substantive += 1;
+        }
+    }
+    const ratio = total > 0 ? substantive / total : 0;
+    // Scale to a bounded [0,1] contribution.
+    const substantiveRatio = Math.min(ratio, 1);
+    const subscores = { markers, toolDensity, editCommit, substantiveRatio };
+    const score = markers + toolDensity + editCommit + substantiveRatio;
+    // Base gate: score must clear the floor.
+    let pass = score >= minScore;
+    // #641 procedural-aware floor (opt-in, DEFAULT OFF).
+    // When enabled, a session that clears the score gate must ALSO have at least
+    // one narrative marker (markers >= 1) OR meaningful edit/commit signal
+    // (editCommit >= 0.5). Pure read-only Q&A sessions that pass only via
+    // toolDensity + substantiveRatio are rejected as low-signal.
+    if (pass && options?.proceduralAwareFloor === true) {
+        const hasProceduralSignal = markers >= 1 || editCommit >= 0.5;
+        if (!hasProceduralSignal) {
+            pass = false;
+        }
+    }
+    return {
+        pass,
+        score,
+        subscores,
+        ...(pass ? {} : { reason: "low_signal" }),
+    };
+}
+/**
+ * Resolve the effective triage config from the extract process config. Mirrors
+ * the minContentChars / schemaSimilarity resolution style in akmExtract.
+ *
+ * Default-off: `enabled` is FALSE unless `triage.enabled === true`. `minScore`
+ * defaults to {@link DEFAULT_TRIAGE_MIN_SCORE}.
+ */
+export function resolveTriageConfig(extractProcess) {
+    const triage = extractProcess?.triage;
+    const enabled = triage?.enabled === true;
+    const minScore = typeof triage?.minScore === "number" ? triage.minScore : DEFAULT_TRIAGE_MIN_SCORE;
+    // #641: default-off — only true when explicitly set to true.
+    const proceduralAwareFloor = triage?.proceduralAwareFloor === true;
+    return { enabled, minScore, proceduralAwareFloor };
+}

package/dist/commands/lint/agent-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 agent frontmatter. */
+const VALID_AGENT_TYPES = ["agent"];
 /**
  * Linter for `agents/` 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 agent type value.
  */
 export class AgentLinter extends BaseLinter {
     types = ["agents"];
     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 AgentLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        else {
+            // Only validate the value when the field is actually present.
+            const invalidTypeDetail = this.checkInvalidTypeValue(ctx.data, VALID_AGENT_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/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([
@@ -95,6 +96,10 @@ export const DANGEROUS_VAULT_KEY_PATTERNS = [
         pattern: /^BASH_FUNC_/,
         reason: "Shellshock-class bash function injection (CVE-2014-6271)",
     },
+    {
+        pattern: /^GIT_CONFIG_/,
+        reason: "Git config injection through environment override variables",
+    },
 ];
 /**
  * Returns `true` if the given key name is dangerous — either by literal match
@@ -122,16 +127,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,
         });
     }