@hegemonart/get-design-done 1.49.0 → 1.50.1

package/reference/visual-tells.md

@@ -1,4 +1,4 @@
-# Visual Tells Catalog (v1)
+# Visual Tells Catalog (v2)
 
 The default-AI aesthetic has a fingerprint. When a model generates a front-end
 without a brand brief, it falls back to the same handful of moves it saw most in
@@ -6,6 +6,12 @@ its training set. This catalog names those moves so the cheap regex floor in
 `hooks/gdd-design-quality-check.js` can flag them on every `.tsx` / `.vue` /
 `.svelte` / `.astro` write.
 
+This catalog grows commit by commit. The v1 floor named the eight loudest tells the
+hook matches today; v2 adds five more identified through hands-on usage. Newer
+categories may be catalog-only (documented and cross-linked, not yet wired to a hook
+rule) until a regex earns its place. Each entry below names a **primary axis** from
+`reference/anti-slop-rubric.md`, so a tell connects to the verb axis it most degrades.
+
 Severity here is WARN (advisory), in the vocabulary of `reference/audit-scoring.md`.
 A WARN is not a FLAG: it does not block the write and it does not fail a gate. It
 is a nudge that asks "did you choose this, or did the model default to it?" Each
@@ -227,11 +233,151 @@ and never animate keyboard-driven actions. See the Motion Anti-Patterns section
 
 ---
 
