frontend-harness 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `frontend-harness` are documented here.
+
+This project follows semver while it is pre-1.0: patch releases may include harness policy improvements that tighten validation, and minor releases may change generated protocol expectations.
+
+## 0.3.2 - 2026-05-20
+
+### Fixed
+
+- Fixed the npm package contents so CLI runtime dependencies such as `dist/runtime/skills.js` are included in published tarballs.
+- Added package-output regression coverage for required runtime files used by the CLI.
+
+## 0.3.1 - 2026-05-20
+
+### Known Issue
+
+- The published npm tarball is missing `dist/runtime/skills.js`, which can make `npx frontend-harness ...` fail with `ERR_MODULE_NOT_FOUND`. Use `0.3.2` or newer.
+
+### Added
+
+- Added structured UI verification evidence gating through `.frontend-harness/verification/evidence.json`.
+- Added shared task-signal detection for workflow routing, source-root selection, and component role inference.
+- Added execution-boundary tracking for accepted agent `planningEvidence.targetCandidates`.
+- Added warnings for low-confidence target candidates that are ignored during planning.
+- Added PRD knowledge frontmatter drift detection.
+- Added UI restoration checklist parity coverage.
+
+### Changed
+
+- Tightened Pixso/MCP/HTML UI workflow detection to avoid classifying generic MCP or HTML maintenance work as UI implementation.
+- Improved page/table/form component placement so page orchestration and child components can land in role-appropriate roots.
+- Improved multi-page execution-unit dependency wiring.
+- Changed UI verification evidence from advisory plan metadata into a verify-time gate.
+- Clarified generated protocol guidance for agent proposal envelopes and state tracking.
+
+### Fixed
+
+- Fixed Unicode-heavy UI task names colliding through empty PascalCase names.
+- Fixed UI implementation fallback classification for unrecognized tasks.
+- Fixed duplicated UI restoration guidance drift across planner/protocol/scaffold text.
+- Fixed malformed knowledge-card rendering where `verification` could be nested under `tags`.

package/README.md

