arkgate 4.2.1 → 4.4.0

package/bin/lib/agent-projection.mjs

@@ -0,0 +1,319 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/agentProjection.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/agent-projection.mjs). Zero Node I/O.
+ */
+
+export const ARK_AGENT_PROJECTION_SCHEMA_VERSION = '1.0';
+/** Begin marker for the managed projection region inside AGENTS.md (or equivalent). */
+export const AGENT_PROJECTION_BEGIN_MARKER = '<!-- arkgate:agent-projection:begin';
+/** End marker for the managed projection region. */
+export const AGENT_PROJECTION_END_MARKER = '<!-- arkgate:agent-projection:end -->';
+/**
+ * Non-enforcement label — must appear in every generated projection body.
+ * Agents and humans must not treat the projection as a pass/fail authority.
+ */
+export const AGENT_PROJECTION_NON_ENFORCEMENT_LABEL = 'This projection is **non-authoritative**. Enforcement is `ark-check` / host write hooks / required CI (`--strict-merge`), not AGENTS.md, skills, or this block.';
+/** Surfaces that actually enforce (closed vocabulary for meta + docs). */
+export const AGENT_PROJECTION_ENFORCEMENT_SURFACES = Object.freeze([
+    'ark-check',
+    'host-write-hooks',
+    'ci-strict-merge',
+]);
+/**
+ * High-signal public ruleIds for the compact catalog short list in the projection.
+ * Full catalog remains `docs/diagnostics.md` / `DIAGNOSTIC_CATALOG` (ACS02).
+ * Titles are supplied by Tooling from the catalog when available.
+ */
+export const DEFAULT_AGENT_PROJECTION_RULE_IDS = Object.freeze([
+    'LAYER_IMPORT_VIOLATION',
+    'LAYER_INTENT_REFERENCE_VIOLATION',
+    'CIRCULAR_DEPENDENCY',
+    'CAPABILITY_VIOLATION',
+    'RAW_EVENT_PUBLISH',
+    'ARKRULE_STRUCTURE',
+    'ATOMIC_PREFLIGHT_UNAVAILABLE',
+    'ANALYSIS_PARSE_INCOMPLETE',
+    'ARK_UNKNOWN',
+]);
+const BEGIN_LINE_RE = /<!--\s*arkgate:agent-projection:begin\b([^>]*)-->/i;
+const END_LINE_RE = /<!--\s*arkgate:agent-projection:end\s*-->/i;
+// Attribute values: alnum + common version/schema tokens only (avoid open char-class ranges).
+const VERSION_ATTR_RE = /\barkgateVersion=([A-Za-z0-9._+-]+)/i;
+const SCHEMA_ATTR_RE = /\bschema=([A-Za-z0-9._+-]+)/i;
+/** FNV-1a identity — portable, no Node crypto (same family as stableHash). */
+export function agentProjectionContentIdentity(body) {
+    const normalized = String(body ?? '').replace(/\r\n/g, '\n');
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < normalized.length; index += 1) {
+        hash ^= normalized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+function normalizeNewlines(text) {
+    return String(text ?? '').replace(/\r\n/g, '\n');
+}
+function ensureTrailingNewline(text) {
+    const normalized = normalizeNewlines(text);
+    return normalized.endsWith('\n') ? normalized : `${normalized}\n`;
+}
+function safeVersion(version) {
+    if (typeof version !== 'string' || version.trim().length === 0)
+        return 'unknown';
+    // Avoid breaking HTML comments / markdown with control chars.
+    return version.trim().replace(/[>\s]/g, '');
+}
+function resolveProfile(profile) {
+    return profile === 'compact' ? 'compact' : 'full';
+}
+/**
+ * Build the managed begin marker line (includes version + nonAuthoritative stamp).
+ */
+export function buildAgentProjectionBeginMarker(facts) {
+    const version = safeVersion(facts.arkgateVersion);
+    const schema = typeof facts.schemaVersion === 'string' && facts.schemaVersion.trim()
+        ? facts.schemaVersion.trim()
+        : ARK_AGENT_PROJECTION_SCHEMA_VERSION;
+    return `<!-- arkgate:agent-projection:begin schema=${schema} arkgateVersion=${version} nonAuthoritative=true -->`;
+}
+/**
+ * Layer placement rows for the projection (compact markdown table).
+ */
+export function formatAgentProjectionLayers(layers) {
+    if (!Array.isArray(layers) || layers.length === 0) {
+        return '_No project layers loaded — read `ark.config.json` or run `ark start` / `ark_manifest`._';
+    }
+    const rows = layers
+        .map((layer) => {
+        const name = layer.name?.trim() || 'Unknown';
+        const patternList = layer.patterns ?? [];
+        const prefixList = layer.intentPrefixes ?? [];
+        const patterns = patternList.map((pattern) => `\`${pattern}\``).join(', ') || '—';
+        const prefixes = prefixList.map((prefix) => `\`${prefix}\``).join(', ') || '—';
+        return `| ${name} | ${patterns} | ${prefixes} |`;
+    })
+        .join('\n');
+    return `| Layer | Patterns | Intent prefixes |
+|-------|----------|-----------------|
+${rows}`;
+}
+/**
+ * Catalog short-list bullets (ruleId + title). Empty list → pointer only.
+ */
+export function formatAgentProjectionCatalogShortList(entries, docsPath) {
+    const path = docsPath.trim() || 'docs/diagnostics.md';
+    if (!Array.isArray(entries) || entries.length === 0) {
+        return `Full public codes: \`${path}\` (and package \`DIAGNOSTIC_CATALOG\`).`;
+    }
+    const lines = entries
+        .filter((entry) => entry && typeof entry.ruleId === 'string' && entry.ruleId.length > 0)
+        .map((entry) => {
+        const title = typeof entry.title === 'string' && entry.title.trim() ? entry.title.trim() : entry.ruleId;
+        return `- \`${entry.ruleId}\` — ${title}`;
+    });
+    return `${lines.join('\n')}
+
+Full catalog: \`${path}\` (\`#RULE_ID\` anchors).`;
+}
+/**
+ * Projection **body** only (no begin/end markers). Used for content-identity.
+ */
+export function buildAgentProjectionBody(facts) {
+    const version = safeVersion(facts.arkgateVersion);
+    const profile = resolveProfile(facts.profile);
+    const checkCommand = typeof facts.checkCommand === 'string' && facts.checkCommand.trim()
+        ? facts.checkCommand.trim()
+        : 'ark-check --strict-config';
+    const docsPath = typeof facts.diagnosticsDocsPath === 'string' && facts.diagnosticsDocsPath.trim()
+        ? facts.diagnosticsDocsPath.trim()
+        : 'docs/diagnostics.md';
+    const hostRaw = typeof facts.host === 'string' ? facts.host.trim().toLowerCase() : '';
+    const host = hostRaw && hostRaw !== 'unknown' ? hostRaw : null;
+    const layers = Array.isArray(facts.layers) ? facts.layers : [];
+    const catalog = Array.isArray(facts.catalogShortList) ? facts.catalogShortList : [];
+    const lines = [
+        '## ArkGate agent contract projection',
+        '',
+        AGENT_PROJECTION_NON_ENFORCEMENT_LABEL,
+        '',
+        `- **arkgateVersion:** \`${version}\` (must match the installed package; regenerate with \`ark agents-md --write\` after upgrade)`,
+        `- **projectionSchema:** \`${ARK_AGENT_PROJECTION_SCHEMA_VERSION}\``,
+        `- **profile:** \`${profile}\`${host ? ` · **host:** \`${host}\`` : ''}`,
+        `- **after edits:** \`${checkCommand}\``,
+        '',
+    ];
+    if (profile === 'compact') {
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name residual lenses in plain language; never “done” on green edges alone while residual remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read the contract with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: edges debt → fix; design-weak / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+    }
+    else {
+        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-contract`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
+    }
+    lines.push('### Enforcement surfaces (authoritative)', '', AGENT_PROJECTION_ENFORCEMENT_SURFACES.map((surface) => `- \`${surface}\``).join('\n'), '');
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/**
+ * Full managed block: begin marker + body + end marker.
+ */
+export function buildAgentProjectionBlock(facts) {
+    const body = buildAgentProjectionBody(facts);
+    const begin = buildAgentProjectionBeginMarker({
+        arkgateVersion: facts.arkgateVersion,
+        schemaVersion: ARK_AGENT_PROJECTION_SCHEMA_VERSION,
+    });
+    return `${begin}\n${body}${AGENT_PROJECTION_END_MARKER}\n`;
+}
+/**
+ * Machine meta for CLI `--json` / tests (never a gate input).
+ */
+export function buildAgentProjectionMeta(facts) {
+    const body = buildAgentProjectionBody(facts);
+    const layers = Array.isArray(facts.layers) ? facts.layers : [];
+    const catalog = Array.isArray(facts.catalogShortList) ? facts.catalogShortList : [];
+    return {
+        schemaVersion: ARK_AGENT_PROJECTION_SCHEMA_VERSION,
+        arkgateVersion: safeVersion(facts.arkgateVersion),
+        nonAuthoritative: true,
+        enforcementSurfaces: [...AGENT_PROJECTION_ENFORCEMENT_SURFACES],
+        contentIdentity: agentProjectionContentIdentity(body),
+        layerCount: layers.length,
+        catalogCodeCount: catalog.filter((entry) => entry?.ruleId).length,
+        profile: resolveProfile(facts.profile),
+    };
+}
+/**
+ * Extract the managed projection block from a document (AGENTS.md or equivalent).
+ */
+export function extractAgentProjectionBlock(document) {
+    const text = normalizeNewlines(document ?? '');
+    const beginMatch = BEGIN_LINE_RE.exec(text);
+    if (!beginMatch) {
+        return { block: null, body: null, before: text, after: '', beginAttrs: null };
+    }
+    const beginIndex = beginMatch.index;
+    const beginEnd = beginIndex + beginMatch[0].length;
+    const rest = text.slice(beginEnd);
+    const endMatch = END_LINE_RE.exec(rest);
+    if (!endMatch) {
+        // Unclosed block: treat as absent so merge can insert a well-formed block.
+        return { block: null, body: null, before: text, after: '', beginAttrs: null };
+    }
+    const endIndexInRest = endMatch.index;
+    const endEndInRest = endIndexInRest + endMatch[0].length;
+    // Strip a single leading newline after the begin marker; keep body content as-is.
+    let body = rest.slice(0, endIndexInRest);
+    if (body.startsWith('\n'))
+        body = body.slice(1);
+    const block = text.slice(beginIndex, beginEnd + endEndInRest);
+    const after = rest.slice(endEndInRest);
+    return {
+        block,
+        body,
+        before: text.slice(0, beginIndex),
+        after,
+        beginAttrs: beginMatch[1] ?? '',
+    };
+}
+/**
+ * Parse stamps from a projection begin marker or full block/document.
+ */
+export function parseAgentProjectionStamp(source) {
+    const text = String(source ?? '');
+    const begin = BEGIN_LINE_RE.exec(text);
+    const attrs = begin?.[1] ?? text;
+    const versionMatch = VERSION_ATTR_RE.exec(attrs);
+    const schemaMatch = SCHEMA_ATTR_RE.exec(attrs);
+    const nonAuthoritative = /\bnonAuthoritative\s*=\s*true\b/i.test(attrs);
+    return {
+        arkgateVersion: versionMatch?.[1] ?? null,
+        schemaVersion: schemaMatch?.[1] ?? null,
+        nonAuthoritative,
+    };
+}
+/**
+ * True when the document/block stamps the given package version.
+ */
+export function projectionMatchesPackageVersion(source, packageVersion) {
+    const stamped = parseAgentProjectionStamp(source).arkgateVersion;
+    if (!stamped)
+        return false;
+    return stamped === safeVersion(packageVersion);
+}
+/**
+ * True when body text carries the non-enforcement label (substring match).
+ */
+export function projectionHasNonEnforcementLabel(bodyOrBlock) {
+    return String(bodyOrBlock ?? '').includes('non-authoritative');
+}
+/**
+ * Merge a desired projection block into an existing document without rewriting
+ * customized content **outside** the managed markers.
+ *
+ * - Missing document → create `# Ark Enforcement` + block
+ * - Existing markers → replace block when content-identity differs; else unchanged
+ * - No markers → insert block after the first markdown H1 (or at top)
+ */
+export function mergeAgentProjectionDocument(existing, desiredBlock) {
+    const desired = ensureTrailingNewline(normalizeNewlines(desiredBlock));
+    const desiredExtract = extractAgentProjectionBlock(desired);
+    const desiredBody = desiredExtract.body ??
+        desired.replace(BEGIN_LINE_RE, '').replace(END_LINE_RE, '').trim() + '\n';
+    const contentIdentity = agentProjectionContentIdentity(desiredBody);
+    if (existing == null || !String(existing).trim()) {
+        return {
+            content: ensureTrailingNewline(`# Ark Enforcement\n\n${desired}`),
+            action: 'created',
+            previousBlock: null,
+            contentIdentity,
+            preservedOutsideBlock: false,
+        };
+    }
+    const current = normalizeNewlines(existing);
+    const extracted = extractAgentProjectionBlock(current);
+    if (extracted.block != null) {
+        const currentBody = extracted.body ?? '';
+        if (agentProjectionContentIdentity(currentBody) === contentIdentity) {
+            return {
+                content: ensureTrailingNewline(current),
+                action: 'unchanged',
+                previousBlock: extracted.block,
+                contentIdentity,
+                preservedOutsideBlock: true,
+            };
+        }
+        const before = extracted.before.replace(/\s*$/, '\n\n');
+        const after = extracted.after.replace(/^\s*/, '\n');
+        return {
+            content: ensureTrailingNewline(`${before}${desired.trimEnd()}\n${after}`),
+            action: 'block-replaced',
+            previousBlock: extracted.block,
+            contentIdentity,
+            preservedOutsideBlock: true,
+        };
+    }
+    // Insert after first H1 line when present.
+    const h1 = /^(#\s+[^\n]*\n)/m.exec(current);
+    if (h1 && h1.index != null) {
+        const insertAt = h1.index + h1[1].length;
+        const before = current.slice(0, insertAt).replace(/\s*$/, '\n\n');
+        const after = current.slice(insertAt).replace(/^\s*/, '\n');
+        return {
+            content: ensureTrailingNewline(`${before}${desired.trimEnd()}\n${after}`),
+            action: 'block-inserted',
+            previousBlock: null,
+            contentIdentity,
+            preservedOutsideBlock: true,
+        };
+    }
+    return {
+        content: ensureTrailingNewline(`${desired.trimEnd()}\n\n${current.trimStart()}`),
+        action: 'block-inserted',
+        previousBlock: null,
+        contentIdentity,
+        preservedOutsideBlock: true,
+    };
+}

package/bin/lib/agent-skills-package.mjs

@@ -0,0 +1,266 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/agentSkillsPackage.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/agent-skills-package.mjs). Zero Node I/O.
+ */
+
+export const ARK_AGENT_SKILLS_PACKAGE_SCHEMA_VERSION = '1.0';
+/**
+ * Relative package-root path of the Agent Skills–compatible skill package.
+ * Install via skills ecosystem: `npx skills add <path-to-this-dir>`.
+ */
+export const AGENT_SKILLS_PACKAGE_RELATIVE_ROOT = 'templates/agent-skills';
+/** Relative package-root path of flat skill templates (Ark install source). */
+export const FLAT_SKILL_TEMPLATES_RELATIVE_ROOT = 'templates/skills';
+/** Required entry filename inside each skill directory (Agent Skills standard). */
+export const AGENT_SKILL_ENTRY_FILENAME = 'SKILL.md';
+/**
+ * Closed skill-name freeze (ACS / ADR skill freeze). Exactly these 13 names ship.
+ * Sorted alphabetically for deterministic inventory diffs.
+ */
+export const ARK_SKILL_NAMES = Object.freeze([
+    'ark-adopt',
+    'ark-architect',
+    'ark-autopilot',
+    'ark-contract',
+    'ark-coverage',
+    'ark-explain',
+    'ark-explore',
+    'ark-fix',
+    'ark-loop',
+    'ark-place',
+    'ark-runtime',
+    'ark-think',
+    'ark-upgrade',
+]);
+/** Count of frozen skill names (must stay 13 until a ROADMAP item lifts the freeze). */
+export const ARK_SKILL_NAME_COUNT = ARK_SKILL_NAMES.length;
+const AGENT_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Agent Skills `name` field rules (agentskills.io):
+ * - 1–64 characters
+ * - lowercase a–z, digits, hyphens only
+ * - no leading/trailing hyphen; no consecutive hyphens
+ */
+export function isValidAgentSkillName(name) {
+    if (typeof name !== 'string' || name.length < 1 || name.length > 64)
+        return false;
+    return AGENT_SKILL_NAME_PATTERN.test(name);
+}
+/** True when `name` is one of the frozen 13 Ark skill names. */
+export function isArkSkillName(name) {
+    return ARK_SKILL_NAMES.includes(name);
+}
+/**
+ * Parse a skill markdown document with optional YAML frontmatter.
+ * Supports the simple `key: value` / `key: "quoted"` form used by Ark templates
+ * (no nested maps, no multi-line YAML).
+ */
+export function parseSkillDocument(content) {
+    const text = String(content ?? '').replace(/^\uFEFF/, '');
+    const newline = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    if (lines[0] !== '---') {
+        return { hasFrontmatter: false, frontmatter: null, body: text };
+    }
+    const closeIdx = lines.indexOf('---', 1);
+    if (closeIdx === -1) {
+        return { hasFrontmatter: false, frontmatter: null, body: text };
+    }
+    const fields = {};
+    for (let i = 1; i < closeIdx; i += 1) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1];
+        let value = match[2] ?? '';
+        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+            value = value.slice(1, -1);
+        }
+        fields[key] = value;
+    }
+    const body = lines.slice(closeIdx + 1).join(newline);
+    const name = typeof fields.name === 'string' && fields.name.length > 0 ? fields.name : null;
+    const description = typeof fields.description === 'string' && fields.description.length > 0
+        ? fields.description
+        : null;
+    const license = typeof fields.license === 'string' && fields.license.length > 0 ? fields.license : null;
+    return {
+        hasFrontmatter: true,
+        frontmatter: { fields, name, description, license },
+        body,
+    };
+}
+/**
+ * Validate one skill document against the Agent Skills spec (+ optional Ark freeze).
+ */
+export function validateAgentSkillDocument(input) {
+    const requireArk = input.requireArkSkillName !== false;
+    const requireBody = input.requireBody !== false;
+    const issues = [];
+    const directoryName = String(input.directoryName ?? '');
+    const parsed = parseSkillDocument(input.content);
+    if (!parsed.hasFrontmatter || !parsed.frontmatter) {
+        issues.push({
+            code: 'MISSING_FRONTMATTER',
+            message: `Skill "${directoryName}" is missing YAML frontmatter fences.`,
+            skillName: directoryName || undefined,
+        });
+        return issues;
+    }
+    const { name, description } = parsed.frontmatter;
+    const skillRef = name ?? (directoryName || undefined);
+    if (!name || !isValidAgentSkillName(name)) {
+        issues.push({
+            code: 'INVALID_NAME',
+            message: `Skill name "${name ?? ''}" is invalid (Agent Skills: 1–64 chars, [a-z0-9-], no leading/trailing/consecutive hyphens).`,
+            skillName: skillRef,
+        });
+    }
+    else if (name !== directoryName) {
+        issues.push({
+            code: 'NAME_DIRECTORY_MISMATCH',
+            message: `Frontmatter name "${name}" must match directory name "${directoryName}".`,
+            skillName: name,
+        });
+    }
+    else if (requireArk && !isArkSkillName(name)) {
+        issues.push({
+            code: 'UNKNOWN_SKILL_NAME',
+            message: `Skill name "${name}" is not in the frozen Ark 13-skill catalog (no new skill names).`,
+            skillName: name,
+        });
+    }
+    if (!description) {
+        issues.push({
+            code: 'MISSING_DESCRIPTION',
+            message: `Skill "${directoryName}" is missing a non-empty description.`,
+            skillName: skillRef,
+        });
+    }
+    else if (description.length > 1024) {
+        issues.push({
+            code: 'DESCRIPTION_TOO_LONG',
+            message: `Skill "${directoryName}" description exceeds 1024 characters (${description.length}).`,
+            skillName: skillRef,
+        });
+    }
+    if (requireBody && parsed.body.trim().length === 0) {
+        issues.push({
+            code: 'EMPTY_BODY',
+            message: `Skill "${directoryName}" has an empty instruction body.`,
+            skillName: skillRef,
+        });
+    }
+    return issues;
+}
+/**
+ * Validate a full Agent Skills package inventory against the frozen 13-name catalog.
+ * Detects missing, extra, duplicate, invalid, and (when supplied) flat-template drift.
+ */
+export function validateAgentSkillsPackage(entries) {
+    const issues = [];
+    const seen = new Set();
+    const names = [];
+    for (const entry of entries) {
+        const name = String(entry.name ?? '');
+        if (seen.has(name)) {
+            issues.push({
+                code: 'DUPLICATE_SKILL',
+                message: `Duplicate skill entry "${name}".`,
+                skillName: name,
+            });
+            continue;
+        }
+        seen.add(name);
+        names.push(name);
+        issues.push(...validateAgentSkillDocument({
+            directoryName: name,
+            content: entry.content,
+            requireArkSkillName: true,
+            requireBody: true,
+        }));
+        if (entry.flatTemplateContent != null &&
+            normalizeSkillContent(entry.content) !== normalizeSkillContent(entry.flatTemplateContent)) {
+            issues.push({
+                code: 'CONTENT_MISMATCH',
+                message: `Agent Skills SKILL.md for "${name}" does not match flat template templates/skills/${name}.md.`,
+                skillName: name,
+            });
+        }
+    }
+    for (const expected of ARK_SKILL_NAMES) {
+        if (!seen.has(expected)) {
+            issues.push({
+                code: 'MISSING_SKILL',
+                message: `Missing frozen skill "${expected}" from Agent Skills package.`,
+                skillName: expected,
+            });
+        }
+    }
+    for (const name of names) {
+        if (!isArkSkillName(name)) {
+            // UNKNOWN_SKILL_NAME may already be reported per-document; still mark package-level extra.
+            if (!issues.some((i) => i.code === 'UNKNOWN_SKILL_NAME' && i.skillName === name)) {
+                issues.push({
+                    code: 'EXTRA_SKILL',
+                    message: `Extra skill "${name}" is not in the frozen Ark 13-skill catalog.`,
+                    skillName: name,
+                });
+            }
+            else {
+                issues.push({
+                    code: 'EXTRA_SKILL',
+                    message: `Extra skill "${name}" is not in the frozen Ark 13-skill catalog.`,
+                    skillName: name,
+                });
+            }
+        }
+    }
+    names.sort();
+    return {
+        ok: issues.length === 0,
+        issues,
+        names,
+        expectedCount: ARK_SKILL_NAME_COUNT,
+        presentCount: names.length,
+    };
+}
+/**
+ * Normalize skill file content for identity compare (LF newlines, strip BOM).
+ * Does not strip or rewrite frontmatter — Agent Skills export is 1:1 with flat templates.
+ */
+export function normalizeSkillContent(content) {
+    return String(content ?? '')
+        .replace(/^\uFEFF/, '')
+        .replace(/\r\n/g, '\n');
+}
+/**
+ * Relative path of one skill entry inside the Agent Skills package root.
+ * Example: `ark-place/SKILL.md`
+ */
+export function agentSkillEntryRelativePath(skillName) {
+    return `${skillName}/${AGENT_SKILL_ENTRY_FILENAME}`;
+}
+/**
+ * Relative path from package root for one Agent Skills entry.
+ * Example: `templates/agent-skills/ark-place/SKILL.md`
+ */
+export function agentSkillPackageFileRelativePath(skillName) {
+    return `${AGENT_SKILLS_PACKAGE_RELATIVE_ROOT}/${agentSkillEntryRelativePath(skillName)}`;
+}
+/**
+ * Relative path from package root for one flat template.
+ * Example: `templates/skills/ark-place.md`
+ */
+export function flatSkillTemplateFileRelativePath(skillName) {
+    return `${FLAT_SKILL_TEMPLATES_RELATIVE_ROOT}/${skillName}.md`;
+}

