dreative 0.5.1 → 0.5.2

package/README.md

@@ -1,35 +1,57 @@
-# Dreative
+# Dreative
+
+Frontend design **skill for coding CLIs** (Claude Code, Codex, etc.) with an optional visual round-trip editor. By default the agent plans a design, selects specialist treatments, edits the real application directly, preserves existing behavior, and verifies the result. No server or extraction is involved in that mode.
 
-Visual round-trip UI editing **skill for coding CLIs** (Claude Code etc.). The CLI agent extracts your app's current UI page-by-page into editable wireframes; you tweak them in the browser (drag-drop, ref images, text prompts); clicking **Finish** hands a compact layout **diff** back to the agent, which rewrites your real code to match.
+Dreative itself has **no AI** — your coding agent is the intelligence. See `skill/dreative/SKILL.md` for the direct-design workflow and optional editor mode.
 
-Dreative itself has **no AI** — the web UI is a dumb visual editor plus a request queue. Your coding agent is the intelligence: it services UI prompts via `dreative wait` / `dreative respond` and applies the finish diff. See `skill/dreative/SKILL.md` for the agent workflow (install it into `.claude/skills/dreative/`).
+## Direct design (default)
 
-## Run
+Install the skill, then ask your coding agent to design or redesign a page. The skill provides:
 
-```sh
-npm install
-npm run build
-npm link          # once — makes the `dreative` command available globally
-```
-
-Then in any project folder:
+- four explicit ambition tiers, from solid product UI through award-site work;
+- ten composable specialist skills with dependency resolution;
+- user-approved multi-page skill routing with explicit per-page assignments;
+- a rule registry that separates hard gates, evidence-backed defaults, and
+  creative provocations, with audited substitutions for equally ambitious alternatives;
+- reflex-font review and diversity-or-development planning instead of fixed aesthetic recipes;
+- framework adapters for React/Vite, Next.js, Vue/Nuxt, SvelteKit, and styling systems;
+- typed plan, preservation, decision-ledger, and verification artifacts;
+- `dreative audit`, which checks delivery status, preservation, assets, evidence, and common frontend risks.
 
 ```sh
-dreative          # starts the local server and opens http://localhost:4820
+dreative install-skill --codex   # or omit --codex for Claude Code
+dreative audit                   # run after implementation
+dreative docs-check              # validate the packaged doctrine and references
 ```
 
-State lives in `.dreative/` in that folder (`project.json`, `refs/`, `generated/`).
-
-## Workflow
-
-1. **Extract** — the CLI agent reads your app and writes `.dreative/project.json` (wireframe per page, real labels, `source` pointers to owning files), then snapshots it: `dreative baseline`.
-2. **Tweak** — in the browser: drag blocks, add/remove/duplicate, attach reference images and prompts per page/block/element. Prompt-driven actions (propose layouts, block edits, design passes) are queued for your agent, which services them via `dreative wait` → `dreative respond`.
-3. **Finish** — click ✅ Finish; the agent receives only the diff vs the baseline (changed/moved/added/removed blocks + annotations) and applies it to the real codebase using the `source` pointers — token-efficient by construction.
-
-CLI: `dreative` / `dreative start` (server+UI) · `dreative install-skill` (copy skill into ./.claude/skills) · `dreative wait` (block for next UI event) · `dreative respond <id> [result.json|--error msg]` · `dreative baseline`.
-
-## Dev
-
-```sh
-npm run dev       # server on :4820 (tsx watch) + Vite UI on :5199 with proxy
-```
+The browser workflow below is optional and only used when explicitly requested.
+
+## Run
+
+```sh
+npm install
+npm run build
+npm link          # once — makes the `dreative` command available globally
+```
+
+Then in any project folder:
+
+```sh
+dreative          # starts the local server and opens http://localhost:4820
+```
+
+State lives in `.dreative/` in that folder (`project.json`, `refs/`, `generated/`).
+
+## Workflow
+
+1. **Extract** — the CLI agent reads your app and writes `.dreative/project.json` (wireframe per page, real labels, `source` pointers to owning files), then snapshots it: `dreative baseline`.
+2. **Tweak** — in the browser: drag blocks, add/remove/duplicate, attach reference images and prompts per page/block/element. Prompt-driven actions (propose layouts, block edits, design passes) are queued for your agent, which services them via `dreative wait` → `dreative respond`.
+3. **Finish** — click ✅ Finish; the agent receives only the diff vs the baseline (changed/moved/added/removed blocks + annotations) and applies it to the real codebase using the `source` pointers — token-efficient by construction.
+
+CLI: `dreative` / `dreative start` (server+UI) · `dreative install-skill` (copy skill into ./.claude/skills) · `dreative wait` (block for next UI event) · `dreative respond <id> [result.json|--error msg]` · `dreative baseline`.
+
+## Dev
+
+```sh
+npm run dev       # server on :4820 (tsx watch) + Vite UI on :5199 with proxy
+```