+## stock-photo-people
+
+Rule id: `stock-photo-people` (catalog-only)
+
+Generic smiling-team and handshake stock photography dropped in where a real product
+view belongs. The diverse-team-around-a-laptop shot, the lone founder gazing out a
+window, the abstract handshake: these read as filler the moment a viewer asks what the
+product actually does. Like the isometric fallback, the tell is that no real screen was
+available, so a stock human filled the hole.
+
+Instances:
+
+1. A hero photo of four people laughing at one laptop, captioned with a value prop.
+2. `src="/images/team-meeting.jpg"` standing in for a product screenshot.
+3. A testimonial section using stock headshots instead of real customer faces.
+4. An unsplash or shutterstock asset path in a primary marketing surface.
+5. The same stock photo reused across unrelated sections of one page.
+
+Diagnostic regex (where applicable): `\b(?:unsplash|shutterstock|istockphoto|gettyimages|stock[-_]?photo)[\w./-]*` in an asset path or `src`.
+
+Remediation: show the real product or real people connected to it. A genuine screenshot,
+a real customer portrait with permission, or a purpose-shot photo all beat a stock human.
+If no real asset exists yet, a clean illustration with brand character beats a stock smile.
+
+Primary axis: Authenticity.
+
+---
+
+## badge-spam
+
+Rule id: `badge-spam` (catalog-only)
+
+Decorative pills stacked to manufacture importance: "New", "Beta", "Pro", "AI-powered",
+"v2" scattered across cards and nav with no state behind them. One badge that reflects a
+real status orients the user. Four badges in a row are noise that the model adds because
+badges look like product maturity. The tell is a cluster of status pills none of which
+encode a true, current state.
+
+Instances:
+
+1. A card carrying "New", "Hot", and "AI-powered" badges at once.
+2. A nav item with a permanent "Beta" pill that has shipped for a year.
+3. Every feature tile in a grid wearing the same "Pro" badge.
+4. An "AI-powered" badge on a feature with no AI in it.
+5. Three or more `<Badge>` or `.badge` elements rendered in one small region.
+
+Diagnostic regex (where applicable): a quoted label matching `\b(?:New|Beta|Pro|AI-powered|Hot|Coming soon)\b` inside a badge or chip element, flagged at three or more in one component.
+
+Remediation: keep one badge that carries a real, current status, and delete the rest.
+A badge should change when state changes. If a label never changes, it is decoration, not
+status, and belongs in the copy or not at all.
+
+Primary axis: Authenticity.
+
+---
+
+## oversized-single-word
+
+Rule id: `oversized-single-word` (catalog-only)
+
+A single word blown up to display size to fill a section that has no content to carry it.
+"Build.", "Ship.", "Scale." at `text-8xl` with nothing beneath but air. Large type is a
+strong tool for one real headline; the tell is a one-word slab standing in for a sentence
+the writer did not write, sized for drama rather than meaning.
+
+Instances:
+
+1. A section whose only content is "Innovate." at `text-9xl`.
+2. A stack of one-word slabs ("Fast." "Simple." "Powerful.") each filling a viewport.
+3. A giant verb with no object, no supporting line, and 300px of padding around it.
+4. Display-size text where the word count is one and the surrounding region is empty.
+
+Diagnostic regex (where applicable): an element with `text-(?:7xl|8xl|9xl)` whose text node is a single word.
+
+Remediation: write the sentence the word was standing in for, then size the headline to
+serve reading. If a one-word moment is genuinely the design, give it a supporting line and
+a reason to be that large. Density should fit the content, not inflate to fill space.
+
+Primary axis: Density.
+
+---
+
+## motion-without-content-intent
+
+Rule id: `motion-without-content-intent` (catalog-only)
+
+Scroll-triggered fades, parallax layers, and entrance animations applied to every block
+because motion reads as "modern". This is the storytelling cousin of the ambient-loop tell:
+where `decorative-motion-without-intent` flags a forever-looping spinner, this flags motion
+wired to scroll or load that carries no content reason. Every element fading up in sequence
+delays the reader and signals motion chosen as decoration, not to direct attention.
+
+Instances:
+
+1. Every section wrapped in a `whileInView` fade-up with a staggered delay.
+2. Parallax on three background layers that encode no depth meaning.
+3. An entrance animation on body copy that the reader is waiting to read.
+4. Scroll-jacking that overrides native scroll for a "cinematic" reveal.
+
+Diagnostic regex (where applicable): `whileInView|data-aos|scroll-trigger|parallax` applied broadly across blocks without a reduced-motion guard in the same file.
+
+Remediation: tie motion to a content reason. Animate the one element that should draw the
+eye, let the rest render immediately, and respect `prefers-reduced-motion`. Reading content
+should never wait on a decorative reveal. See the Motion Anti-Patterns section of
+`reference/anti-patterns.md`.
+
+Primary axis: Hierarchy.
+
+---
+
+## narrator-from-a-distance-UI
+
+Rule id: `narrator-from-a-distance-UI` (catalog-only)
+
+Copy that describes the product from the outside in a detached marketing voice instead of
+speaking to the user doing a task. "Our platform empowers teams to achieve more" is a
+narrator at a distance; "Invite your team and assign the first task" speaks to the person
+in front of the screen. The tell is third-person product description where a second-person
+instruction belongs, especially inside the product rather than on a landing page.
+
+Instances:
+
+1. A dashboard empty state reading "The platform helps you organize your work" instead of "Create your first board".
+2. In-product copy in third person ("Users can export reports") rather than direct address.
+3. A feature headline describing the feature to an investor, not to its user.
+4. Onboarding steps narrated about the product instead of instructing the new user.
+
+Diagnostic regex (where applicable): in-product strings matching `\b(?:our platform|the platform|users can|we help you|empowers)\b` outside marketing routes.
+
+Remediation: write to the user in second person and name the next action. Inside the
+product, copy should instruct and orient, not pitch. Reserve the outside-in description for
+the marketing surface, and even there, lead with what the reader can do. See
+`reference/copy-quality.md` for the per-surface voice contract.
+
+Primary axis: Directness.
+
+---
+
 ## Notes
 
-This is a v1 floor, not a ceiling. The regexes favor precision over recall: they
-aim to fire only on the obvious cases so the WARN stays trustworthy. A clean pass
-here does not mean the design is good. It means the eight loudest default-AI tells
-are absent. Real review still applies the full rubric in
-`reference/audit-scoring.md` and the BAN / SLOP catalog in
+This is a v2 catalog, growing commit by commit, not a ceiling. The hook regexes favor
+precision over recall: they aim to fire only on the obvious cases so the WARN stays
+trustworthy. The five v2 categories above are catalog-only until a regex earns a place in
+the hook; they still give review a named tell and a primary axis to score against. A clean
+pass here does not mean the design is good. It means the loudest default-AI tells are
+absent. Real review still applies the full rubric in `reference/audit-scoring.md`, the verb
+axes in `reference/anti-slop-rubric.md`, and the BAN / SLOP catalog in
 `reference/anti-patterns.md`.