package/bin/lib/baseline-key.mjs

@@ -11,6 +11,8 @@
 /**
  * Stable key used by `--baseline` / `--update-baseline` to match frozen debt.
  * Field order and empty-string fallbacks are part of the CLI contract.
+ *
+ * Same string is the ACS06 finding `targetKey` (baseline-compatible).
  */
 export function baselineKey(violation) {
     return [
@@ -28,6 +30,9 @@ export function baselineKey(violation) {
  * compatible. Repeated violations with the same identity gain a `#N` suffix;
  * adding a second identical violation is therefore new debt instead of being
  * silently suppressed by the first occurrence's key.
+ *
+ * ACS06 multi-turn adapters must use these keys as `targetKey` so occurrence
+ * identity matches the freeze ratchet (never orphan baselines).
  */
 export function baselineOccurrenceKeys(violations) {
     const counts = new Map();
@@ -38,3 +43,30 @@ export function baselineOccurrenceKeys(violations) {
         return occurrence === 1 ? base : `${base}#${occurrence}`;
     });
 }
+/**
+ * ACS06: baseline-compatible target key for one finding (alias of baselineKey).
+ * Prefer baselineOccurrenceKeys when emitting a list so duplicates stay distinct.
+ */
+export function findingTargetKey(violation) {
+    return baselineKey(violation);
+}
+/**
+ * Compact stable finding ref derived from a baseline-compatible targetKey.
+ * FNV-1a identity only (same family as package fingerprints) — not a security hash.
+ * Format: `fnv1a-` + 8 zero-padded hex digits.
+ */
+export function findingRefFromTargetKey(targetKey) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < targetKey.length; index += 1) {
+        hash ^= targetKey.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+/**
+ * Finding ref for a single violation (first-occurrence / solo identity).
+ * For lists, hash baselineOccurrenceKeys(entries)[i] instead so duplicates differ.
+ */
+export function findingRefForViolation(violation) {
+    return findingRefFromTargetKey(baselineKey(violation));
+}