@@ -344,3 +344,13 @@ npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run
 ```
 
 The temporary npm cache avoids local global-cache permission issues on machines where `~/.npm` contains root-owned files.
+
+Release checklist:
+
+```bash
+npm run verify
+npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run
+npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --pack-destination /tmp
+```
+
+Update `CHANGELOG.md` before publishing, then install the generated tarball in a temporary consumer project and run `npx frontend-harness --help` plus scaffold dry-run. See `docs/RELEASE.md` for the full npm release process.

package/dist/runtime/common/parsing.d.ts

@@ -0,0 +1,11 @@
+export interface BoundedStringOptions {
+    prefix: string;
+    maxLength?: number;
+}
+export interface StringArrayOptions extends BoundedStringOptions {
+    minItems?: number;
+    maxItems?: number;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseBoundedString(value: unknown, label: string, options: BoundedStringOptions): string;
+export declare function parseStringArray(value: unknown, label: string, options: StringArrayOptions): string[];

package/dist/runtime/common/parsing.js

@@ -0,0 +1,30 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function parseBoundedString(value, label, options) {
+    const maxLength = options.maxLength ?? 500;
+    if (typeof value !== "string") {
+        throw new Error(`${options.prefix} ${label} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`${options.prefix} ${label} cannot be empty`);
+    }
+    if (trimmed.length > maxLength) {
+        throw new Error(`${options.prefix} ${label} cannot exceed ${maxLength} characters`);
+    }
+    return trimmed;
+}
+export function parseStringArray(value, label, options) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${options.prefix} ${label} must be an array of strings`);
+    }
+    if (options.minItems !== undefined && value.length < options.minItems) {
+        throw new Error(`${options.prefix} ${label} must contain at least ${options.minItems} item`);
+    }
+    if (options.maxItems !== undefined && value.length > options.maxItems) {
+        throw new Error(`${options.prefix} ${label} cannot contain more than ${options.maxItems} items`);
+    }
+    return value.map((item, index) => parseBoundedString(item, `${label}[${index}]`, options));
+}
+//# sourceMappingURL=parsing.js.map

package/dist/runtime/common/parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.js","sourceRoot":"","sources":["../../../src/runtime/common/parsing.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc,EAAE,KAAa,EAAE,OAA6B;IAC7F,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,mBAAmB,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,kBAAkB,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,kBAAkB,SAAS,aAAa,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,KAAa,EAAE,OAA2B;IACzF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,8BAA8B,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,0BAA0B,OAAO,CAAC,QAAQ,OAAO,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,6BAA6B,OAAO,CAAC,QAAQ,QAAQ,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7F,CAAC"}

package/dist/runtime/project-discovery.d.ts

@@ -0,0 +1,17 @@
+export interface DetectedStack {
+    packageManager: string;
+    framework: string;
+    language: string;
+}
+export interface ProjectSurface {
+    sourceRoots: string[];
+    entryFiles: string[];
+    fileExtensions: string[];
+}
+export declare function detectProjectStack(projectRoot: string): DetectedStack;
+export declare function discoverProjectSurface(projectRoot: string): ProjectSurface;
+export declare function resolveComponentPlacement(projectRoot: string, scope: string): {
+    sourceRoot: string;
+    extension: string;
+};
+export declare function chooseComponentExtension(fileExtensions: string[], stack: DetectedStack): string;

package/dist/runtime/project-discovery.js

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import path from "node:path";
+import { hasRoleSignal } from "./task-signals.js";
+const SOURCE_ROOT_CANDIDATES = [
+    "src/pages",
+    "src/app",
+    "src/components",
+    "src/views",
+    "src/features",
+    "src",
+    "app",
+    "pages",
+    "components",
+    "views",
+    "features"
+];
+const ENTRY_FILE_CANDIDATES = [
+    "src/main.tsx",
+    "src/main.ts",
+    "src/main.jsx",
+    "src/main.js",
+    "src/index.tsx",
+    "src/index.ts",
+    "src/index.jsx",
+    "src/index.js",
+    "src/App.vue",
+    "src/App.tsx",
+    "src/App.ts",
+    "src/App.jsx",
+    "src/App.js",
+    "app/main.tsx",
+    "app/main.ts",
+    "app/main.jsx",
+    "app/main.js",
+    "app/page.tsx",
+    "app/page.ts",
+    "app/page.jsx",
+    "app/page.js"
+];
+const IGNORED_DIRECTORIES = new Set([
+    ".frontend-harness",
+    ".git",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    ".cache",
+    ".turbo"
+]);
+const EXTENSION_PRIORITY = [".vue", ".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs"];
+export function detectProjectStack(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, "package.json");
+    const packageJson = readPackageJson(packageJsonPath);
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    return {
+        packageManager: detectPackageManager(projectRoot, packageJson),
+        framework: deps["vite"]
+            ? "vite"
+            : deps["next"]
+                ? "next"
+                : deps["vue"]
+                    ? "vue"
+                    : deps["react"]
+                        ? "react"
+                        : "unknown",
+        language: deps["typescript"] || fs.existsSync(path.join(projectRoot, "tsconfig.json"))
+            ? "typescript"
+            : "unknown"
+    };
+}
+function readPackageJson(packageJsonPath) {
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    try {
+        return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function discoverProjectSurface(projectRoot) {
+    const sourceRoots = SOURCE_ROOT_CANDIDATES.filter((candidate) => directoryHasFiles(path.join(projectRoot, candidate)));
+    const entryFiles = ENTRY_FILE_CANDIDATES.filter((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
+    const fileExtensions = EXTENSION_PRIORITY.filter((extension) => sourceRoots.some((root) => hasExtensionInDirectory(path.join(projectRoot, root), extension)));
+    return {
+        sourceRoots,
+        entryFiles,
+        fileExtensions
+    };
+}
+export function resolveComponentPlacement(projectRoot, scope) {
+    const stack = detectProjectStack(projectRoot);
+    const surface = discoverProjectSurface(projectRoot);
+    return {
+        sourceRoot: chooseSourceRoot(surface.sourceRoots, scope),
+        extension: chooseComponentExtension(surface.fileExtensions, stack)
+    };
+}
+export function chooseComponentExtension(fileExtensions, stack) {
+    for (const extension of EXTENSION_PRIORITY) {
+        if (fileExtensions.includes(extension)) {
+            return extension;
+        }
+    }
+    if (stack.framework === "vue") {
+        return ".vue";
+    }
+    if (stack.framework === "react") {
+        return ".tsx";
+    }
+    if (stack.language === "typescript") {
+        return ".tsx";
+    }
+    return ".js";
+}
+function chooseSourceRoot(sourceRoots, scope) {
+    if (sourceRoots.length === 0) {
+        return "src";
+    }
+    const preferComponentRoots = hasRoleSignal(scope, "component") || hasRoleSignal(scope, "form") || hasRoleSignal(scope, "table");
+    const preferPageRoots = hasRoleSignal(scope, "page");
+    const preferredRoots = preferComponentRoots
+        ? sourceRoots.filter((root) => root.includes("components") || root.includes("widgets"))
+        : preferPageRoots
+            ? sourceRoots.filter((root) => root.includes("pages") || root.includes("app") || root.includes("views") || root.includes("features"))
+            : [];
+    return preferredRoots[0] ?? sourceRoots[0] ?? "src";
+}
+function detectPackageManager(projectRoot, packageJson) {
+    const declared = packageJson.packageManager?.split("@", 1)[0];
+    if (declared && ["npm", "pnpm", "yarn", "bun"].includes(declared)) {
+        return declared;
+    }
+    if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) {
+        return "yarn";
+    }
+    if (fs.existsSync(path.join(projectRoot, "bun.lock")) || fs.existsSync(path.join(projectRoot, "bun.lockb"))) {
+        return "bun";
+    }
+    if (fs.existsSync(path.join(projectRoot, "package-lock.json"))) {
+        return "npm";
+    }
+    return "unknown";
+}
+function directoryHasFiles(directory) {
+    return listFiles(directory, 4).length > 0;
+}
+function hasExtensionInDirectory(directory, extension) {
+    return listFiles(directory, 4).some((file) => file.endsWith(extension));
+}
+function listFiles(directory, maxDepth, depth = 0) {
+    if (!fs.existsSync(directory) || depth > maxDepth) {
+        return [];
+    }
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+            files.push(...listFiles(fullPath, maxDepth, depth + 1));
+            continue;
+        }
+        files.push(fullPath);
+    }
+    return files;
+}
+//# sourceMappingURL=project-discovery.js.map

package/dist/runtime/project-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-discovery.js","sourceRoot":"","sources":["../../src/runtime/project-discovery.ts"],"names":[],"mappings":"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"}

package/dist/runtime/skills.d.ts

@@ -0,0 +1,19 @@
+export interface ProjectSkill {
+    name: string;
+    title: string;
+    description: string | null;
+    path: string;
+    triggers?: string[];
+    intents?: string[];
+    examples?: string[];
+}
+export type SkillCheckStatus = "passed" | "failed" | "not_configured";
+export interface SkillCheckResult {
+    status: SkillCheckStatus;
+    skillsRoot: string;
+    skillCount: number;
+    errors: string[];
+    warnings: string[];
+}
+export declare function discoverSkills(projectRoot: string): ProjectSkill[];
+export declare function checkSkills(projectRoot: string): SkillCheckResult;

package/dist/runtime/skills.js

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+import { harnessPath } from "../storage/paths.js";
+export function discoverSkills(projectRoot) {
+    const skillsRoot = harnessPath(projectRoot, "skills");
+    if (!isReadableDirectory(skillsRoot)) {
+        return [];
+    }
+    return listMarkdownFiles(skillsRoot)
+        .flatMap((fullPath) => {
+        const skill = describeSkill(projectRoot, fullPath);
+        return skill ? [skill] : [];
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function checkSkills(projectRoot) {
+    const skillsRoot = harnessPath(projectRoot, "skills");
+    const relativeSkillsRoot = path.relative(projectRoot, skillsRoot).split(path.sep).join(path.posix.sep);
+    if (!fs.existsSync(skillsRoot)) {
+        return {
+            status: "not_configured",
+            skillsRoot: relativeSkillsRoot,
+            skillCount: 0,
+            errors: [],
+            warnings: ["Create .frontend-harness/skills before checking project-local skills."]
+        };
+    }
+    const errors = [];
+    const warnings = [];
+    if (!isReadableDirectory(skillsRoot)) {
+        errors.push(".frontend-harness/skills must be a readable directory.");
+    }
+    const skillFiles = isReadableDirectory(skillsRoot) ? listMarkdownFiles(skillsRoot, errors) : [];
+    const names = new Set();
+    const duplicateNames = new Set();
+    for (const fullPath of skillFiles) {
+        const relativePath = path.relative(projectRoot, fullPath).split(path.sep).join(path.posix.sep);
+        const skillPath = path.relative(skillsRoot, fullPath);
+        const name = slugFromSkillPath(skillPath);
+        if (names.has(name)) {
+            duplicateNames.add(name);
+        }
+        names.add(name);
+        let content;
+        try {
+            content = fs.readFileSync(fullPath, "utf8");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${relativePath} cannot be read: ${message}`);
+            continue;
+        }
+        const title = extractTitle(content);
+        if (!title) {
+            errors.push(`${relativePath} must include a non-empty "# Title" heading.`);
+        }
+        if (!hasBodyGuidance(content)) {
+            errors.push(`${relativePath} must include non-empty body guidance after the title.`);
+        }
+    }
+    for (const duplicateName of duplicateNames) {
+        errors.push(`Duplicate project skill name: ${duplicateName}.`);
+    }
+    return {
+        status: errors.length > 0 ? "failed" : "passed",
+        skillsRoot: relativeSkillsRoot,
+        skillCount: skillFiles.length,
+        errors,
+        warnings
+    };
+}
+function describeSkill(projectRoot, fullPath) {
+    const relativePath = path.relative(projectRoot, fullPath).split(path.sep).join(path.posix.sep);
+    const skillsRoot = harnessPath(projectRoot, "skills");
+    const skillPath = path.relative(skillsRoot, fullPath);
+    let content;
+    try {
+        content = fs.readFileSync(fullPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const name = slugFromSkillPath(skillPath);
+    const title = extractTitle(content) ?? name;
+    const metadata = parseFrontmatter(content);
+    return {
+        name: metadata.name ?? name,
+        title: metadata.title ?? title,
+        description: metadata.description ?? extractDescription(content),
+        path: relativePath,
+        ...(metadata.triggers.length ? { triggers: metadata.triggers } : {}),
+        ...(metadata.intents.length ? { intents: metadata.intents } : {}),
+        ...(metadata.examples.length ? { examples: metadata.examples } : {})
+    };
+}
+function parseFrontmatter(content) {
+    const empty = {
+        triggers: [],
+        intents: [],
+        examples: []
+    };
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+        return empty;
+    }
+    const endIndex = content.search(/\r?\n---(?:\r?\n|$)/);
+    if (endIndex < 0) {
+        return empty;
+    }
+    const lines = content.slice(content.startsWith("---\r\n") ? 5 : 4, endIndex).split(/\r?\n/);
+    const result = {
+        triggers: [],
+        intents: [],
+        examples: []
+    };
+    let currentList = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const listItem = trimmed.match(/^-\s+(.+)$/);
+        if (listItem && currentList) {
+            const value = listItem[1];
+            if (value) {
+                result[currentList].push(unquoteScalar(value));
+            }
+            continue;
+        }
+        const pair = trimmed.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!pair) {
+            currentList = null;
+            continue;
+        }
+        const key = pair[1] ?? "";
+        const value = (pair[2] ?? "").trim();
+        if (key === "name" || key === "title" || key === "description") {
+            result[key] = unquoteScalar(value);
+            currentList = null;
+            continue;
+        }
+        if (key === "triggers" || key === "intents" || key === "examples") {
+            result[key] = parseListValue(value);
+            currentList = value ? null : key;
+            continue;
+        }
+        currentList = null;
+    }
+    return result;
+}
+function parseListValue(value) {
+    if (!value) {
+        return [];
+    }
+    const inline = value.match(/^\[(.*)\]$/);
+    if (!inline) {
+        return [unquoteScalar(value)];
+    }
+    return (inline[1] ?? "")
+        .split(",")
+        .map((item) => unquoteScalar(item.trim()))
+        .filter(Boolean);
+}
+function unquoteScalar(value) {
+    return value.replace(/^["']|["']$/g, "").trim();
+}
+function extractTitle(content) {
+    const line = content.split("\n").find((item) => item.startsWith("# "));
+    return line ? line.replace(/^#\s+/, "").trim() || null : null;
+}
+function extractDescription(content) {
+    const lines = content.split("\n");
+    const titleIndex = lines.findIndex((line) => line.startsWith("# "));
+    const body = lines
+        .slice(titleIndex >= 0 ? titleIndex + 1 : 0)
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("#") && !line.startsWith("- "));
+    return body ?? null;
+}
+function hasBodyGuidance(content) {
+    const lines = content.split("\n");
+    const titleIndex = lines.findIndex((line) => line.startsWith("# "));
+    return lines
+        .slice(titleIndex >= 0 ? titleIndex + 1 : 0)
+        .some((line) => {
+        const trimmed = line.trim();
+        return trimmed && !trimmed.startsWith("#");
+    });
+}
+function isReadableDirectory(directory) {
+    try {
+        return fs.statSync(directory).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function slugFromSkillPath(skillPath) {
+    const parsed = path.parse(skillPath);
+    const parts = skillPath.split(path.sep);
+    const nameParts = parsed.name.toLowerCase() === "skill"
+        ? parts.slice(0, -1)
+        : [...parts.slice(0, -1), parsed.name];
+    return nameParts.join("-")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "skill";
+}
+function listMarkdownFiles(directory, errors) {
+    try {
+        return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith(".")) {
+                    return [];
+                }
+                return listMarkdownFiles(fullPath, errors);
+            }
+            return entry.name.endsWith(".md") ? [fullPath] : [];
+        });
+    }
+    catch (error) {
+        if (errors) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`Cannot read .frontend-harness/skills: ${message}`);
+            return [];
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=skills.js.map

package/dist/runtime/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/runtime/skills.ts"],"names":[],"mappings":"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"}

package/dist/runtime/task-signals.d.ts

@@ -0,0 +1,24 @@
+export type ComponentRoleSignal = "page" | "table" | "form" | "component";
+export interface TaskSignalInput {
+    prd?: string;
+    ui?: string;
+}
+export interface TaskSignals {
+    hasAttachedUiSource: boolean;
+    hasUiImplementationSignal: boolean;
+    hasUiSource: boolean;
+    hasPrdSource: boolean;
+    hasPrdKnowledgeSignal: boolean;
+    hasReviewSignal: boolean;
+    hasBugSignal: boolean;
+    hasTestSignal: boolean;
+    hasApiSignal: boolean;
+    hasRequirementChange: boolean;
+    hasDocumentationSignal: boolean;
+    hasExplicitDocumentationTarget: boolean;
+    hasMaintenanceSignal: boolean;
+    hasRefactorSignal: boolean;
+    hasComponentPlacementSignal: boolean;
+}
+export declare function detectTaskSignals(scope: string, input?: TaskSignalInput): TaskSignals;
+export declare function hasRoleSignal(value: string, role: ComponentRoleSignal): boolean;

package/dist/runtime/task-signals.js

@@ -0,0 +1,47 @@
+export function detectTaskSignals(scope, input = {}) {
+    const normalized = scope.toLowerCase();
+    const hasAttachedUiSource = Boolean(input.ui);
+    const hasUiImplementationSignal = hasUiImplementationSourceSignal(normalized);
+    const hasUiSource = hasAttachedUiSource || /\b(ui)\b/.test(normalized) || hasUiImplementationSignal;
+    const hasPrdSource = Boolean(input.prd) || /\b(prd|product|requirement|requirements|knowledge|document)\b|\u4ea7\u54c1|\u9700\u6c42|\u77e5\u8bc6\u5e93|\u6587\u6863/.test(normalized);
+    const hasPrdKnowledgeSignal = hasPrdSource &&
+        (Boolean(input.prd) || /\b(prd|requirement|requirements|knowledge)\b|\u9700\u6c42|\u77e5\u8bc6\u5e93/.test(normalized)) &&
+        /\b(digest|distill|capture|index|knowledge|document|organize|summari[sz]e)\b|\u6c89\u6dc0|\u6574\u7406|\u7d22\u5f15|\u77e5\u8bc6\u5e93|\u63d0\u70bc|\u68b3\u7406|\u603b\u7ed3/.test(normalized);
+    return {
+        hasAttachedUiSource,
+        hasUiImplementationSignal,
+        hasUiSource,
+        hasPrdSource,
+        hasPrdKnowledgeSignal,
+        hasReviewSignal: /\b(review|code review|audit|handoff)\b|\u8bc4\u5ba1|\u4ee3\u7801\u5ba1\u67e5|\u5ba1\u67e5|\u5ba1\u6838|\u590d\u6838|\u4ea4\u4ed8/.test(normalized),
+        hasBugSignal: /\b(bug|fix|regression|error)\b|\u4fee\u590d|\u9519\u8bef|\u62a5\u9519|\u7f3a\u9677/.test(normalized),
+        hasTestSignal: /\b(e2e|integration test|test|playwright|vitest)\b|\u6d4b\u8bd5|\u7aef\u5230\u7aef|\u96c6\u6210\u6d4b\u8bd5/.test(normalized),
+        hasApiSignal: /\b(api|swagger|endpoint|interface|request|dto)\b|\u63a5\u53e3|\u8bf7\u6c42|\u5bf9\u63a5|\u8054\u8c03/.test(normalized),
+        hasRequirementChange: /\b(requirement changes?|changed [a-z0-9 -]*requirements?|update [a-z0-9 -]*requirements?|sync [a-z0-9 -]*requirements?)\b|\u9700\u6c42\u53d8\u66f4|\u53d8\u66f4\u9700\u6c42|\u540c\u6b65\u9700\u6c42/.test(normalized),
+        hasDocumentationSignal: /\b(readme|docs?|documentation|guide|manual|agents\.md|claude\.md)\b|\u6587\u6863|\u8bf4\u660e|\u6307\u5357/.test(normalized),
+        hasExplicitDocumentationTarget: /\b(readme|docs?|guide|manual|agents\.md|claude\.md)\b|\u6587\u6863|\u8bf4\u660e|\u6307\u5357/.test(normalized),
+        hasMaintenanceSignal: /\b(cli|runtime|config|package|script|scaffold|harness|protocol|workflow|planning|planner|resolver|policy|maintenance|refactor)\b|\u811a\u624b\u67b6|\u534f\u8bae|\u89c4\u5212|\u5206\u6d3e|\u7ef4\u62a4|\u91cd\u6784|\u51c6\u786e\u6027/.test(normalized),
+        hasRefactorSignal: /\brefactor\b|\u91cd\u6784/.test(normalized),
+        hasComponentPlacementSignal: hasRoleSignal(normalized, "component")
+    };
+}
+export function hasRoleSignal(value, role) {
+    const normalized = value.toLowerCase();
+    switch (role) {
+        case "page":
+            return /\b(page|screen|dashboard|view|route|layout|detail)\b|\u9875\u9762|\u754c\u9762|\u89c6\u56fe|\u770b\u677f/.test(normalized);
+        case "table":
+            return /\b(table|grid|list)\b|\u8868\u683c|\u5217\u8868|\u6e05\u5355/.test(normalized);
+        case "form":
+            return /\b(form|create|edit|filter|search|input|select|modal|dialog|button|widget|card)\b|\u8868\u5355|\u65b0\u589e|\u7f16\u8f91|\u7b5b\u9009|\u641c\u7d22|\u67e5\u8be2|\u8fc7\u6ee4|\u8f93\u5165|\u9009\u62e9|\u5f39\u7a97|\u6309\u94ae|\u5361\u7247/.test(normalized);
+        case "component":
+            return /\b(component|widget|card|modal|dialog|button|input|select)\b|\u7ec4\u4ef6|\u5361\u7247|\u5f39\u7a97|\u6309\u94ae|\u8f93\u5165|\u9009\u62e9/.test(normalized);
+    }
+}
+function hasUiImplementationSourceSignal(normalized) {
+    return (/\b(stitch|figma|pixso|dst|design|screenshot|selected|restore)\b|\u622a\u56fe|\u9009\u4e2d|\u8fd8\u539f|\u8bbe\u8ba1/.test(normalized) ||
+        /\b(?:pixso|figma|stitch)\s+mcp\b|\bmcp\s+(?:selected|selection|design|page|screen|ui)\b/.test(normalized) ||
+        /\bhtml\s+(?:mockup|prototype|design|screen|page|ui)\b|\b(?:restore|adapt|convert)\s+html\b/.test(normalized) ||
+        hasRoleSignal(normalized, "page"));
+}
+//# sourceMappingURL=task-signals.js.map

package/dist/runtime/task-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-signals.js","sourceRoot":"","sources":["../../src/runtime/task-signals.ts"],"names":[],"mappings":"AAyBA,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,QAAyB,EAAE;IAC1E,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,mBAAmB,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9C,MAAM,yBAAyB,GAAG,+BAA+B,CAAC,UAAU,CAAC,CAAC;IAC9E,MAAM,WAAW,GAAG,mBAAmB,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,yBAAyB,CAAC;IACpG,MAAM,YAAY,GAChB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,yHAAyH,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnK,MAAM,qBAAqB,GACzB,YAAY;QACZ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,8EAA8E,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvH,8KAA8K,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAElM,OAAO;QACL,mBAAmB;QACnB,yBAAyB;QACzB,WAAW;QACX,YAAY;QACZ,qBAAqB;QACrB,eAAe,EAAE,kIAAkI,CAAC,IAAI,CAAC,UAAU,CAAC;QACpK,YAAY,EAAE,oFAAoF,CAAC,IAAI,CAAC,UAAU,CAAC;QACnH,aAAa,EAAE,4GAA4G,CAAC,IAAI,CAAC,UAAU,CAAC;QAC5I,YAAY,EAAE,sGAAsG,CAAC,IAAI,CAAC,UAAU,CAAC;QACrI,oBAAoB,EAClB,sMAAsM,CAAC,IAAI,CAAC,UAAU,CAAC;QACzN,sBAAsB,EAAE,4GAA4G,CAAC,IAAI,CAAC,UAAU,CAAC;QACrJ,8BAA8B,EAAE,8FAA8F,CAAC,IAAI,CAAC,UAAU,CAAC;QAC/I,oBAAoB,EAClB,yOAAyO,CAAC,IAAI,CAAC,UAAU,CAAC;QAC5P,iBAAiB,EAAE,2BAA2B,CAAC,IAAI,CAAC,UAAU,CAAC;QAC/D,2BAA2B,EAAE,aAAa,CAAC,UAAU,EAAE,WAAW,CAAC;KACpE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,IAAyB;IACpE,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,0GAA0G,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrI,KAAK,OAAO;YACV,OAAO,8DAA8D,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzF,KAAK,MAAM;YACT,OAAO,+OAA+O,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1Q,KAAK,WAAW;YACd,OAAO,4IAA4I,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzK,CAAC;AACH,CAAC;AAED,SAAS,+BAA+B,CAAC,UAAkB;IACzD,OAAO,CACL,qHAAqH,CAAC,IAAI,CAAC,UAAU,CAAC;QACtI,yFAAyF,CAAC,IAAI,CAAC,UAAU,CAAC;QAC1G,4FAA4F,CAAC,IAAI,CAAC,UAAU,CAAC;QAC7G,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,CAClC,CAAC;AACJ,CAAC"}

package/dist/runtime/verification-commands.d.ts

@@ -0,0 +1,11 @@
+export declare const defaultVerificationCommandNames: readonly ["typecheck", "test", "build"];
+export type DefaultVerificationCommandName = typeof defaultVerificationCommandNames[number];
+export type VerificationCommandName = DefaultVerificationCommandName | string;
+export type VerificationCommandSource = "flag" | "config" | "package" | "none";
+export type VerificationCommandOverrides = Partial<Record<DefaultVerificationCommandName, string>>;
+export interface VerificationCommandDiscovery {
+    name: VerificationCommandName;
+    source: VerificationCommandSource;
+    command: string | null;
+}
+export declare function discoverVerificationCommands(projectRoot: string, overrides?: VerificationCommandOverrides): VerificationCommandDiscovery[];

package/dist/runtime/verification-commands.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { harnessPath } from "../storage/paths.js";
+import { readJson } from "../storage/json.js";
+import { isRecord } from "./common/parsing.js";
+export const defaultVerificationCommandNames = ["typecheck", "test", "build"];
+export function discoverVerificationCommands(projectRoot, overrides = {}) {
+    const config = readJson(harnessPath(projectRoot, "config.json")) ?? {};
+    const scripts = readPackageScripts(projectRoot);
+    const commands = defaultVerificationCommandNames.map((name) => {
+        const overrideCommand = overrides[name];
+        if (overrideCommand) {
+            return {
+                name,
+                source: "flag",
+                command: overrideCommand
+            };
+        }
+        const configCommand = config.verification?.[name];
+        if (configCommand) {
+            return {
+                name,
+                source: "config",
+                command: configCommand
+            };
+        }
+        if (scripts[name]) {
+            return {
+                name,
+                source: "package",
+                command: `npm run ${name}`
+            };
+        }
+        return {
+            name,
+            source: "none",
+            command: null
+        };
+    });
+    const customCommands = readCustomConfigCommands(config);
+    const defaultNames = new Set(defaultVerificationCommandNames);
+    const configuredNames = new Set(commands.map((entry) => entry.name));
+    for (const customCommand of customCommands) {
+        if (defaultNames.has(customCommand.name) || configuredNames.has(customCommand.name)) {
+            continue;
+        }
+        commands.push(customCommand);
+        configuredNames.add(customCommand.name);
+    }
+    return commands;
+}
+function readCustomConfigCommands(config) {
+    if (!Array.isArray(config.verification?.commands)) {
+        return [];
+    }
+    const commands = [];
+    const names = new Set();
+    for (const entry of config.verification.commands) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const name = typeof entry["name"] === "string" ? entry["name"].trim() : "";
+        const command = typeof entry["command"] === "string" ? entry["command"].trim() : "";
+        if (!isValidCommandName(name) || !command || names.has(name)) {
+            continue;
+        }
+        commands.push({
+            name,
+            source: "config",
+            command
+        });
+        names.add(name);
+    }
+    return commands;
+}
+function readPackageScripts(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    return packageJson.scripts ?? {};
+}
+function isValidCommandName(value) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9:_-]{0,79}$/.test(value);
+}
+//# sourceMappingURL=verification-commands.js.map