package/scripts/lib/manifest/scaffolder.cjs

@@ -0,0 +1,261 @@
+'use strict';
+/**
+ * scripts/lib/manifest/scaffolder.cjs — Phase 50 (Authoring Contract v3).
+ *
+ * Pure, dependency-free generator behind the `/gdd:new-skill` scaffolder skill.
+ * The SKILL.md (source/skills/new-skill/SKILL.md) drives the interactive
+ * prompts; this module is the deterministic core it (and the test suite) call.
+ *
+ * Exports:
+ *   buildSkillRecord({ name, description, argumentHint, tools, userInvocable,
+ *     composesWith }) -> a skills.json record object. Validates the name slug,
+ *     the v3 description budget (20..1024 chars), and the comma-separated tools
+ *     list. Throws on invalid input.
+ *   renderSkillMd(record) -> the SKILL.md template string (frontmatter in the
+ *     same canonical key order as generate-skill-frontmatter.cjs + a minimal
+ *     body skeleton with the standard sections).
+ *   suggestComposesWith(name, allSkills) -> heuristic composition suggestions
+ *     (skills sharing a lifecycle-stage keyword with the new skill name).
+ *
+ * Dependency-free of any third party. It DOES reuse the in-repo
+ * generate-skill-frontmatter.cjs `frontmatterFromRecord` emitter so the
+ * rendered frontmatter is a byte-for-byte fixed point with the forward
+ * generator (description quoted, canonical key order, name leads).
+ */
+
+const path = require('node:path');
+
+// Reuse the canonical frontmatter emitter so renderSkillMd stays compatible
+// with `npm run generate:skill-frontmatter` (same quoting + key order).
+const { frontmatterFromRecord } = require(
+  path.join(__dirname, '..', '..', 'generate-skill-frontmatter.cjs'),
+);
+
+// Slug rule mirrors reference/skill-authoring-contract.md `## Frontmatter`:
+// kebab-case identifier matching ^[a-z0-9][a-z0-9-._]*$.
+const NAME_RE = /^[a-z0-9][a-z0-9-._]*$/;
+
+// Description budget mirrors the Phase 28.5 contract (D-02) + skills.schema.json:
+// 20..1024 chars. The v3 "Activates for requests involving X, Y, Z." sentence
+// is recommended (LAX by default) but not regex-enforced here.
+const DESC_MIN = 20;
+const DESC_MAX = 1024;
+
+// Lifecycle-stage keyword groups used by suggestComposesWith. Skills whose
+// name shares a group with the new skill name are plausible composition
+// neighbours. Kept deliberately small and dependency-free; the SKILL.md treats
+// the result as a suggestion the user confirms, never an autowire.
+const STAGE_GROUPS = [
+  ['brief', 'intake', 'start', 'new-project', 'new-cycle'],
+  ['explore', 'discover', 'discuss', 'sketch', 'spike', 'map'],
+  ['plan', 'planning', 'design', 'do', 'build'],
+  ['verify', 'audit', 'review', 'quality-gate', 'check'],
+  ['ship', 'pr', 'complete', 'closeout', 'rollout'],
+  ['figma', 'extract', 'export', 'import', 'sync'],
+  ['token', 'tokens', 'darkmode', 'style', 'theme'],
+  ['health', 'progress', 'stats', 'report', 'timeline'],
+];
+
+function fail(msg) {
+  throw new Error(`scaffolder: ${msg}`);
+}
+
+/** Normalize a tools input (string or array) to a clean comma-list string. */
+function normalizeTools(tools) {
+  if (tools == null) return undefined;
+  let parts;
+  if (Array.isArray(tools)) {
+    parts = tools;
+  } else if (typeof tools === 'string') {
+    parts = tools.split(',');
+  } else {
+    fail('tools must be a comma-separated string or an array of tool names');
+  }
+  const cleaned = parts.map((t) => String(t).trim()).filter(Boolean);
+  if (cleaned.length === 0) fail('tools, when provided, must name at least one tool');
+  // Each token: a Tool name or an mcp__* identifier. No commas, no empty.
+  // `\w` already includes `_`, so a single `[\w-]*` class matches plain names
+  // (Read) AND mcp__* identifiers (mcp__gdd_state__get) in linear time. The old
+  // `(__[\w-]+)*` suffix overlapped `[\w-]*` and caused exponential backtracking
+  // (CodeQL js/redos) on inputs like `A__-__-__...`; it was redundant. Removed.
+  for (const t of cleaned) {
+    if (!/^[A-Za-z][\w-]*$/.test(t)) {
+      fail(`tools entry "${t}" is not a valid tool identifier`);
+    }
+  }
+  return cleaned.join(', ');
+}
+
+/** Normalize a composes_with input (string or array) to a slug array. */
+function normalizeComposesWith(composesWith) {
+  if (composesWith == null) return undefined;
+  let parts;
+  if (Array.isArray(composesWith)) parts = composesWith;
+  else if (typeof composesWith === 'string') parts = composesWith.split(',');
+  else fail('composesWith must be an array or comma-separated string of skill names');
+  const cleaned = parts.map((s) => String(s).trim()).filter(Boolean);
+  if (cleaned.length === 0) return undefined;
+  for (const s of cleaned) {
+    if (!NAME_RE.test(s)) fail(`composesWith entry "${s}" is not a valid skill slug`);
+  }
+  // De-dupe, preserve first-seen order.
+  return [...new Set(cleaned)];
+}
+
+/**
+ * Build a skills.json record object from scaffolder inputs.
+ * Keys are inserted in the canonical emit order so frontmatterFromRecord
+ * produces the same byte layout generate-skill-frontmatter.cjs would.
+ * @throws on an invalid name, out-of-budget description, or malformed tools.
+ */
+function buildSkillRecord(input) {
+  const opts = input || {};
+  const name = typeof opts.name === 'string' ? opts.name.trim() : opts.name;
+  if (!name || typeof name !== 'string') fail('name is required (a kebab-case slug)');
+  if (!NAME_RE.test(name)) {
+    fail(`name "${name}" must match ${NAME_RE} (lower-case, starts alnum, kebab/dot/underscore)`);
+  }
+
+  const description = typeof opts.description === 'string' ? opts.description.trim() : opts.description;
+  if (!description || typeof description !== 'string') fail('description is required');
+  if (description.length < DESC_MIN) {
+    fail(`description is ${description.length} chars; require >=${DESC_MIN}`);
+  }
+  if (description.length > DESC_MAX) {
+    fail(`description is ${description.length} chars; require <=${DESC_MAX}`);
+  }
+
+  // Insertion order == canonical managed-key emit order (name leads in the
+  // emitter; the rest follow record insertion order).
+  const rec = { name, description };
+
+  const argumentHint = opts.argumentHint != null ? String(opts.argumentHint) : undefined;
+  if (argumentHint !== undefined) rec.argument_hint = argumentHint;
+
+  const tools = normalizeTools(opts.tools);
+  if (tools !== undefined) rec.tools = tools;
+
+  if (opts.userInvocable !== undefined) rec.user_invocable = Boolean(opts.userInvocable);
+
+  const composesWith = normalizeComposesWith(opts.composesWith);
+  if (composesWith !== undefined) rec.composes_with = composesWith;
+
+  return rec;
+}
+
+/**
+ * Render the SKILL.md template string for a record.
+ * Frontmatter is emitted via the shared generate-skill-frontmatter emitter so
+ * it is a fixed point with the forward generator. composes_with (a Phase 50
+ * field not yet in the emitter's MANAGED set) is appended as an explicit
+ * frontmatter line; `--extract` carries it verbatim in extra_frontmatter.
+ */
+function renderSkillMd(record) {
+  if (!record || typeof record !== 'object') fail('renderSkillMd requires a record object');
+  // Validate/normalize defensively so renderSkillMd(buildSkillRecord(x)) and
+  // renderSkillMd(rawObject) both produce a contract-valid file.
+  const rec = buildSkillRecord({
+    name: record.name,
+    description: record.description,
+    argumentHint: record.argument_hint,
+    tools: record.tools,
+    userInvocable: record.user_invocable,
+    composesWith: record.composes_with,
+  });
+
+  // Separate composes_with: the shared emitter only knows the MANAGED keys, so
+  // composes_with rides as an extra_frontmatter line (the round-trip home the
+  // forward generator already uses for non-managed keys).
+  const composesWith = rec.composes_with;
+  const emitRec = { ...rec };
+  delete emitRec.composes_with;
+  if (composesWith && composesWith.length) {
+    emitRec.extra_frontmatter = [`composes_with: [${composesWith.join(', ')}]`];
+  }
+
+  const frontmatter = frontmatterFromRecord(emitRec);
+  const prefix = '{{command_prefix}}';
+  const upper = rec.name.toUpperCase();
+
+  const body = [
+    '',
+    `# ${prefix}${rec.name}`,
+    '',
+    `**Role:** ${rec.description.split('. ')[0]}.`,
+    '',
+    '## Steps',
+    '',
+    '1. State the preconditions this skill needs (read `.design/STATE.md` if relevant).',
+    '2. Do the work. Keep each step a single concrete action.',
+    '3. Report the result and recommend the next action.',
+    '',
+    '## Output',
+    '',
+    '```',
+    `${prefix}${rec.name} result summary goes here.`,
+    '```',
+    '',
+    '## Do Not',
+    '',
+    '- Do not exceed the authoring-contract length cap (warn at 100 lines).',
+    '- Do not invent state; read it from `.design/`.',
+    '',
+    `## ${upper} COMPLETE`,
+    '',
+  ].join('\n');
+
+  return `---\n${frontmatter}\n---\n${body}`;
+}
+
+/**
+ * Heuristic composition suggestions for a new skill.
+ * Returns skill names from `allSkills` that share a lifecycle-stage keyword
+ * with `name` (or whose name substring-matches a shared stage token). The
+ * new skill itself is never suggested. Order: stable by allSkills order.
+ * @param {string} name new skill slug
+ * @param {Array<string|{name:string}>} allSkills existing skills (names or records)
+ * @returns {string[]} suggested composition neighbours (possibly empty)
+ */
+function suggestComposesWith(name, allSkills) {
+  if (!name || typeof name !== 'string') return [];
+  const self = name.trim().toLowerCase();
+  const names = (Array.isArray(allSkills) ? allSkills : [])
+    .map((s) => (typeof s === 'string' ? s : s && s.name))
+    .filter((n) => typeof n === 'string' && n.trim() && n.trim().toLowerCase() !== self)
+    .map((n) => n.trim());
+
+  // Which stage groups does the new skill touch?
+  const tokensOf = (slug) => slug.toLowerCase().split(/[-._]/).filter(Boolean);
+  const selfTokens = new Set(tokensOf(self));
+  const selfGroups = new Set();
+  STAGE_GROUPS.forEach((group, idx) => {
+    if (group.some((kw) => selfTokens.has(kw) || self.includes(kw))) selfGroups.add(idx);
+  });
+
+  if (selfGroups.size === 0) return [];
+
+  const seen = new Set();
+  const out = [];
+  for (const candidate of names) {
+    if (seen.has(candidate)) continue;
+    const cTokens = new Set(tokensOf(candidate));
+    const inGroup = [...selfGroups].some((idx) =>
+      STAGE_GROUPS[idx].some((kw) => cTokens.has(kw) || candidate.toLowerCase().includes(kw)),
+    );
+    if (inGroup) {
+      out.push(candidate);
+      seen.add(candidate);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  buildSkillRecord,
+  renderSkillMd,
+  suggestComposesWith,
+  NAME_RE,
+  DESC_MIN,
+  DESC_MAX,
+  STAGE_GROUPS,
+};

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -60,6 +60,20 @@
             },
             "description": "Reserved for pin shortcuts; honored by the pin metadata catalogue."
           },
+          "composes_with": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Phase 50 (v3) optional: skill names this skill calls as sub-orchestration. Each becomes a directed composition edge validated by scripts/validate-composition-graph.cjs (must be a DAG, no dangling refs)."
+          },
+          "next_skills": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Phase 50 (v3) optional: pipeline hint listing skill names that naturally run after this one. Each becomes a directed edge in the composition graph (DAG, no dangling refs)."
+          },
           "extra_frontmatter": {
             "type": "array",
             "items": {