@agentxm/workspace-lint 0.28.4-bootstrap.0

package/dist/src/catalog/workspace/packs-dependencies-resolved.js

@@ -0,0 +1,49 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { lockfileDisplayPath } from "./display-paths.js";
+const RULE_ID = "workspace/packs-dependencies-resolved";
+/** Pack membership comes from the desired graph; lock rows only prove external resolution. */
+export const packsDependenciesResolvedRule = {
+    id: RULE_ID,
+    description: "Pack-declared external dependencies have accepted resolutions.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        if (context.health === undefined)
+            return [];
+        const graphResult = yield* Effect.result(context.health.desiredState);
+        const lockResult = yield* Effect.result(context.workspace.state.lockfile);
+        if (Result.isFailure(graphResult) || Result.isFailure(lockResult))
+            return [];
+        const lockfile = Option.getOrUndefined(lockResult.success);
+        if (lockfile === undefined)
+            return [];
+        const lockedNames = {
+            skill: new Set(Object.keys(lockfile.skills)),
+            subagent: new Set(Object.keys(lockfile.subagents ?? {})),
+            "mcp-server": new Set(Object.keys(lockfile.mcpServers ?? {})),
+            rule: new Set(Object.keys(lockfile.rules ?? {})),
+            hook: new Set(Object.keys(lockfile.hooks ?? {})),
+            knowledge: new Set(Object.keys(lockfile.knowledge ?? {})),
+        };
+        const findings = [];
+        for (const node of graphResult.success.nodes) {
+            if (node.type === "pack" ||
+                node.identity.startsWith("workspace:") ||
+                !node.origins.some((origin) => origin.type === "pack") ||
+                lockedNames[node.type].has(node.name)) {
+                continue;
+            }
+            findings.push({
+                kind: "advisory",
+                ruleId: RULE_ID,
+                severity: "error",
+                message: `Pack-declared ${node.type} '${node.identity}' has no accepted external resolution.`,
+                location: { file: lockfileDisplayPath(context.subject.scope) },
+            });
+        }
+        return findings;
+    }),
+};
+//# sourceMappingURL=packs-dependencies-resolved.js.map

package/dist/src/catalog/workspace/projections-current.d.ts

@@ -0,0 +1,15 @@
+import { type ProjectionInvariantFact } from "@agentxm/extension-workspace";
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule, LintFinding } from "@agentxm/registry-protocol/unstable/lint/rule";
+/**
+ * Managed output units render their complete contributor sets and content.
+ *
+ * Evidence is read back from the outputs themselves: an extension whose
+ * canonical content is installed and reachable can still be absent from, or
+ * stale in, its projection. The accessor yields no verdict when currency
+ * cannot be judged (incomplete desired-state graph, missing canonical
+ * content); root-cause rules own those conditions.
+ */
+export declare const projectionsCurrentRule: AdvisoryRule<WorkspaceRuleContext>;
+export declare const findingsForProjectionFacts: (facts: ReadonlyArray<ProjectionInvariantFact>) => ReadonlyArray<LintFinding>;
+//# sourceMappingURL=projections-current.d.ts.map

package/dist/src/catalog/workspace/projections-current.js

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import { projectionFactIsViolation, } from "@agentxm/extension-workspace";
+import { EMPTY_LINT_FINDINGS } from "./helpers/empty.js";
+const RULE_ID = "workspace/projections-current";
+/**
+ * Managed output units render their complete contributor sets and content.
+ *
+ * Evidence is read back from the outputs themselves: an extension whose
+ * canonical content is installed and reachable can still be absent from, or
+ * stale in, its projection. The accessor yields no verdict when currency
+ * cannot be judged (incomplete desired-state graph, missing canonical
+ * content); root-cause rules own those conditions.
+ */
+export const projectionsCurrentRule = {
+    id: RULE_ID,
+    description: "Managed outputs render every enabled reachable contributor exactly once.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        if (context.projections === undefined)
+            return EMPTY_LINT_FINDINGS;
+        return findingsForProjectionFacts(yield* context.projections.facts);
+    }),
+};
+const contributorSuffix = (fact) => fact.affectedContributors.length === 0
+    ? ""
+    : ` Affected contributors: ${fact.affectedContributors.join(", ")}.`;
+export const findingsForProjectionFacts = (facts) => facts.filter(projectionFactIsViolation).map((fact) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: fact.observation.message ??
+        `The AXM-owned projection at ${fact.subject.path} is ${fact.observation.status}.${contributorSuffix(fact)}`,
+}));
+//# sourceMappingURL=projections-current.js.map

