@opengsd/gsd-pi 1.0.2-dev.e70300c → 1.0.2-dev.fb7ddf1

package/dist/resources/extensions/gsd/skill-activation.js

@@ -0,0 +1,233 @@
+/**
+ * Skill activation and discovery prompt blocks for GSD auto-mode units.
+ */
+import { basename } from "node:path";
+import { parseTaskPlanFile } from "./files.js";
+import { loadEffectiveGSDPreferences, resolveAllSkillReferences, resolveSkillDiscoveryMode, } from "./preferences.js";
+import { filterSkillsByManifest, resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { getInstalledSkills } from "./skills.js";
+import { logWarning } from "./workflow-logger.js";
+function normalizeSkillReference(ref) {
+    const normalized = ref.replace(/\\/g, "/").trim();
+    const base = basename(normalized).replace(/\.md$/i, "");
+    const name = /^SKILL$/i.test(base)
+        ? basename(normalized.replace(/\/SKILL(?:\.md)?$/i, ""))
+        : base;
+    return name.trim().toLowerCase();
+}
+function tokenizeSkillContext(...parts) {
+    const tokens = new Set();
+    const addVariants = (raw) => {
+        const value = raw.trim().toLowerCase();
+        if (!value || value.length < 2)
+            return;
+        tokens.add(value);
+        tokens.add(value.replace(/[-_]+/g, " "));
+        tokens.add(value.replace(/\s+/g, "-"));
+        tokens.add(value.replace(/\s+/g, ""));
+    };
+    for (const part of parts) {
+        if (!part)
+            continue;
+        const text = part.toLowerCase();
+        const phraseMatches = text.match(/[a-z0-9][a-z0-9+.#/_-]{1,}/g) ?? [];
+        for (const match of phraseMatches) {
+            addVariants(match);
+            for (const piece of match.split(/[^a-z0-9+.#]+/g)) {
+                if (piece.length >= 3)
+                    addVariants(piece);
+            }
+        }
+    }
+    return tokens;
+}
+function skillMatchesContext(skill, contextTokens) {
+    const haystacks = [
+        skill.name.toLowerCase(),
+        skill.name.toLowerCase().replace(/[-_]+/g, " "),
+        skill.description.toLowerCase(),
+    ];
+    return [...contextTokens].some(token => token.length >= 3 && haystacks.some(haystack => haystack.includes(token)));
+}
+function resolvePreferenceSkillNames(refs, base) {
+    if (refs.length === 0)
+        return [];
+    const prefs = { always_use_skills: refs };
+    const report = resolveAllSkillReferences(prefs, base);
+    return refs.map(ref => {
+        const resolution = report.resolutions.get(ref);
+        return normalizeSkillReference(resolution?.resolvedPath ?? ref);
+    }).filter(Boolean);
+}
+function ruleMatchesContext(when, contextTokens) {
+    const whenTokens = tokenizeSkillContext(when);
+    return [...whenTokens].some(token => contextTokens.has(token) || [...contextTokens].some(ctx => ctx.includes(token) || token.includes(ctx)));
+}
+function resolveSkillRuleMatches(prefs, contextTokens, base) {
+    if (!prefs?.skill_rules?.length)
+        return { include: [], avoid: [] };
+    const include = [];
+    const avoid = [];
+    for (const rule of prefs.skill_rules) {
+        if (!ruleMatchesContext(rule.when, contextTokens))
+            continue;
+        include.push(...resolvePreferenceSkillNames([...(rule.use ?? []), ...(rule.prefer ?? [])], base));
+        avoid.push(...resolvePreferenceSkillNames(rule.avoid ?? [], base));
+    }
+    return { include, avoid };
+}
+function resolvePreferredSkillNames(prefs, visibleSkills, contextTokens, base) {
+    if (!prefs?.prefer_skills?.length)
+        return [];
+    const preferred = new Set(resolvePreferenceSkillNames(prefs.prefer_skills, base));
+    return visibleSkills
+        .filter(skill => preferred.has(normalizeSkillReference(skill.name)) && skillMatchesContext(skill, contextTokens))
+        .map(skill => normalizeSkillReference(skill.name));
+}
+/** Skill names must be lowercase alphanumeric with hyphens — reject anything else
+ *  to prevent prompt injection via crafted directory names. */
+const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+function formatSkillActivationBlock(skillNames) {
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    // Use explicit parameter syntax so LLMs pass { skill: "..." } instead of { name: "..." }.
+    // The function-call-like syntax `Skill('name')` led LLMs to infer a positional
+    // parameter name, causing tool validation failures — see #2224.
+    const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
+    return `<skill_activation>${calls}.</skill_activation>`;
+}
+/**
+ * Manifest-driven recommendations block — informational only, does NOT
+ * auto-invoke. Lists per-unit-type skills that are installed but not already
+ * activated by explicit user intent (always_use_skills / prefer_skills /
+ * skill_rules / task-plan skills_used). Surfaces relevant skills to the
+ * model so they can be invoked when the model judges them useful.
+ *
+ * This is the additive complement to the existing activation directive:
+ * activation force-invokes (explicit intent), recommendations remind
+ * (manifest defaults). User intent is preserved as the stronger signal
+ * (RFC #4779 design principle); this block only adds visibility.
+ */
+function formatSkillRecommendationsBlock(unitType, skillNames) {
+    if (!unitType)
+        return "";
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+}
+export function buildSkillActivationBlock(params) {
+    const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
+    const contextTokens = tokenizeSkillContext(params.milestoneId, params.milestoneTitle, params.sliceId, params.sliceTitle, params.taskId, params.taskTitle);
+    const loaded = getInstalledSkills(params.skills).filter(skill => !skill.disableModelInvocation);
+    // Skill activation here is driven entirely by explicit sources
+    // (always_use_skills, prefer_skills, skill_rules, task-plan skills_used).
+    // Every match is an explicit user/project intent and must not be dropped
+    // by the unit-type manifest — user intent is stronger signal than
+    // defaults. The manifest's real home is the skill catalog rendering
+    // layer (pi-coding-agent `formatSkillsForPrompt`); that wiring is tracked
+    // as the "load-time short-circuit" follow-up to RFC #4779.
+    //
+    // `unitType` stays plumbed so the strict-mode warning can surface
+    // manifest entries that reference uninstalled skills, and so the
+    // activation-block site is ready to opt in once PR B lands.
+    const visibleSkills = loaded;
+    const manifestScopedSkills = filterSkillsByManifest(visibleSkills, params.unitType);
+    const installedNames = new Set(visibleSkills.map(skill => normalizeSkillReference(skill.name)));
+    warnIfManifestHasMissingSkills(params.unitType, installedNames);
+    const avoided = new Set(resolvePreferenceSkillNames(prefs?.avoid_skills ?? [], params.base));
+    const matched = new Set();
+    for (const name of resolvePreferenceSkillNames(prefs?.always_use_skills ?? [], params.base)) {
+        matched.add(name);
+    }
+    const ruleMatches = resolveSkillRuleMatches(prefs, contextTokens, params.base);
+    for (const name of ruleMatches.include)
+        matched.add(name);
+    for (const name of ruleMatches.avoid)
+        avoided.add(name);
+    for (const name of resolvePreferredSkillNames(prefs, visibleSkills, contextTokens, params.base)) {
+        matched.add(name);
+    }
+    if (params.taskPlanContent) {
+        try {
+            const taskPlan = parseTaskPlanFile(params.taskPlanContent);
+            for (const skillName of taskPlan.frontmatter.skills_used) {
+                matched.add(normalizeSkillReference(skillName));
+            }
+        }
+        catch (err) {
+            logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Heuristic auto-match (gated on skill_discovery: "auto").
+    // For each installed skill, check if its name or description appears in the
+    // unit's context tokens (milestone/slice/task titles). Only consider skills
+    // already on the unit-type manifest allowlist — this keeps the heuristic
+    // narrow and avoids wildly off-topic activations.
+    // Users who set `skill_discovery: "off"` or "suggest" do not get
+    // auto-matched skills (the recommendations block still surfaces manifest
+    // skills passively); only "auto" actually adds them to the activation
+    // directive set. Default `skill_discovery` is "suggest", so this is opt-in.
+    if ((prefs?.skill_discovery ?? "suggest") === "auto") {
+        for (const skill of manifestScopedSkills) {
+            const normalized = normalizeSkillReference(skill.name);
+            if (matched.has(normalized) || avoided.has(normalized))
+                continue;
+            if (skillMatchesContext(skill, contextTokens)) {
+                matched.add(normalized);
+            }
+        }
+    }
+    const ordered = [...matched]
+        .filter(name => installedNames.has(name) && !avoided.has(name))
+        .sort();
+    const activationBlock = formatSkillActivationBlock(ordered);
+    // Omit recommendations when the system catalog is manifest-scoped for this
+    // unit — skill names are already listed in <available_skills>.
+    let recommendationsBlock = "";
+    if (resolveSkillManifest(params.unitType) === null) {
+        const matchedSet = new Set(ordered);
+        const recommendations = (resolveSkillManifest(params.unitType) ?? [])
+            .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+            .sort();
+        recommendationsBlock = formatSkillRecommendationsBlock(params.unitType, recommendations);
+    }
+    if (!activationBlock && !recommendationsBlock)
+        return "";
+    if (!activationBlock)
+        return recommendationsBlock;
+    if (!recommendationsBlock)
+        return activationBlock;
+    return `${activationBlock}\n${recommendationsBlock}`;
+}
+/**
+ * Build the skill discovery template variables for research prompts.
+ * Returns { skillDiscoveryMode, skillDiscoveryInstructions } for template substitution.
+ */
+export function buildSkillDiscoveryVars() {
+    const mode = resolveSkillDiscoveryMode();
+    if (mode === "off") {
+        return {
+            skillDiscoveryMode: "off",
+            skillDiscoveryInstructions: " Skill discovery is disabled. Skip this step.",
+        };
+    }
+    if (mode === "suggest") {
+        return {
+            skillDiscoveryMode: mode,
+            skillDiscoveryInstructions: `
+   Check \`<available_skills>\` for installed skills matching core technologies. For gaps, run \`npx skills find "<technology>"\` and note promising install commands in your research output — do NOT install.`,
+        };
+    }
+    const autoInstall = mode === "auto";
+    const instructions = autoInstall
+        ? `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\`, install relevant matches with \`npx skills add <owner/repo@skill> -g -y\`, and record them in "Skills Discovered".`
+        : `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\` and note install commands in your research output — do NOT install.`;
+    return {
+        skillDiscoveryMode: mode,
+        skillDiscoveryInstructions: instructions,
+    };
+}