@planu/cli 4.4.1 → 4.4.3

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [4.4.3] - 2026-06-09
+
+### Features
+- feat(SPEC-1081): add skill security scan gate
+- feat(SPEC-1082): add implementation contract readiness
+
+
+## [4.4.2] - 2026-06-05
+
+### Bug Fixes
+- fix: keep spec folders spec.md-only and store evidence externally
+
+
 ## [4.4.1] - 2026-06-04
 
 ### Bug Fixes
@@ -4029,4 +4042,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/engine/evidence-gates/artifact-reader.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join } from 'node:path';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { projectDataDir } from '../../storage/base-store.js';
 const DiscoverySchema = z.object({
@@ -49,20 +49,6 @@ const ContractValidationSchema = z.object({
     reportPath: z.string().optional(),
     summary: z.string().optional(),
 });
-function resolveSpecPath(spec, projectPath) {
-    const specPath = spec.specPath;
-    if (!specPath?.trim()) {
-        return null;
-    }
-    if (isAbsolute(specPath) || !projectPath) {
-        return specPath;
-    }
-    return join(projectPath, specPath);
-}
-function specEvidencePath(spec, filename, projectPath) {
-    const specPath = resolveSpecPath(spec, projectPath);
-    return specPath ? join(dirname(specPath), 'evidence', filename) : null;
-}
 function handoffEvidencePath(projectId, specId, filename) {
     return join(projectDataDir(projectId), 'handoffs', specId, filename);
 }
@@ -108,28 +94,19 @@ export async function readEvidenceArtifacts(args) {
         label: 'Discovery evidence',
         invalidArtifacts,
         schema: DiscoverySchema,
-        paths: [
-            specEvidencePath(args.spec, 'discovery.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'discovery.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'discovery.json')],
     });
     const taskPlan = await readOptional({
         label: 'Task plan evidence',
         invalidArtifacts,
         schema: TaskPlanSchema,
-        paths: [
-            specEvidencePath(args.spec, 'task-plan.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'task-plan.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'task-plan.json')],
     });
     const traceabilityMatrix = await readOptional({
         label: 'Traceability matrix evidence',
         invalidArtifacts,
         schema: TraceabilityMatrixSchema,
-        paths: [
-            specEvidencePath(args.spec, 'traceability-matrix.json', args.projectPath),
-            handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json'),
-        ],
+        paths: [handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json')],
     });
     const contractValidations = [];
     for (const filename of [
@@ -143,10 +120,7 @@ export async function readEvidenceArtifacts(args) {
             label: filename,
             invalidArtifacts,
             schema: ContractValidationSchema,
-            paths: [
-                specEvidencePath(args.spec, filename, args.projectPath),
-                handoffEvidencePath(args.projectId, args.specId, filename),
-            ],
+            paths: [handoffEvidencePath(args.projectId, args.specId, filename)],
         });
         if (evidence) {
             contractValidations.push(evidence);

package/dist/engine/implementation-contract/common.d.ts

@@ -0,0 +1,5 @@
+export declare const IMPLEMENTATION_CONTRACT_SECTION = "Implementation Contract";
+export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ["User Outcome", "Behavior Contract", "File-Level Work Plan", "Acceptance-To-Verification Map", "Edge Cases And Failure Modes", "Non-Goals And Forbidden Approaches", "Verification Commands"];
+export declare function hasImplementationContract(specBody: string): boolean;
+export declare function extractTopLevelSection(body: string, sectionName: string): string;
+//# sourceMappingURL=common.d.ts.map

package/dist/engine/implementation-contract/common.js

@@ -0,0 +1,30 @@
+export const IMPLEMENTATION_CONTRACT_SECTION = 'Implementation Contract';
+export const IMPLEMENTATION_CONTRACT_SUBSECTIONS = [
+    'User Outcome',
+    'Behavior Contract',
+    'File-Level Work Plan',
+    'Acceptance-To-Verification Map',
+    'Edge Cases And Failure Modes',
+    'Non-Goals And Forbidden Approaches',
+    'Verification Commands',
+];
+export function hasImplementationContract(specBody) {
+    return extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION).trim().length > 0;
+}
+export function extractTopLevelSection(body, sectionName) {
+    const normalized = body.replace(/\r\n/g, '\n');
+    const headingRe = new RegExp(`^##\\s+${escapeRegex(sectionName)}[ \\t]*$`, 'm');
+    const match = headingRe.exec(normalized);
+    if (!match) {
+        return '';
+    }
+    const start = match.index + match[0].length;
+    const nextRe = /^##\s+\S/gm;
+    nextRe.lastIndex = start;
+    const next = nextRe.exec(normalized);
+    return normalized.slice(start, next ? next.index : normalized.length).trim();
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=common.js.map

package/dist/engine/implementation-contract/evaluator.d.ts

@@ -0,0 +1,3 @@
+import type { ImplementationContractIssue } from '../../types/index.js';
+export declare function evaluateImplementationContract(specBody: string, acceptanceCriteria: string[]): ImplementationContractIssue[];
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/engine/implementation-contract/evaluator.js

@@ -0,0 +1,105 @@
+import { extractTopLevelSection, IMPLEMENTATION_CONTRACT_SECTION, IMPLEMENTATION_CONTRACT_SUBSECTIONS, } from './common.js';
+const FILLER_PATTERNS = [
+    /\bTBD\b/i,
+    /\bN\/A\b/i,
+    /\bimplement correctly\b/i,
+    /\bhandle errors\b/i,
+    /\bto be determined\b/i,
+];
+export function evaluateImplementationContract(specBody, acceptanceCriteria) {
+    const contract = extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION);
+    if (contract.trim().length === 0) {
+        return [
+            {
+                code: 'contract_missing',
+                message: 'Implementation Contract is missing — add user outcome, behavior, file plan, verification map, edge cases, non-goals, and commands.',
+            },
+        ];
+    }
+    const issues = [];
+    const sections = new Map(IMPLEMENTATION_CONTRACT_SUBSECTIONS.map((section) => [
+        section,
+        extractSubsection(contract, section),
+    ]));
+    for (const [section, content] of sections.entries()) {
+        if (content === null) {
+            issues.push({
+                code: 'contract_subsection_missing',
+                message: `Implementation Contract subsection "${section}" is missing.`,
+            });
+            continue;
+        }
+        const trimmed = content.trim();
+        if (trimmed.length === 0) {
+            issues.push({
+                code: 'contract_subsection_empty',
+                message: `Implementation Contract subsection "${section}" is empty.`,
+            });
+        }
+        for (const pattern of FILLER_PATTERNS) {
+            if (pattern.test(trimmed)) {
+                issues.push({
+                    code: 'contract_filler',
+                    message: `Implementation Contract subsection "${section}" contains filler text.`,
+                });
+                break;
+            }
+        }
+        if (/\bNeeds decision:/i.test(trimmed)) {
+            issues.push({
+                code: 'contract_needs_decision',
+                message: `Implementation Contract subsection "${section}" still has unresolved Needs decision items.`,
+            });
+        }
+    }
+    const map = sections.get('Acceptance-To-Verification Map') ?? '';
+    for (const criterion of acceptanceCriteria) {
+        if (!criterionHasVerification(criterion, map)) {
+            issues.push({
+                code: 'contract_unmapped_criterion',
+                message: `Acceptance criterion is not mapped to verification evidence: ${criterion}`,
+            });
+        }
+    }
+    if (/\bmanual verification\b/i.test(map) &&
+        !/\b(given|when|then|step|observe|click|run)\b/i.test(map)) {
+        issues.push({
+            code: 'contract_manual_verification_vague',
+            message: 'Manual verification in the Implementation Contract must include exact observable steps.',
+        });
+    }
+    return issues;
+}
+function extractSubsection(sectionBody, subsectionName) {
+    const headingRe = new RegExp(`^###\\s+${escapeRegex(subsectionName)}[ \\t]*$`, 'm');
+    const match = headingRe.exec(sectionBody);
+    if (!match) {
+        return null;
+    }
+    const start = match.index + match[0].length;
+    const nextRe = /^###\s+\S/gm;
+    nextRe.lastIndex = start;
+    const next = nextRe.exec(sectionBody);
+    return sectionBody.slice(start, next ? next.index : sectionBody.length);
+}
+function criterionHasVerification(criterion, map) {
+    const normalizedCriterion = normalize(criterion);
+    if (normalizedCriterion.length === 0) {
+        return true;
+    }
+    const short = normalizedCriterion.slice(0, 48);
+    const normalizedMap = normalize(map);
+    return (normalizedMap.includes(short) &&
+        /\b(unit test|integration test|cli\/tool result|typecheck\/lint command|snapshot\/golden fixture|manual verification|pnpm|vitest|test)\b/i.test(map));
+}
+function normalize(value) {
+    return value
+        .replace(/[`*_()[\]:]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/engine/implementation-contract/index.d.ts

@@ -0,0 +1,4 @@
+export * from './common.js';
+export * from './renderer.js';
+export * from './evaluator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/implementation-contract/index.js

@@ -0,0 +1,4 @@
+export * from './common.js';
+export * from './renderer.js';
+export * from './evaluator.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/implementation-contract/renderer.d.ts

@@ -0,0 +1,4 @@
+import type { ImplementationContractInput } from '../../types/index.js';
+export declare function buildImplementationContractSection(input: ImplementationContractInput): string;
+export declare function appendImplementationContractIfMissing(specBody: string, input: ImplementationContractInput): string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/engine/implementation-contract/renderer.js

@@ -0,0 +1,98 @@
+import { hasImplementationContract, IMPLEMENTATION_CONTRACT_SECTION } from './common.js';
+export function buildImplementationContractSection(input) {
+    const criteria = input.criteria.length > 0 ? input.criteria : fallbackCriteria();
+    const testFiles = input.files.test.map((file) => file.path);
+    const verificationCommands = input.verificationCommands.length > 0
+        ? input.verificationCommands
+        : ['pnpm typecheck', 'pnpm lint', 'pnpm test'];
+    const lines = [
+        `## ${IMPLEMENTATION_CONTRACT_SECTION}`,
+        '### User Outcome',
+        firstConcreteSentence(input.description) ??
+            'Needs decision: define the exact user-visible outcome this spec must deliver.',
+        '',
+        '### Behavior Contract',
+        ...renderBehaviorContract(criteria),
+        '- Inputs: use the user request and existing project conventions as the source of truth.',
+        '- Outputs: update canonical `spec.md` behavior without creating sidecar implementation docs.',
+        '- State changes: persist only the files and metadata required by the spec workflow.',
+        '- Errors: missing implementation detail must surface as `Needs decision:` instead of generic filler.',
+        '',
+        '### File-Level Work Plan',
+        ...renderFilePlan(input.files),
+        '',
+        '### Acceptance-To-Verification Map',
+        ...criteria.map((criterion, index) => renderVerificationRow(criterion.text, index + 1, testFiles, verificationCommands)),
+        '',
+        '### Edge Cases And Failure Modes',
+        '- Generated specs with too little context must use `Needs decision:` placeholders.',
+        '- Existing specs without this section must remain readable and must not be rewritten by readiness checks.',
+        '- A heading with filler text must not count as a usable implementation contract.',
+        '- Manual verification must include exact observable steps when no automated proof is practical.',
+        '',
+        '### Non-Goals And Forbidden Approaches',
+        ...renderNonGoals(input.outOfScope),
+        '',
+        '### Verification Commands',
+        ...verificationCommands.map((command) => `- \`${command}\``),
+        '',
+    ];
+    return lines.join('\n');
+}
+export function appendImplementationContractIfMissing(specBody, input) {
+    if (hasImplementationContract(specBody)) {
+        return specBody.endsWith('\n') ? specBody : `${specBody}\n`;
+    }
+    return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
+}
+function fallbackCriteria() {
+    return [
+        {
+            text: 'Needs decision: define at least one acceptance criterion with executable verification.',
+            done: false,
+        },
+    ];
+}
+function firstConcreteSentence(description) {
+    const body = description
+        .replace(/^---[\s\S]*?---/, '')
+        .replace(/^#{1,6}\s+.+$/gm, '')
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.length >= 24 && !line.startsWith('-'));
+    if (!body) {
+        return null;
+    }
+    return body.replace(/\s+/g, ' ').slice(0, 240);
+}
+function renderFilePlan(files) {
+    const lines = [];
+    for (const [label, entries] of [
+        ['Create', files.create],
+        ['Modify', files.modify],
+        ['Test', files.test],
+    ]) {
+        for (const entry of entries) {
+            lines.push(`- ${label}: \`${entry.path}\` (${entry.status})`);
+        }
+    }
+    return lines.length > 0 ? lines : ['- Needs decision: identify expected source and test files.'];
+}
+function renderBehaviorContract(criteria) {
+    return criteria.map((criterion, index) => `- Expected behavior AC${String(index + 1)}: ${criterion.text}`);
+}
+function renderVerificationRow(criterion, index, testFiles, commands) {
+    const test = testFiles[0];
+    if (test) {
+        return `- AC${String(index)}: ${criterion} -> unit test \`${test}\` plus \`${commands[0] ?? 'pnpm test'}\`.`;
+    }
+    return `- AC${String(index)}: ${criterion} -> Needs decision: choose unit test, integration test, CLI/tool result, snapshot/golden fixture, or exact manual verification.`;
+}
+function renderNonGoals(outOfScope) {
+    const base = [
+        '- Do not create durable sidecar implementation docs outside canonical `spec.md`.',
+        '- Do not treat headings or filler text as implementation-ready detail.',
+    ];
+    return outOfScope.length > 0 ? [...base, ...outOfScope.map((item) => `- ${item}`)] : base;
+}
+//# sourceMappingURL=renderer.js.map

package/dist/engine/readiness-checker.js

@@ -4,7 +4,8 @@ import { readSpecTechnicalSection } from './spec-format/read-technical-section.j
 import { stripFrontmatter } from './frontmatter-parser.js';
 import { loadReadinessConfig } from './readiness-config-loader.js';
 import { runEarsGate } from './ears-gate.js';
-import { findScenariosWithoutTests } from './validator/spec-compliance-runner.js';
+import { findScenariosWithoutTests, parseFrontmatterScenarios, } from './validator/spec-compliance-runner.js';
+import { evaluateImplementationContract } from './implementation-contract/index.js';
 // ── SPEC-784: Technical section quality constants ─────────────────────────────
 const TECHNICAL_MIN_CHARS = 500;
 // Detects "See technical.md", "See spec.md", or "See `<file>` technical.md" patterns
@@ -110,6 +111,14 @@ export function extractCriteriaLines(huContent) {
     }
     return criteria;
 }
+function frontmatterScenarioCriteria(raw) {
+    return parseFrontmatterScenarios(raw).map((scenario) => {
+        const tests = scenario.tests
+            ?.map((test) => `${test.path}${test.line !== undefined ? ` line ${String(test.line)}` : ''}`)
+            .join(' ') ?? '';
+        return [scenario.title, tests].filter((part) => part.trim().length > 0).join(' ');
+    });
+}
 function scoreCriteria(criteriaLines, vagueWords) {
     const blockers = [];
     const warnings = [];
@@ -397,10 +406,8 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     // When a spec uses BDD format, acceptance criteria are stored as `scenarios:` in
     // the YAML frontmatter (multi-line YAML that the simple KV parser cannot handle).
     // If no criteria were found in the body, fall back to counting frontmatter scenarios.
-    const scenarioCount = criteriaLines.length === 0 ? countFrontmatterScenarios(huRaw) : 0;
-    const effectiveCriteriaLines = scenarioCount > 0
-        ? Array.from({ length: scenarioCount }).fill('bdd-scenario')
-        : criteriaLines;
+    const scenarioCriteria = criteriaLines.length === 0 ? frontmatterScenarioCriteria(huRaw) : [];
+    const effectiveCriteriaLines = scenarioCriteria.length > 0 ? scenarioCriteria : criteriaLines;
     const hu = scoreHuCompleteness(spec);
     const criteria = scoreCriteria(effectiveCriteriaLines, vagueWords);
     const files = scoreFilesIdentified(spec, fichaContent);
@@ -416,6 +423,11 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
         ...earsBlockers,
     ];
     const allWarnings = [...hu.warnings, ...criteria.warnings, ...files.warnings, ...deps.warnings];
+    if (mode === 'strict' && spec.scope !== 'trivial' && spec.difficulty >= 3) {
+        for (const issue of evaluateImplementationContract(huContent, effectiveCriteriaLines)) {
+            allBlockers.push(`${issue.code}: ${issue.message}`);
+        }
+    }
     // SPEC-732: Executable AC gate — block approved when any scenario lacks a `tests` array.
     // Only enforce when the spec uses frontmatter scenarios (BDD format).
     const bddScenarioCount = countFrontmatterScenarios(huRaw);
@@ -436,7 +448,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     }
     // SPEC-629: Specificity gate caps score at 60 for difficulty >= 3 specs that lack
     // concrete file paths, function names, or anticipated test breaks.
-    const specificityBlockers = checkSpecificityGate(spec, criteriaLines, fichaContent);
+    const specificityBlockers = checkSpecificityGate(spec, effectiveCriteriaLines, fichaContent);
     allBlockers.push(...specificityBlockers);
     const effectiveScore = specificityBlockers.length > 0 && spec.difficulty >= 3 ? Math.min(totalScore, 60) : totalScore;
     const breakdown = {

package/dist/engine/skill-registry/index.d.ts

@@ -1,5 +1,6 @@
 export { searchAllRegistries } from './unified-search.js';
 export { installSkill, isSkillInstalled, readSkillManifest } from './installer.js';
+export { scanSkillSecurity } from './skill-security-scanner.js';
 export { searchAnthropicSkills, fetchAnthropicSkillContent, clearAnthropicCache, } from './anthropic-adapter.js';
 export { searchSkillsSh } from './skillssh-adapter.js';
 export { searchAgentSkills } from './agentskill-adapter.js';

package/dist/engine/skill-registry/index.js

@@ -1,6 +1,7 @@
 // engine/skill-registry/index.ts — Barrel for skill registry engine (SPEC-150)
 export { searchAllRegistries } from './unified-search.js';
 export { installSkill, isSkillInstalled, readSkillManifest } from './installer.js';
+export { scanSkillSecurity } from './skill-security-scanner.js';
 export { searchAnthropicSkills, fetchAnthropicSkillContent, clearAnthropicCache, } from './anthropic-adapter.js';
 export { searchSkillsSh } from './skillssh-adapter.js';
 export { searchAgentSkills } from './agentskill-adapter.js';

package/dist/engine/skill-registry/installer.d.ts

@@ -1,4 +1,4 @@
-import type { SkillInstallResult, SkillManifest } from '../../types/index.js';
+import type { SkillInstallOptions, SkillInstallResult, SkillManifest } from '../../types/index.js';
 /**
  * Read the skill manifest from disk.
  * Returns an empty manifest if the file does not exist or cannot be parsed.
@@ -18,5 +18,5 @@ export declare function isSkillInstalled(projectPath: string, skillName: string)
  *  4. Update the local manifest.
  *  5. Return the install result with security flags.
  */
-export declare function installSkill(skillName: string, source: string, projectPath: string): Promise<SkillInstallResult>;
+export declare function installSkill(skillName: string, source: string, projectPath: string, options?: SkillInstallOptions): Promise<SkillInstallResult>;
 //# sourceMappingURL=installer.d.ts.map

package/dist/engine/skill-registry/installer.js

@@ -3,10 +3,13 @@
 // Manages the local manifest (manifest.json) tracking all installed skills.
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import * as os from 'node:os';
 import { fetchAnthropicSkillContent } from './anthropic-adapter.js';
 import { getBuiltInSkillEntry } from './builtin-catalog-adapter.js';
+import { scanSkillSecurity } from './skill-security-scanner.js';
 const SKILLS_DIR = '.claude/skills';
 const MANIFEST_FILE = 'manifest.json';
+const BLOCKING_SEVERITIES = new Set(['HIGH', 'CRITICAL']);
 /** Return the absolute path to the project's skills directory. */
 function skillsRoot(projectPath) {
     return path.join(projectPath, SKILLS_DIR);
@@ -48,18 +51,15 @@ function upsertManifestEntry(manifest, entry) {
         : [...manifest.skills, entry];
     return { ...manifest, skills };
 }
-/** Install a skill from the Anthropic (GitHub) source. */
-async function installFromAnthropic(skillName, installDir) {
+/** Prepare a skill from the Anthropic (GitHub) source. */
+async function prepareFromAnthropic(skillName) {
     const content = await fetchAnthropicSkillContent(skillName);
     if (!content) {
         throw new Error(`Skill "${skillName}" not found in the Anthropic skills repository. ` +
             'Check the skill name and try again.');
     }
-    await fs.mkdir(installDir, { recursive: true });
-    const skillMdPath = path.join(installDir, 'SKILL.md');
-    await fs.writeFile(skillMdPath, content.skillMd, 'utf-8');
     const hasScripts = content.files.some((f) => f.startsWith('scripts/') || f === 'scripts');
-    return { filesWritten: [skillMdPath], hasScripts };
+    return { content: content.skillMd, hasScripts };
 }
 /** Build a YAML frontmatter block for a skill entry if model/effort are defined. */
 function buildFrontmatter(entry) {
@@ -76,10 +76,9 @@ function buildFrontmatter(entry) {
     lines.push('---', '');
     return lines.join('\n');
 }
-/** Install a built-in skill from the local catalog, generating a SKILL.md. */
-async function installFromBuiltIn(skillName, installDir) {
+/** Prepare a built-in skill from the local catalog, generating a SKILL.md. */
+function prepareFromBuiltIn(skillName) {
     const entry = getBuiltInSkillEntry(skillName);
-    await fs.mkdir(installDir, { recursive: true });
     let content;
     if (entry) {
         const frontmatter = buildFrontmatter(entry);
@@ -109,13 +108,10 @@ async function installFromBuiltIn(skillName, installDir) {
             `Consult the Planu documentation.`,
         ].join('\n');
     }
-    const skillMdPath = path.join(installDir, 'SKILL.md');
-    await fs.writeFile(skillMdPath, content, 'utf-8');
-    return { filesWritten: [skillMdPath], hasScripts: false };
+    return { content, hasScripts: false };
 }
-/** Install a skill placeholder for skillssh/agentskill sources (no direct file API yet). */
-async function installFromExternal(skillName, source, installDir) {
-    await fs.mkdir(installDir, { recursive: true });
+/** Prepare a skill placeholder for skillssh/agentskill sources (no direct file API yet). */
+function prepareFromExternal(skillName, source) {
     const placeholder = [
         `# ${skillName}`,
         '',
@@ -124,9 +120,55 @@ async function installFromExternal(skillName, source, installDir) {
         '',
         'Run `planu registry install` again to refresh this skill.',
     ].join('\n');
+    return { content: placeholder, hasScripts: false };
+}
+function shouldScanSource(source) {
+    return source !== 'builtin';
+}
+async function writePreparedSkill(prepared, installDir) {
+    await fs.mkdir(installDir, { recursive: true });
     const skillMdPath = path.join(installDir, 'SKILL.md');
-    await fs.writeFile(skillMdPath, placeholder, 'utf-8');
-    return { filesWritten: [skillMdPath], hasScripts: false };
+    await fs.writeFile(skillMdPath, prepared.content, 'utf-8');
+    return {
+        filesWritten: [skillMdPath],
+        hasScripts: prepared.hasScripts,
+        version: prepared.version,
+    };
+}
+async function scanPreparedSkill(prepared, skillName, source, options) {
+    if (!shouldScanSource(source)) {
+        return undefined;
+    }
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'planu-skill-scan-'));
+    try {
+        await fs.writeFile(path.join(tempDir, 'SKILL.md'), prepared.content, 'utf-8');
+        const scan = await scanSkillSecurity(tempDir, skillName);
+        if (BLOCKING_SEVERITIES.has(scan.severity) || scan.recommendation === 'DO_NOT_INSTALL') {
+            throw new Error(`Skill "${skillName}" blocked by security scan: ${scan.severity} risk, recommendation ${scan.recommendation}.`);
+        }
+        return scan;
+    }
+    catch (err) {
+        if (options.scannerUnavailablePolicy === 'allow' &&
+            err instanceof Error &&
+            err.name === 'SkillSecurityScannerUnavailableError') {
+            return {
+                scanner: 'skillspector',
+                scannedAt: new Date().toISOString(),
+                score: 100,
+                severity: 'UNKNOWN',
+                recommendation: 'UNKNOWN',
+                issuesCount: 0,
+                command: 'skillspector scan <skillDir> --no-llm --format json',
+                available: false,
+                error: err.message,
+            };
+        }
+        throw err;
+    }
+    finally {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    }
 }
 /**
  * Install a skill from the specified source into the project's .claude/skills/ directory.
@@ -138,27 +180,15 @@ async function installFromExternal(skillName, source, installDir) {
  *  4. Update the local manifest.
  *  5. Return the install result with security flags.
  */
-export async function installSkill(skillName, source, projectPath) {
+export async function installSkill(skillName, source, projectPath, options = {}) {
     const installDir = path.join(skillsRoot(projectPath), skillName);
-    let filesWritten;
-    let hasScripts;
-    let version;
-    if (source === 'anthropic') {
-        const result = await installFromAnthropic(skillName, installDir);
-        filesWritten = result.filesWritten;
-        hasScripts = result.hasScripts;
-        version = result.version;
-    }
-    else if (source === 'builtin') {
-        const result = await installFromBuiltIn(skillName, installDir);
-        filesWritten = result.filesWritten;
-        hasScripts = result.hasScripts;
-    }
-    else {
-        const result = await installFromExternal(skillName, source, installDir);
-        filesWritten = result.filesWritten;
-        hasScripts = result.hasScripts;
-    }
+    const prepared = source === 'anthropic'
+        ? await prepareFromAnthropic(skillName)
+        : source === 'builtin'
+            ? prepareFromBuiltIn(skillName)
+            : prepareFromExternal(skillName, source);
+    const securityScan = await scanPreparedSkill(prepared, skillName, source, options);
+    const { filesWritten, hasScripts, version } = await writePreparedSkill(prepared, installDir);
     const manifest = await readSkillManifest(projectPath);
     const entry = {
         name: skillName,
@@ -166,6 +196,7 @@ export async function installSkill(skillName, source, projectPath) {
         version,
         installedAt: new Date().toISOString(),
         path: installDir,
+        securityScan,
     };
     await writeSkillManifest(projectPath, upsertManifestEntry(manifest, entry));
     return {
@@ -175,6 +206,7 @@ export async function installSkill(skillName, source, projectPath) {
         filesWritten,
         hasScripts,
         version,
+        securityScan,
     };
 }
 //# sourceMappingURL=installer.js.map

package/dist/engine/skill-registry/skill-security-scanner.d.ts

@@ -0,0 +1,12 @@
+import type { SkillSecurityScanResult } from '../../types/index.js';
+export declare class SkillSecurityScannerUnavailableError extends Error {
+    constructor(skillName: string, cause: unknown);
+}
+/**
+ * Scan a prepared skill directory using SkillSpector static analysis only.
+ *
+ * SkillSpector returns exit code 1 for high-risk reports. Planu still parses stdout
+ * in that case because the report is valid and should drive the gate decision.
+ */
+export declare function scanSkillSecurity(skillDir: string, skillName: string): Promise<SkillSecurityScanResult>;
+//# sourceMappingURL=skill-security-scanner.d.ts.map