package/dist/src/catalog/workspace/settings-keys-recognized.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `workspace/settings-keys-recognized` — `axm.json` uses only
+ * supported top-level keys.
+ *
+ * `SettingsSchema` tolerates and preserves unknown top-level keys so a write
+ * never destroys data it did not create; this rule is the guardrail that
+ * surfaces those keys loudly. It early-returns when the file is missing or
+ * unparsable (`workspace/initialized` and `workspace/settings-schema-valid`
+ * own those arms).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule } from "@agentxm/registry-protocol/unstable/lint/rule";
+export declare const settingsKeysRecognizedRule: AdvisoryRule<WorkspaceRuleContext>;
+//# sourceMappingURL=settings-keys-recognized.d.ts.map

package/dist/src/catalog/workspace/settings-keys-recognized.js

@@ -0,0 +1,90 @@
+/**
+ * `workspace/settings-keys-recognized` — `axm.json` uses only
+ * supported top-level keys.
+ *
+ * `SettingsSchema` tolerates and preserves unknown top-level keys so a write
+ * never destroys data it did not create; this rule is the guardrail that
+ * surfaces those keys loudly. It early-returns when the file is missing or
+ * unparsable (`workspace/initialized` and `workspace/settings-schema-valid`
+ * own those arms).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { SETTINGS_KNOWN_KEYS } from "@agentxm/workspace-state";
+import { settingsDisplayPath } from "./display-paths.js";
+import { EMPTY_ADVISORY_FINDINGS } from "./helpers/empty.js";
+const RULE_ID = "workspace/settings-keys-recognized";
+const levenshteinDistance = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        let diagonal = previous[0] ?? 0;
+        previous[0] = leftIndex;
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const above = previous[rightIndex] ?? 0;
+            const substitution = left[leftIndex - 1] === right[rightIndex - 1] ? diagonal : diagonal + 1;
+            previous[rightIndex] = Math.min(above + 1, (previous[rightIndex - 1] ?? 0) + 1, substitution);
+            diagonal = above;
+        }
+    }
+    return previous[right.length] ?? 0;
+};
+const closestKnownKey = (key) => {
+    const lowered = key.toLowerCase();
+    let best;
+    for (const candidate of SETTINGS_KNOWN_KEYS) {
+        if (candidate.toLowerCase() === lowered)
+            return candidate;
+        const distance = levenshteinDistance(key, candidate);
+        if (distance <= 2 && (best === undefined || distance < best.distance)) {
+            best = { candidate, distance };
+        }
+    }
+    return best?.candidate;
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// `workspace/settings-schema-valid` owns the invalid-JSON arm; this rule stays
+// quiet unless the bytes parse to a plain object.
+const parseJsonRecord = (raw) => {
+    try {
+        const value = JSON.parse(raw);
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const settingsKeysRecognizedRule = {
+    id: RULE_ID,
+    description: "Workspace settings use only supported top-level keys.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const raw = yield* Effect.result(context.workspace.state.raw("settings"));
+        if (Result.isFailure(raw) || Option.isNone(raw.success)) {
+            return EMPTY_ADVISORY_FINDINGS;
+        }
+        const parsed = parseJsonRecord(raw.success.value.bytes);
+        if (parsed === undefined) {
+            return EMPTY_ADVISORY_FINDINGS;
+        }
+        return Object.keys(parsed)
+            .filter((key) => !SETTINGS_KNOWN_KEYS.has(key))
+            .map((key) => {
+            const hint = closestKnownKey(key);
+            return {
+                kind: "advisory",
+                ruleId: RULE_ID,
+                severity: "error",
+                message: `Workspace settings has unrecognized top-level key '${key}'.` +
+                    (hint === undefined ? "" : ` Did you mean '${hint}'?`) +
+                    ` The current settings schema does not recognize this key.`,
+                location: { file: settingsDisplayPath(context.subject.scope) },
+            };
+        });
+    }),
+};
+//# sourceMappingURL=settings-keys-recognized.js.map

package/dist/src/catalog/workspace/settings-schema-valid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `workspace/settings-schema-valid` — `axm.json` conforms to
+ * `SettingsSchema`.
+ *
+ * Cascade per the lint design:
+ *
+ * 1. `axm.json` is present (`workspace/initialized` owns the
+ *    absence arm; this rule early-returns when the file is missing).
+ * 2. The file parses as JSON (the accessor surfaces parse failures via
+ *    `SettingsReadError`; we emit one finding per read failure).
+ * 3. The parsed value is a JSON object (not an array or scalar) — enforced
+ *    by `Schema.decodeUnknownResult(SettingsSchema)` structurally.
+ * 4. `SettingsSchema` decode succeeds; `ParseResult` issues map 1:1 to
+ *    findings via `schemaDecodeFindings`.
+ *
+ * Reports the read-failure finding when arm 2 fails; otherwise reports the
+ * schema issues produced by arm 3/4. The unknown-key companion
+ * (`workspace/settings-keys-recognized`) reports unrecognized top-level keys,
+ * which `SettingsSchema` now tolerates and preserves rather than rejecting.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule } from "@agentxm/registry-protocol/unstable/lint/rule";
+export declare const settingsSchemaValidRule: AdvisoryRule<WorkspaceRuleContext>;
+//# sourceMappingURL=settings-schema-valid.d.ts.map

package/dist/src/catalog/workspace/settings-schema-valid.js

@@ -0,0 +1,68 @@
+/**
+ * `workspace/settings-schema-valid` — `axm.json` conforms to
+ * `SettingsSchema`.
+ *
+ * Cascade per the lint design:
+ *
+ * 1. `axm.json` is present (`workspace/initialized` owns the
+ *    absence arm; this rule early-returns when the file is missing).
+ * 2. The file parses as JSON (the accessor surfaces parse failures via
+ *    `SettingsReadError`; we emit one finding per read failure).
+ * 3. The parsed value is a JSON object (not an array or scalar) — enforced
+ *    by `Schema.decodeUnknownResult(SettingsSchema)` structurally.
+ * 4. `SettingsSchema` decode succeeds; `ParseResult` issues map 1:1 to
+ *    findings via `schemaDecodeFindings`.
+ *
+ * Reports the read-failure finding when arm 2 fails; otherwise reports the
+ * schema issues produced by arm 3/4. The unknown-key companion
+ * (`workspace/settings-keys-recognized`) reports unrecognized top-level keys,
+ * which `SettingsSchema` now tolerates and preserves rather than rejecting.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { EMPTY_ADVISORY_FINDINGS } from "./helpers/empty.js";
+import { settingsDisplayPath } from "./display-paths.js";
+const RULE_ID = "workspace/settings-schema-valid";
+export const settingsSchemaValidRule = {
+    id: RULE_ID,
+    description: "Workspace settings are structurally valid.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const scoped = context.workspace;
+        const settingsPath = settingsDisplayPath(context.subject.scope);
+        const raw = yield* Effect.result(scoped.state.raw("settings"));
+        if (Result.isSuccess(raw) && Option.isNone(raw.success)) {
+            return EMPTY_ADVISORY_FINDINGS;
+        }
+        const settings = yield* Effect.result(scoped.state.settings);
+        if (Result.isFailure(settings)) {
+            const error = settings.failure;
+            if (error._tag === "SettingsDecodeError") {
+                return error.issues.map((issue) => ({
+                    kind: "advisory",
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    message: `The workspace settings file does not match the expected schema. Detail: ${issue}. Edit \`${settingsPath}\` to fix the invalid value.`,
+                    location: { file: settingsPath },
+                }));
+            }
+            return [
+                {
+                    kind: "advisory",
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    message: `The workspace settings file is not valid JSON. Detail: ${error._tag}. ` +
+                        `Edit \`${settingsPath}\` to fix the JSON syntax.`,
+                    location: { file: settingsPath },
+                },
+            ];
+        }
+        return EMPTY_ADVISORY_FINDINGS;
+    }),
+};
+//# sourceMappingURL=settings-schema-valid.js.map

package/dist/src/catalog/workspace/skills-artifacts-correct.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `workspace/skills-artifacts-correct` — each enabled skill has artifacts in
+ * every declared agent's skill target; disabled skills have none.
+ *
+ * Three symptoms of the same invariant (§10.workspace.Skills note):
+ *
+ * - **Enabled-but-not-linked** — a skill declared `enabled: true` is missing
+ *   its per-agent artifact for at least one declared agent. Autofix:
+ *   `enable-skill` (the handler recreates symlinks across configured agents).
+ * - **Disabled-but-still-present** — a skill declared `enabled: false` still
+ *   has a per-agent artifact for at least one declared agent. Autofix:
+ *   `disable-skill`.
+ * - **Cross-agent-inconsistent** — an enabled skill has artifacts in some
+ *   declared agents but not others. Autofix: `enable-skill`.
+ *
+ * One finding per affected skill (per-entity cascade); the first arm that
+ * fires for a skill emits its finding and the other arms for the same skill
+ * do not. Configured skills keep the existing autofix arms; pack-provided
+ * implicit skills emit advisory findings because the repair is a pack-level
+ * reinstall.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule } from "@agentxm/registry-protocol/unstable/lint/rule";
+export declare const skillsArtifactsCorrectRule: AdvisoryRule<WorkspaceRuleContext>;
+//# sourceMappingURL=skills-artifacts-correct.d.ts.map

package/dist/src/catalog/workspace/skills-artifacts-correct.js

@@ -0,0 +1,143 @@
+/**
+ * `workspace/skills-artifacts-correct` — each enabled skill has artifacts in
+ * every declared agent's skill target; disabled skills have none.
+ *
+ * Three symptoms of the same invariant (§10.workspace.Skills note):
+ *
+ * - **Enabled-but-not-linked** — a skill declared `enabled: true` is missing
+ *   its per-agent artifact for at least one declared agent. Autofix:
+ *   `enable-skill` (the handler recreates symlinks across configured agents).
+ * - **Disabled-but-still-present** — a skill declared `enabled: false` still
+ *   has a per-agent artifact for at least one declared agent. Autofix:
+ *   `disable-skill`.
+ * - **Cross-agent-inconsistent** — an enabled skill has artifacts in some
+ *   declared agents but not others. Autofix: `enable-skill`.
+ *
+ * One finding per affected skill (per-entity cascade); the first arm that
+ * fires for a skill emits its finding and the other arms for the same skill
+ * do not. Configured skills keep the existing autofix arms; pack-provided
+ * implicit skills emit advisory findings because the repair is a pack-level
+ * reinstall.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { EMPTY_LINT_FINDINGS } from "./helpers/empty.js";
+import { isUniversalSkillsRelativeDir, resolveUniversalDirPresence, } from "@agentxm/extension-model/unstable/extensions/universal-skills-dir";
+import { isConfigurableAgentId } from "@agentxm/extension-model/unstable/agents/types";
+import { settingsDisplayPath } from "./display-paths.js";
+const RULE_ID = "workspace/skills-artifacts-correct";
+const enableFinding = (name, reason, path) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${name}' is enabled, but it is missing from declared agents: ${reason}.`,
+    location: { file: path },
+});
+const disableFinding = (name, reason, path) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${name}' is disabled, but it is still present for declared agents: ${reason}.`,
+    location: { file: path },
+});
+const inconsistentFinding = (name, details, path) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${name}' is present for some declared agents but missing from others. ${details}.`,
+    location: { file: path },
+});
+const implicitEnableFinding = (name, reason, path) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Pack-provided skill '${name}' is missing from declared agents: ${reason}.`,
+    location: { file: path },
+});
+const collectArtifactViolations = (existenceBySkill, settingsPath) => {
+    const violations = [];
+    for (const { name, enabled, presentAgents, missingAgents, implicit } of existenceBySkill) {
+        if (enabled) {
+            if (missingAgents.length === 0) {
+                continue;
+            }
+            if (implicit) {
+                violations.push({
+                    finding: implicitEnableFinding(name, missingAgents.join(", "), settingsPath),
+                });
+                continue;
+            }
+            if (presentAgents.length === 0) {
+                violations.push({
+                    finding: enableFinding(name, missingAgents.join(", "), settingsPath),
+                });
+                continue;
+            }
+            violations.push({
+                finding: inconsistentFinding(name, `Present for agents: ${presentAgents.join(", ")}. Missing from agents: ${missingAgents.join(", ")}`, settingsPath),
+            });
+            continue;
+        }
+        if (presentAgents.length > 0) {
+            violations.push({
+                finding: disableFinding(name, presentAgents.join(", "), settingsPath),
+            });
+        }
+    }
+    return violations;
+};
+export const skillsArtifactsCorrectRule = {
+    id: RULE_ID,
+    description: "Skill directories match each skill's enabled state across declared agents.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const scoped = context.workspace;
+        const settingsResult = yield* Effect.result(scoped.state.settings);
+        // The schema/readability rules own these failures and emit the precise
+        // finding. This dependent rule cannot evaluate artifact correctness.
+        if (Result.isFailure(settingsResult))
+            return EMPTY_LINT_FINDINGS;
+        const settings = settingsResult.success;
+        if (Option.isNone(settings)) {
+            return EMPTY_LINT_FINDINGS;
+        }
+        const declaredAgentIds = new Set(settings.value.agents ?? []);
+        if (declaredAgentIds.size === 0) {
+            return EMPTY_LINT_FINDINGS;
+        }
+        const knownAgents = yield* scoped.agents.known;
+        const declaredAgents = knownAgents.filter((agent) => isConfigurableAgentId(agent.id) && declaredAgentIds.has(agent.id));
+        const universalAgentIds = new Set(declaredAgents
+            .filter((agent) => agent.skills !== undefined && isUniversalSkillsRelativeDir(agent.skills.dir))
+            .map((agent) => agent.id));
+        const installedResult = yield* Effect.result(scoped.skills.installed);
+        // The lockfile/readability rules own this failure; avoid turning it into
+        // a defect or duplicating a less precise finding here.
+        if (Result.isFailure(installedResult))
+            return EMPTY_LINT_FINDINGS;
+        const installed = installedResult.success;
+        const existenceBySkill = installed.flatMap((row) => {
+            const implicit = row.installationOrigin._tag === "pack-member";
+            if (implicit && Option.isNone(row.resolved)) {
+                return [];
+            }
+            const present = new Set(row.actual.flatMap((actual) => actual.origin._tag === "agent-skill-dir" ? [actual.origin.agentId] : []));
+            const collapsed = resolveUniversalDirPresence(declaredAgents.map((agent) => ({ agentId: agent.id, exists: present.has(agent.id) })), universalAgentIds);
+            return {
+                name: row.key.name,
+                enabled: row.activation === "enabled",
+                presentAgents: collapsed.filter((p) => p.exists).map((p) => p.agentId),
+                missingAgents: collapsed.filter((p) => !p.exists).map((p) => p.agentId),
+                implicit,
+            };
+        });
+        const violations = collectArtifactViolations(existenceBySkill, settingsDisplayPath(context.subject.scope));
+        return violations.map((violation) => violation.finding);
+    }),
+};
+//# sourceMappingURL=skills-artifacts-correct.js.map

package/dist/src/catalog/workspace/skills-declarations-valid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `workspace/skills-declarations-valid` — declared skills name a resolvable,
+ * owner-qualified, unique source.
+ *
+ * Cascade per the lint design (reports the
+ * first failing arm per affected entity):
+ *
+ * 1. Source resolvability — the source string is shaped like a ref we can
+ *    route (owner-qualified FQN like `@owner/skills/name`, a known source
+ *    host, `file://` URL, local path). Bare names (`just-a-name`) fail.
+ * 2. Owner qualification — registry-shaped sources carry an `@owner`
+ *    prefix; entries whose source looks registry-ish but omits the owner
+ *    fail.
+ * 3. Duplicate FQNs — when two settings entries normalize to the same
+ *    owner/type/name FQN, both entries emit a finding.
+ *
+ * One finding per affected entity (per-entity cascade). Advisory — no lint
+ * autofix; resolve invalid or duplicate declarations with install/uninstall
+ * commands.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule } from "@agentxm/registry-protocol/unstable/lint/rule";
+export declare const skillsDeclarationsValidRule: AdvisoryRule<WorkspaceRuleContext>;
+//# sourceMappingURL=skills-declarations-valid.d.ts.map

package/dist/src/catalog/workspace/skills-declarations-valid.js

@@ -0,0 +1,102 @@
+/**
+ * `workspace/skills-declarations-valid` — declared skills name a resolvable,
+ * owner-qualified, unique source.
+ *
+ * Cascade per the lint design (reports the
+ * first failing arm per affected entity):
+ *
+ * 1. Source resolvability — the source string is shaped like a ref we can
+ *    route (owner-qualified FQN like `@owner/skills/name`, a known source
+ *    host, `file://` URL, local path). Bare names (`just-a-name`) fail.
+ * 2. Owner qualification — registry-shaped sources carry an `@owner`
+ *    prefix; entries whose source looks registry-ish but omits the owner
+ *    fail.
+ * 3. Duplicate FQNs — when two settings entries normalize to the same
+ *    owner/type/name FQN, both entries emit a finding.
+ *
+ * One finding per affected entity (per-entity cascade). Advisory — no lint
+ * autofix; resolve invalid or duplicate declarations with install/uninstall
+ * commands.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { settingsDisplayPath } from "./display-paths.js";
+import { EMPTY_ADVISORY_FINDINGS } from "./helpers/empty.js";
+import { categorizeEntry } from "./helpers/source-categorize.js";
+const RULE_ID = "workspace/skills-declarations-valid";
+const findingForBareName = (entry, settingsPath) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${entry.name}' uses ambiguous bare source '${entry.source}'.`,
+    location: { file: settingsPath },
+});
+const findingForMissingOwner = (entry, settingsPath) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${entry.name}' source '${entry.source}' is missing its owner-qualified identity.`,
+    location: { file: settingsPath },
+});
+const findingForDuplicate = (entry, duplicates, settingsPath) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message: `Skill '${entry.name}' duplicates the same Skill identity as: ${duplicates.join(", ")}.`,
+    location: { file: settingsPath },
+});
+export const skillsDeclarationsValidRule = {
+    id: RULE_ID,
+    description: "Declared skills use unique, resolvable sources.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const scoped = context.workspace;
+        const declaredResult = yield* Effect.result(scoped.skills.declared);
+        if (Result.isFailure(declaredResult) || Option.isNone(declaredResult.success)) {
+            return EMPTY_ADVISORY_FINDINGS;
+        }
+        const entries = declaredResult.success.value.map(({ name, entry }) => categorizeEntry(name, entry.source));
+        // Group by registry FQN for duplicate detection.
+        const byFqn = new Map();
+        for (const entry of entries) {
+            if ((entry.kind !== "registry" && entry.kind !== "workspace") ||
+                entry.registryFqn === undefined) {
+                continue;
+            }
+            const group = byFqn.get(entry.registryFqn) ?? [];
+            group.push(entry);
+            byFqn.set(entry.registryFqn, group);
+        }
+        const findings = [];
+        const settingsPath = settingsDisplayPath(context.subject.scope);
+        for (const entry of entries) {
+            if (entry.kind === "bare") {
+                findings.push(findingForBareName(entry, settingsPath));
+                continue;
+            }
+            if (entry.kind === "registry-no-owner") {
+                findings.push(findingForMissingOwner(entry, settingsPath));
+                continue;
+            }
+            if (entry.kind === "non-registry") {
+                // Non-registry sources are allowed for skills (local, git-hosted)
+                // and don't fire this rule. Move on.
+                continue;
+            }
+            if ((entry.kind === "registry" || entry.kind === "workspace") &&
+                entry.registryFqn !== undefined) {
+                const group = byFqn.get(entry.registryFqn) ?? [];
+                if (group.length > 1) {
+                    findings.push(findingForDuplicate(entry, group.map((g) => g.name).sort(), settingsPath));
+                }
+            }
+        }
+        return findings;
+    }),
+};
+//# sourceMappingURL=skills-declarations-valid.js.map

package/dist/src/catalog/workspace/skills-integrity-valid.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `workspace/skills-integrity-valid` — each installed skill listed in the
+ * lockfile is present on disk.
+ *
+ * For each accepted skill lock entry, verify that its canonical acquired
+ * package is present in the scope's canonical root. Missing-package entries
+ * each emit one finding.
+ * Configured findings are autofixable via `install-skill` with
+ * `force: true`; pack-provided implicit findings are advisory because the
+ * repair is a pack-level reinstall.
+ *
+ * This rule owns only the missing-package arm. Package-tree integrity is
+ * evaluated by canonical observations against `treeIntegrity`; local edits,
+ * including formatter changes, are drift and block affected reads and
+ * mutation closures until explicit recovery.
+ *
+ * A skill whose `sourceHash` is undefined in the lockfile (e.g., git-hosted
+ * sources without pinned hash) is not checked.
+ *
+ * One finding per affected entity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { WorkspaceRuleContext } from "../../workspace-context.js";
+import type { AdvisoryRule } from "@agentxm/registry-protocol/unstable/lint/rule";
+export declare const skillsIntegrityValidRule: AdvisoryRule<WorkspaceRuleContext>;
+//# sourceMappingURL=skills-integrity-valid.d.ts.map