package/dist/cli/audit.js

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateDecisionLedger, validatePlan, validatePreservationManifest, validateVerificationReport, } from "../shared/artifacts.js";
+import { resolveSkillDependencies } from "../shared/skillSystem.js";
+import { validateRuleControls, } from "../shared/ruleSystem.js";
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+const packagedSkillDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skill", "dreative");
+function loadRuleFiles() {
+    return {
+        registry: readJson(path.join(packagedSkillDir, "references", "RULES.json")),
+        reflexFonts: readJson(path.join(packagedSkillDir, "references", "REFLEX_FONTS.json")),
+    };
+}
+function finding(level, check, message) {
+    return { level, check, message };
+}
+function checkArtifact(file, check, validate) {
+    if (!fs.existsSync(file))
+        return [finding("error", check, `missing ${path.basename(file)}`)];
+    try {
+        return validate(readJson(file)).map((message) => finding("error", check, message));
+    }
+    catch (error) {
+        return [finding("error", check, `cannot parse ${path.basename(file)}: ${String(error)}`)];
+    }
+}
+function checkPreservation(projectDir, manifestFile) {
+    const findings = checkArtifact(manifestFile, "preservation", validatePreservationManifest);
+    if (findings.some((item) => item.level === "error"))
+        return findings;
+    const manifest = readJson(manifestFile);
+    for (const item of manifest.items) {
+        if (item.intentionallyChanged)
+            continue;
+        const target = path.resolve(projectDir, item.file);
+        if (!target.startsWith(path.resolve(projectDir) + path.sep)) {
+            findings.push(finding("error", "preservation", `${item.id}: file escapes the project root`));
+            continue;
+        }
+        if (!fs.existsSync(target)) {
+            findings.push(finding("error", "preservation", `${item.id}: missing ${item.file}`));
+            continue;
+        }
+        if (!fs.readFileSync(target, "utf-8").includes(item.needle))
+            findings.push(finding("error", "preservation", `${item.id}: expected content is absent from ${item.file}`));
+    }
+    return findings;
+}
+function checkSkillClosure(plan) {
+    const findings = [];
+    const requested = plan.skills;
+    const missing = resolveSkillDependencies(requested).filter((skill) => !requested.includes(skill));
+    if (missing.length)
+        findings.push(finding("error", "skills", `missing required skill dependencies: ${missing.join(", ")}`));
+    for (const page of plan.pages) {
+        const pageMissing = resolveSkillDependencies(page.skills).filter((skill) => !page.skills.includes(skill));
+        if (pageMissing.length)
+            findings.push(finding("error", "skills", `${page.name} is missing dependencies: ${pageMissing.join(", ")}`));
+    }
+    return findings;
+}
+function checkAssets(projectDir, plan) {
+    const findings = [];
+    for (const page of plan.pages) {
+        for (const section of page.sections) {
+            for (const asset of section.assets) {
+                if (asset.status !== "shipped")
+                    continue;
+                const target = path.resolve(projectDir, asset.path);
+                if (!target.startsWith(path.resolve(projectDir) + path.sep) || !fs.existsSync(target))
+                    findings.push(finding("error", "assets", `${page.name}/${section.name}/${asset.id}: shipped asset missing at ${asset.path}`));
+            }
+        }
+    }
+    return findings;
+}
+const SOURCE_EXTENSIONS = new Set([".tsx", ".jsx", ".vue", ".svelte", ".html", ".css", ".scss"]);
+const SKIP_DIRS = new Set([".git", ".dreative", "node_modules", "dist", "build", ".next", ".nuxt"]);
+function collectSourceFiles(root, current = root) {
+    const files = [];
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const absolute = path.join(current, entry.name);
+        if (entry.isDirectory())
+            files.push(...collectSourceFiles(root, absolute));
+        else if (SOURCE_EXTENSIONS.has(path.extname(entry.name)))
+            files.push(absolute);
+    }
+    return files;
+}
+function checkStaticQuality(projectDir, plan) {
+    const findings = [];
+    const files = collectSourceFiles(projectDir);
+    let combined = "";
+    for (const file of files) {
+        const source = fs.readFileSync(file, "utf-8");
+        combined += `\n${source}`;
+        const relative = path.relative(projectDir, file);
+        for (const match of source.matchAll(/<img\b([^>]*?)>/gis)) {
+            const attributes = match[1];
+            if (!/\balt\s*=/.test(attributes))
+                findings.push(finding("error", "accessibility", `${relative}: image is missing alt`));
+            if (!/\b(width|height)\s*=/.test(attributes) && !/\baspect-/.test(attributes))
+                findings.push(finding("warning", "layout", `${relative}: image has no explicit dimensions or aspect token`));
+        }
+        if (/<(?:div|span)\b[^>]*\bonClick\s*=/is.test(source) && !/\b(role|tabIndex|onKeyDown)\s*=/is.test(source))
+            findings.push(finding("warning", "accessibility", `${relative}: non-semantic click target may lack keyboard support`));
+        if (/outline\s*:\s*none|outline-none/.test(source) && !/focus-visible/.test(source))
+            findings.push(finding("warning", "accessibility", `${relative}: focus outline is removed without a visible replacement`));
+        if (/href\s*=\s*["']#["']/.test(source))
+            findings.push(finding("warning", "navigation", `${relative}: placeholder href="#" remains`));
+    }
+    if (plan.skills.some((skill) => ["motion", "3d", "immersive", "cinematic", "experimental"].includes(skill))) {
+        if (!/prefers-reduced-motion|useReducedMotion|reducedMotion/i.test(combined))
+            findings.push(finding("error", "motion", "selected effects require an implemented reduced-motion path"));
+    }
+    return findings;
+}
+function checkVerificationProof(projectDir, verificationFile) {
+    if (!fs.existsSync(verificationFile))
+        return [];
+    let report;
+    try {
+        report = readJson(verificationFile);
+    }
+    catch {
+        return [];
+    }
+    const findings = [];
+    for (const item of report.evidence ?? []) {
+        const proof = item.proof;
+        if (!proof)
+            continue;
+        if (proof.artifactPath) {
+            const target = path.resolve(projectDir, proof.artifactPath);
+            if (!target.startsWith(path.resolve(projectDir) + path.sep))
+                findings.push(finding("error", "verification", `${item.id}: artifact path escapes the project root`));
+            else if (!fs.existsSync(target))
+                findings.push(finding("error", "verification", `${item.id}: evidence artifact is missing at ${proof.artifactPath}`));
+        }
+        if (proof.viewport && (proof.viewport.width <= 0 || proof.viewport.height <= 0 || (proof.viewport.dpr ?? 1) <= 0))
+            findings.push(finding("error", "verification", `${item.id}: viewport dimensions and DPR must be positive`));
+        if (typeof proof.averageFps === "number" && proof.averageFps <= 0)
+            findings.push(finding("error", "verification", `${item.id}: averageFps must be positive`));
+        if (typeof proof.maxFrameTimeMs === "number" && proof.maxFrameTimeMs < 0)
+            findings.push(finding("error", "verification", `${item.id}: maxFrameTimeMs cannot be negative`));
+    }
+    return findings;
+}
+export function runDirectDesignAudit(projectDir) {
+    const root = path.join(projectDir, ".dreative");
+    const planFile = path.join(root, "plan.json");
+    const findings = checkArtifact(planFile, "plan", validatePlan);
+    if (!fs.existsSync(planFile) || findings.some((item) => item.level === "error"))
+        return { ok: false, findings };
+    const plan = readJson(planFile);
+    const preservationFile = path.resolve(projectDir, plan.preservationManifest);
+    const ledgerFile = path.resolve(projectDir, plan.decisionLedger);
+    const verificationFile = path.join(root, "verify.json");
+    findings.push(...checkPreservation(projectDir, preservationFile));
+    findings.push(...checkArtifact(ledgerFile, "ledger", validateDecisionLedger));
+    findings.push(...checkArtifact(verificationFile, "verification", validateVerificationReport));
+    findings.push(...checkVerificationProof(projectDir, verificationFile));
+    if (plan.doctrineVersion !== 2) {
+        findings.push(finding("warning", "migration", "legacy v2 plan accepted; add doctrineVersion: 2 and the new creative-control fields on the next design run"));
+    }
+    else {
+        try {
+            const { registry, reflexFonts } = loadRuleFiles();
+            const verification = fs.existsSync(verificationFile) ? readJson(verificationFile) : undefined;
+            for (const message of validateRuleControls(plan, registry, reflexFonts, verification))
+                findings.push(finding("error", "rules", message));
+        }
+        catch (error) {
+            findings.push(finding("error", "rules", `cannot load rule registries: ${String(error)}`));
+        }
+    }
+    findings.push(...checkSkillClosure(plan));
+    findings.push(...checkAssets(projectDir, plan));
+    findings.push(...checkStaticQuality(projectDir, plan));
+    const verify = fs.existsSync(verificationFile) ? JSON.stringify(readJson(verificationFile)) : "";
+    for (const page of plan.pages) {
+        for (const section of page.sections) {
+            for (const criterion of section.verification) {
+                if (!verify.includes(criterion))
+                    findings.push(finding("warning", "verification", `${page.name}/${section.name}: no evidence references criterion: ${criterion}`));
+            }
+        }
+    }
+    return { ok: !findings.some((item) => item.level === "error"), findings };
+}
+export function printAudit(report, json) {
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (report.findings.length === 0)
+        console.log("Dreative audit passed with no findings.");
+    for (const item of report.findings)
+        console.log(`${item.level === "error" ? "ERROR" : "WARN "} [${item.check}] ${item.message}`);
+    console.log(report.ok ? "Dreative audit passed." : "Dreative audit failed.");
+}

package/dist/cli/audit.test.js

@@ -0,0 +1,79 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runDirectDesignAudit } from "./audit.js";
+test("direct-design audit verifies artifacts and preservation needles", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "dreative-audit-"));
+    try {
+        fs.mkdirSync(path.join(root, ".dreative"));
+        fs.mkdirSync(path.join(root, "src"));
+        fs.writeFileSync(path.join(root, "src", "App.tsx"), 'export const App = () => <a href="/pricing">Pricing</a>;');
+        fs.writeFileSync(path.join(root, ".dreative", "plan.json"), JSON.stringify({
+            version: 2,
+            request: "Polish pricing",
+            createdAt: new Date().toISOString(),
+            tier: "solid",
+            depth: "restyle",
+            skills: ["ux", "mobile"],
+            skillPolicy: { mode: "hybrid", global: ["ux", "mobile"], routingApproved: true, userAssignments: [] },
+            designRead: { register: "product", concept: "clear value", signature: "pricing rail" },
+            preservationManifest: ".dreative/preservation.json",
+            decisionLedger: ".dreative/ledger.json",
+            pages: [
+                {
+                    id: "pricing-page",
+                    name: "Pricing page",
+                    skills: ["ux", "mobile"],
+                    sections: [
+                        {
+                            id: "pricing",
+                            name: "Pricing",
+                            layoutFamily: "comparison",
+                            skills: ["ux", "mobile"],
+                            interactions: [],
+                            mobile: "stacked plans",
+                            fallback: "semantic table",
+                            verification: ["Pricing link remains"],
+                            assets: [],
+                            status: "shipped",
+                        },
+                    ],
+                },
+            ],
+        }));
+        fs.writeFileSync(path.join(root, ".dreative", "preservation.json"), JSON.stringify({
+            version: 1,
+            createdAt: new Date().toISOString(),
+            items: [{ id: "pricing-link", kind: "link", file: "src/App.tsx", needle: 'href="/pricing"', purpose: "Pricing navigation" }],
+        }));
+        fs.writeFileSync(path.join(root, ".dreative", "ledger.json"), JSON.stringify({ version: 1, entries: [] }));
+        fs.writeFileSync(path.join(root, ".dreative", "verify.json"), JSON.stringify({
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            evidence: [
+                {
+                    id: "pricing-link",
+                    criterion: "Pricing link remains",
+                    status: "pass",
+                    evidence: "Clicked /pricing in production build",
+                    proof: { timestamp: new Date().toISOString(), testedUrl: "http://localhost:3000/pricing", consoleErrorCount: 0 },
+                },
+            ],
+        }));
+        const report = runDirectDesignAudit(root);
+        assert.equal(report.ok, true, JSON.stringify(report.findings));
+        assert.ok(report.findings.some((item) => item.check === "migration" && item.level === "warning"));
+        const verifyFile = path.join(root, ".dreative", "verify.json");
+        const verify = JSON.parse(fs.readFileSync(verifyFile, "utf-8"));
+        verify.evidence[0].proof.artifactPath = ".dreative/screenshots/missing.png";
+        fs.writeFileSync(verifyFile, JSON.stringify(verify));
+        const missingArtifact = runDirectDesignAudit(root);
+        assert.equal(missingArtifact.ok, false);
+        assert.ok(missingArtifact.findings.some((item) => item.message.includes("evidence artifact is missing")));
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/cli/docsCheck.js

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_DEFINITIONS, resolveSkillDependencies } from "../shared/skillSystem.js";
+const UNIVERSAL_RULE = "Universal foundation: ux and baseline mobile apply to every web page.";
+const UNIVERSAL_FILES = ["SKILL.md", "references/SKILL_CONTRACT.md", "skills/ux.md", "skills/mobile.md"];
+const RUNTIME_MARKDOWN = new Set(["plan.md", "verify.md", "system.md", "ledger.md"]);
+function walk(root, current = root) {
+    return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+        const absolute = path.join(current, entry.name);
+        return entry.isDirectory() ? walk(root, absolute) : [path.relative(root, absolute).split(path.sep).join("/")];
+    });
+}
+function add(findings, check, file, message) {
+    findings.push({ check, file, message });
+}
+function resolveReference(skillDir, from, reference) {
+    if (reference.includes("<") ||
+        reference.includes(">") ||
+        reference.includes(".dreative/") ||
+        reference.includes(".dreative\\") ||
+        path.isAbsolute(reference) ||
+        RUNTIME_MARKDOWN.has(path.basename(reference)))
+        return true;
+    const candidates = [
+        path.resolve(skillDir, path.dirname(from), reference),
+        path.resolve(skillDir, reference),
+        path.resolve(skillDir, "skills", path.basename(reference)),
+        path.resolve(skillDir, "references", path.basename(reference)),
+        path.resolve(skillDir, "frameworks", path.basename(reference)),
+    ];
+    return candidates.some((candidate) => fs.existsSync(candidate));
+}
+export function runDocsCheck(skillDir) {
+    const findings = [];
+    const files = walk(skillDir).filter((file) => file.endsWith(".md") || file.endsWith(".json"));
+    const contents = new Map(files.map((file) => [file, fs.readFileSync(path.join(skillDir, file), "utf-8")]));
+    for (const [file, content] of contents) {
+        if (/^(<<<<<<<|=======|>>>>>>>)/m.test(content))
+            add(findings, "merge-markers", file, "contains unresolved merge markers");
+        if (/\bAskUserQuestion\b/.test(content))
+            add(findings, "obsolete-tool", file, "names AskUserQuestion instead of using tool-neutral wording");
+        if (file.endsWith(".md")) {
+            for (const match of content.matchAll(/`([^`\n]+\.md)`/g)) {
+                if (!resolveReference(skillDir, file, match[1]))
+                    add(findings, "references", file, `missing referenced file: ${match[1]}`);
+            }
+        }
+    }
+    const schemaFile = "schemas/plan.schema.json";
+    try {
+        const schema = JSON.parse(contents.get(schemaFile) ?? "{}");
+        const tiers = schema.properties?.tier?.enum ?? [];
+        const expected = ["solid", "premium", "expressive", "award"];
+        if (JSON.stringify(tiers) !== JSON.stringify(expected))
+            add(findings, "tiers", schemaFile, `tier enum must be ${expected.join(" | ")}`);
+        for (const file of ["SKILL.md", "PLAN.md", "references/ARTIFACTS.md", "references/TIERS.md"]) {
+            const content = contents.get(file) ?? "";
+            for (const tier of expected) {
+                if (!new RegExp(`\\b${tier}\\b`, "i").test(content))
+                    add(findings, "tiers", file, `does not mention canonical tier ${tier}`);
+            }
+        }
+        const plan = contents.get("PLAN.md") ?? "";
+        for (const tier of expected) {
+            if (!plan.includes(`(\`${tier}\`)`))
+                add(findings, "tiers", "PLAN.md", `choice label must expose stored id (${tier})`);
+        }
+        if (/\*\*(safe|award-site)\*\*/i.test(plan))
+            add(findings, "tiers", "PLAN.md", "contains a legacy tier choice label");
+    }
+    catch (error) {
+        add(findings, "tiers", schemaFile, `cannot parse tier schema: ${String(error)}`);
+    }
+    for (const skill of ["media", "motion", "3d", "immersive", "cinematic"]) {
+        const specialist = `skills/${skill}.md`;
+        const recipe = `recipes/${skill}-recipes.md`;
+        if (!contents.has(recipe))
+            add(findings, "recipes", recipe, "recipe reference is missing");
+        if (!(contents.get(specialist) ?? "").includes(`../${recipe}`))
+            add(findings, "recipes", specialist, "does not point to its progressively loaded recipe reference");
+        if (/^## (?:\d+(?:\.\d+)*\.?\s+)?(?:implementation\s+)?recipes?(?:\s|$)/im.test(contents.get(specialist) ?? ""))
+            add(findings, "recipes", specialist, "inline recipe catalog remains in the primary specialist file");
+    }
+    const planSchema = contents.get("schemas/plan.schema.json") ?? "";
+    for (const field of ["doctrineVersion", "ruleExceptions", "creativeStrategy", "fontDecision", "experimentalPlan", "conceptExploration", "recipeAccess"]) {
+        if (!planSchema.includes(`\"${field}\"`))
+            add(findings, "schema", "schemas/plan.schema.json", `missing creative-control field ${field}`);
+    }
+    const main = contents.get("SKILL.md") ?? "";
+    for (const definition of SKILL_DEFINITIONS) {
+        const file = `skills/${definition.name}.md`;
+        if (!contents.has(file))
+            add(findings, "skills", file, "specialist file is missing");
+        if (!main.includes(`\`${definition.name}\``))
+            add(findings, "skills", "SKILL.md", `picker omits ${definition.name}`);
+        for (const dependency of resolveSkillDependencies([definition.name])) {
+            if (!SKILL_DEFINITIONS.some((candidate) => candidate.name === dependency))
+                add(findings, "skills", file, `dependency ${dependency} has no definition`);
+        }
+    }
+    for (const file of UNIVERSAL_FILES) {
+        if (!(contents.get(file) ?? "").includes(UNIVERSAL_RULE))
+            add(findings, "universal-rules", file, "universal ux/mobile rule differs from the canonical wording");
+    }
+    try {
+        const registry = JSON.parse(contents.get("references/RULES.json") ?? "{}");
+        const ids = new Set();
+        for (const rule of registry.rules ?? []) {
+            if (!rule.id || ids.has(rule.id))
+                add(findings, "rules", "references/RULES.json", `missing or duplicate rule id: ${rule.id}`);
+            ids.add(rule.id);
+            if (!["hard-gate", "evidence-backed-default", "creative-provocation"].includes(rule.category))
+                add(findings, "rules", "references/RULES.json", `${rule.id}: invalid category`);
+            if (rule.category === "hard-gate" && rule.exceptionAllowed)
+                add(findings, "rules", "references/RULES.json", `${rule.id}: hard gates cannot allow exceptions`);
+            if (!rule.observedFailure || !rule.defaultRemedy || !rule.exceptionTest)
+                add(findings, "rules", "references/RULES.json", `${rule.id}: missing history, remedy, or exception test`);
+        }
+        if (!registry.wordingPrinciple?.includes("measurable success criteria"))
+            add(findings, "rules", "references/RULES.json", "missing bounded-exception wording principle");
+    }
+    catch (error) {
+        add(findings, "rules", "references/RULES.json", `cannot parse registry: ${String(error)}`);
+    }
+    try {
+        const reflex = JSON.parse(contents.get("references/REFLEX_FONTS.json") ?? "{}");
+        if (!Array.isArray(reflex.fonts) || reflex.fonts.length === 0)
+            add(findings, "fonts", "references/REFLEX_FONTS.json", "reflex font list is empty");
+        if (!Array.isArray(reflex.validReasonKinds) || reflex.validReasonKinds.length === 0)
+            add(findings, "fonts", "references/REFLEX_FONTS.json", "valid reason-kind list is empty");
+        if (!Array.isArray(reflex.invalidGenericReasons) || reflex.invalidGenericReasons.length === 0)
+            add(findings, "fonts", "references/REFLEX_FONTS.json", "generic-reason list is empty");
+    }
+    catch (error) {
+        add(findings, "fonts", "references/REFLEX_FONTS.json", `cannot parse registry: ${String(error)}`);
+    }
+    const design = contents.get("DESIGN.md") ?? "";
+    const lines = design.split(/\r?\n/);
+    const bannedTokens = new Set();
+    for (const line of lines) {
+        if (/\b(banned|never)\b/i.test(line))
+            for (const match of line.matchAll(/`([^`]+)`/g))
+                bannedTokens.add(match[1]);
+    }
+    for (const token of bannedTokens) {
+        const contradictory = lines.find((line) => line.includes(`\`${token}\``) && /\b(allowed|valid|preferred|required|use|source)\b/i.test(line) && !/\b(banned|never|instead of|do not)\b/i.test(line));
+        if (contradictory)
+            add(findings, "doctrine", "DESIGN.md", `implementation ${token} is both banned and presented positively`);
+    }
+    const phaseRule = "Run one short decision phase containing several sequential single-question";
+    for (const file of ["SKILL.md", "PLAN.md"]) {
+        if (!(contents.get(file) ?? "").includes(phaseRule))
+            add(findings, "questions", file, "decision-phase rule is inconsistent");
+    }
+    return { ok: findings.length === 0, findings };
+}
+export function printDocsCheck(report, json) {
+    if (json)
+        return void console.log(JSON.stringify(report, null, 2));
+    for (const item of report.findings)
+        console.log(`ERROR [${item.check}] ${item.file}: ${item.message}`);
+    console.log(report.ok ? "Dreative docs check passed." : "Dreative docs check failed.");
+}