package/dist/runtime/verification-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-commands.js","sourceRoot":"","sources":["../../src/runtime/verification-commands.ts"],"names":[],"mappings":"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"}

package/dist/storage/json.d.ts

@@ -0,0 +1,5 @@
+export declare function ensureDir(dir: string): void;
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function writeJsonExclusive(filePath: string, value: unknown): void;
+export declare function readJson<T>(filePath: string): T | null;
+export declare function writeText(filePath: string, value: string): void;

package/dist/storage/json.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function writeJson(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export function writeJsonExclusive(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+}
+export function readJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeText(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, value, "utf8");
+}
+//# sourceMappingURL=json.js.map

package/dist/storage/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/storage/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAc;IACxD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,KAAc;IACjE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACtG,CAAC;AAED,MAAM,UAAU,QAAQ,CAAI,QAAgB;IAC1C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAM,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAa;IACvD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}

package/dist/storage/paths.d.ts

@@ -0,0 +1,3 @@
+export declare const HARNESS_DIR = ".frontend-harness";
+export declare function harnessPath(projectRoot: string, ...parts: string[]): string;
+export declare function relativeHarnessPath(...parts: string[]): string;

package/dist/storage/paths.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+export const HARNESS_DIR = ".frontend-harness";
+export function harnessPath(projectRoot, ...parts) {
+    return path.join(projectRoot, HARNESS_DIR, ...parts);
+}
+export function relativeHarnessPath(...parts) {
+    return path.posix.join(HARNESS_DIR, ...parts);
+}
+//# sourceMappingURL=paths.js.map