package/dist/cli/docsCheck.test.js

@@ -0,0 +1,8 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { runDocsCheck } from "./docsCheck.js";
+test("packaged skill documents are internally consistent", () => {
+    const report = runDocsCheck(path.resolve("skill", "dreative"));
+    assert.equal(report.ok, true, JSON.stringify(report.findings, null, 2));
+});

package/dist/cli/index.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from "node:url";
 import readline from "node:readline";
 import { createServer } from "../server/index.js";
 import open from "open";
+import { printAudit, runDirectDesignAudit } from "./audit.js";
+import { printDocsCheck, runDocsCheck } from "./docsCheck.js";
 const port = Number(process.env.DREATIVE_PORT || 4820);
 const base = `http://localhost:${port}`;
 const args = process.argv.slice(2);
@@ -17,8 +19,31 @@ const USAGE = `usage: dreative [command]
                    --codex            install for Codex CLI instead (.codex/skills/ + AGENTS.md pointer)
                    --check            verify the installed skill matches this package (exit 1 on drift)
   wait             (agent) block until the UI needs something; prints one JSON event
-  respond <id> [result.json | --error msg]   (agent) answer a request
-  baseline         (agent) snapshot project.json as the finish-diff baseline`;
+  respond <id> [result.json | --error msg]   (agent) answer a request
+  baseline         (agent) snapshot project.json as the finish-diff baseline
+  audit             validate direct-design plan, preservation, assets, ledger, and verification
+                    --json              emit a machine-readable report
+  docs-check        validate packaged skill tiers, names, rules, references, and doctrine consistency
+                    --json              emit a machine-readable report`;
+const packagedSkillDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skill", "dreative");
+function walkFiles(root, current = root) {
+    const files = [];
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        const absolute = path.join(current, entry.name);
+        if (entry.isDirectory())
+            files.push(...walkFiles(root, absolute));
+        else
+            files.push(path.relative(root, absolute));
+    }
+    return files;
+}
+function copyRelativeFiles(sourceRoot, destinationRoot, files) {
+    for (const relative of files) {
+        const destination = path.join(destinationRoot, relative);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.copyFileSync(path.join(sourceRoot, relative), destination);
+    }
+}
 async function main() {
     if (args.includes("--help") || args.includes("-h")) {
         console.log(USAGE);
@@ -40,11 +65,12 @@ async function main() {
             return;
         }
         case "install-skill": {
-            const srcDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skill", "dreative");
+            const srcDir = packagedSkillDir;
             const skillsDir = path.join(srcDir, "skills");
             const available = fs.existsSync(skillsDir)
                 ? fs.readdirSync(skillsDir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
                 : [];
+            const coreFiles = walkFiles(srcDir).filter((relative) => !relative.startsWith(`skills${path.sep}`));
             if (args.includes("--list")) {
                 console.log(`specialist skills (installed by default, pick with --skills a,b):`);
                 for (const s of available) {
@@ -61,8 +87,7 @@ async function main() {
                     console.error(`skill not installed at ${destDir} — run \`dreative install-skill${args.includes("--codex") ? " --codex" : ""}\``);
                     process.exit(1);
                 }
-                const rootFiles = fs.readdirSync(srcDir).filter((f) => fs.statSync(path.join(srcDir, f)).isFile());
-                const packaged = [...rootFiles, ...available.map((s) => path.join("skills", `${s}.md`))];
+                const packaged = [...coreFiles, ...available.map((s) => path.join("skills", `${s}.md`))];
                 const stale = [];
                 const missingCore = [];
                 for (const rel of packaged) {
@@ -121,10 +146,7 @@ async function main() {
                 ? path.join(process.cwd(), ".codex", "skills", "dreative")
                 : path.join(process.cwd(), ".claude", "skills", "dreative");
             fs.mkdirSync(destDir, { recursive: true });
-            for (const f of fs.readdirSync(srcDir)) {
-                if (fs.statSync(path.join(srcDir, f)).isFile())
-                    fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
-            }
+            copyRelativeFiles(srcDir, destDir, coreFiles);
             if (picked.length) {
                 fs.mkdirSync(path.join(destDir, "skills"), { recursive: true });
                 for (const s of picked) {
@@ -149,6 +171,20 @@ async function main() {
             console.log(`next: ask your coding agent to "open dreative" or "redesign my app's UI visually"`);
             return;
         }
+        case "audit": {
+            const report = runDirectDesignAudit(process.cwd());
+            printAudit(report, args.includes("--json"));
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case "docs-check": {
+            const report = runDocsCheck(packagedSkillDir);
+            printDocsCheck(report, args.includes("--json"));
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
         // Agent: block until the UI needs something; print one event as JSON.
         // Output: {"kind":"request",...} | {"kind":"finish","diff":...} | {"kind":"none"}
         case "wait": {