package/dist/storage/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAE/C,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,GAAG,KAAe;IACjE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAG,KAAe;IACpD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/docs/RELEASE.md

@@ -0,0 +1,97 @@
+# Release Process
+
+Use this checklist for every npm release of `frontend-harness`.
+
+## Preconditions
+
+- Work from a clean git tree except for the intended release changes.
+- Confirm `package.json` and `package-lock.json` have the same version.
+- Update `CHANGELOG.md` for the version being released.
+- Keep `package.json#files` aligned with the intended npm package contents.
+
+## Verification
+
+Run the full project gate:
+
+```bash
+npm run verify
+```
+
+Inspect the npm package contents before publishing:
+
+```bash
+npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run
+```
+
+The temporary npm cache avoids local global-cache permission issues on machines where `~/.npm` contains root-owned files.
+
+Confirm the dry-run output includes only intended public artifacts, normally:
+
+- `dist/**`
+- `README.md`
+- `CHANGELOG.md`
+- `docs/DIRECTION.md`
+- `docs/RELEASE.md`
+- `package.json`
+
+Create and smoke-test the exact tarball that will be published:
+
+```bash
+npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --pack-destination /tmp
+SMOKE_DIR="$(mktemp -d /tmp/frontend-harness-smoke-XXXXXX)"
+cd "$SMOKE_DIR"
+npm init -y
+npm install /tmp/frontend-harness-<version>.tgz --save-dev
+npx frontend-harness --help
+npx frontend-harness scaffold --preset vue --target my-vue-app --dry-run --json
+```
+
+The smoke test must run from a temporary consumer project, not from this source checkout. It catches missing published files such as `dist/runtime/*.js` imports before npm publish.
+
+## Versioning
+
+Use semver:
+
+- Patch: bug fixes, stricter gates, protocol guidance clarifications, and compatible planner improvements.
+- Minor: new commands, new public artifacts, or changed generated protocol expectations.
+- Major: reserved for post-1.0 breaking changes.
+
+For a version bump:
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+Use `minor` instead of `patch` when the release changes consumer-visible workflow contracts.
+
+## Publish
+
+After verification, tarball smoke testing, and review:
+
+```bash
+npm publish --access public
+```
+
+Then create a git commit and tag if they were not already created:
+
+```bash
+git add package.json package-lock.json CHANGELOG.md docs/RELEASE.md
+git commit -m "Release v<version>"
+git tag v<version>
+```
+
+Push the commit and tag:
+
+```bash
+git push
+git push origin v<version>
+```
+
+## Post-Publish Smoke Test
+
+In a temporary directory outside this repository, validate the published package by version:
+
+```bash
+npx frontend-harness@<version> --help
+npx frontend-harness@<version> scaffold --preset vue --target my-vue-app --dry-run --json
+```

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "frontend-harness",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "files": [
     "dist",
+    "docs/RELEASE.md",
     "docs/DIRECTION.md",
+    "CHANGELOG.md",
     "README.md"
   ],
   "bin": {