b2c-app-builder 0.221.39

package/checks/validation/business/words/check-founder-copy.ts

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+/**
+ * check-founder-copy.ts — no raw machine value reaches a founder.
+ *
+ * This gate exists because the founder-facing dashboard used to print
+ * state/business-state.json keys straight into HTML, so a founder read rows like
+ * "paid_tool_routing | not_started" on their own business dashboard. The fix was a
+ * translation layer (tooling/lib/founder-copy.ts). This gate is what stops the fix from
+ * rotting the next time someone adds a lane, a status, a phase, or a provider route.
+ *
+ * Four rules:
+ *
+ * 1. COVERAGE. Every lane, status, phase, and autonomy mode in lib/launch-state.ts has
+ *    founder copy in lib/founder-copy.ts. A new lane cannot ship unlabeled.
+ * 2. NO RAW IDENTIFIERS. No snake_case token, SCREAMING_SNAKE token, or pipe-delimited
+ *    multi-segment value appears in founder-visible text. Text inside a clearly marked
+ *    technical-details disclosure is exempt, because that block is explicitly for
+ *    whoever picks the repo up next rather than for the founder.
+ * 3. NO INTERNAL VOCABULARY. The words in bannedFounderVocabulary do not appear in
+ *    founder-visible prose. Each one has a plain-language replacement recorded next to
+ *    it, so a failure tells the author what to say instead.
+ * 4. THE EXPERIENCE-CARD NAMES ARE NOT TRANSLATED. Rules 1–3 all push toward inventing a
+ *    friendlier word; for the twelve technique names that would be wrong, and rule 4 is
+ *    the record of that decision. It holds the umbrella phrase in the lane blurb a
+ *    founder reads, keeps the HIGH-risk set the founder attests to tied to the tiers the
+ *    card stubs declare, and rejects any attempt to ban a technique name outright.
+ *
+ * Scanning is deliberately text-only: HTML attributes (where `class="status
+ * not_started"` legitimately carries the enum), <style> and <script> bodies, markdown
+ * code fences, and inline code spans are stripped before the scan. Identifiers belong in
+ * those places; they do not belong in a sentence a founder reads.
+ *
+ * npm script: check:founder-copy
+ * Usage: tsx checks/validation/business/words/check-founder-copy.ts --root /path/to/templates [--skill-root /path/to/skill]
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  asString,
+  flagString,
+  getPath,
+  isPastOrientPhase,
+  isRecord,
+  issue,
+  parseFlags,
+  reportAndExit,
+  type Issue,
+} from "../../../../tooling/lib/launch-state.js";
+import { attestedTechniques, bannedFounderVocabulary, coverageGaps, experienceCardUmbrella, milestones } from "../../../../tooling/lib/founder-copy.js";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const defaultSkillRoot = path.resolve(scriptDir, "../../../..");
+
+const flags = parseFlags(process.argv.slice(2), [
+  { flags: ["--root"], key: "root" },
+  { flags: ["--skill-root"], key: "skillRoot" },
+]);
+const root = path.resolve(flagString(flags, "root") ?? path.join(defaultSkillRoot, "business"));
+const skillRoot = path.resolve(flagString(flags, "skillRoot") ?? defaultSkillRoot);
+const issues: Issue[] = [];
+
+/**
+ * Founder-visible surfaces. These are the files a founder actually opens, so they carry
+ * the strictest copy rules in the repo.
+ */
+const founderSurfaces: { relative: string; kind: "html" | "markdown" }[] = [
+  { relative: "operations/BUSINESS_ACCESS.md", kind: "markdown" },
+  { relative: "design/design-room.html", kind: "html" },
+  { relative: "product/onboarding.html", kind: "html" },
+  { relative: "analytics/analytics-plan.html", kind: "html" },
+  { relative: "trust/security-review.html", kind: "html" },
+  { relative: "store/store-console.html", kind: "html" },
+];
+
+/**
+ * Tokens that legitimately appear in founder-visible prose despite matching an
+ * identifier shape. Every entry needs a reason, in keeping with house culture.
+ */
+const allowedTokens = new Map<string, string>([
+  ["robots.txt", "a real filename a founder will see referenced in SEO work"],
+  ["llms.txt", "a real filename a founder will see referenced in AI-crawler work"],
+  ["sitemap.xml", "a real filename a founder will see referenced in SEO work"],
+  ["security.txt", "a published file at a public URL"],
+  ["app-ads.txt", "a published file at a public URL"],
+  ["BUSINESS_ACCESS.md", "the founder's own access document, named in its own heading"],
+  ["state/business-state.json", "named in continuity prose that a founder may hand to another agent"],
+  ["package.json", "a real filename in setup instructions"],
+  ["Info.plist", "a real Apple filename in submission instructions"],
+  ["2FA", "a term founders already know"],
+]);
+
+/** Words allowed despite matching a banned term, because the phrase means something else. */
+const vocabularyExemptions = new Map<string, RegExp[]>([
+  ["gate", [/\bdelegate/i, /\bgateway/i, /\bmitigate/i, /\baggregate/i, /\bnavigate/i, /\binvestigate/i]],
+  ["lane", [/\bplane\b/i, /\bplanet/i, /\bexplanet/i]],
+  ["proof", [/\bproofread/i, /\bfoolproof/i, /\bwaterproof/i, /\bbulletproof/i]],
+]);
+
+// ---------------------------------------------------------------------------
+// Rule 1: coverage
+// ---------------------------------------------------------------------------
+
+for (const gap of coverageGaps()) {
+  issues.push(
+    issue(
+      "error",
+      `founder_copy.missing_${gap.vocabulary.replace(/\s+/g, "_")}`,
+      `tooling/lib/founder-copy.ts has no founder-visible label for these ${gap.vocabulary}: ${gap.missing.join(", ")}. Add a label in the same commit that adds the value.`,
+      "tooling/lib/founder-copy.ts",
+    ),
+  );
+}
+
+if (milestones.length < 5 || milestones.length > 12) {
+  issues.push(
+    issue(
+      "error",
+      "founder_copy.milestone_count",
+      `The founder progress view has ${milestones.length} milestones. Keep it between 5 and 12 — fewer says nothing, more is the 22-row table again under a new name.`,
+      "tooling/lib/founder-copy.ts",
+    ),
+  );
+}
+
+/**
+ * The dictionary as text, not as an import. Every rule below reads the source under
+ * --skill-root rather than the module this gate itself imports, which is the only way a
+ * fixture can hand the gate a broken dictionary and prove the rule can fail.
+ */
+const founderCopySource = readFileSync(path.join(skillRoot, "tooling/lib/founder-copy.ts"), "utf8");
+
+for (const beatPhase of ["phase_1", "phase_2", "phase_3b", "phase_6"]) {
+  const found = founderCopySource.includes(`phase: "${beatPhase}"`);
+  if (!found) {
+    issues.push(
+      issue(
+        "error",
+        "founder_copy.celebration_beat_missing",
+        `No progress beat is recorded for ${beatPhase}. A founder should hear when a real milestone lands, not only when something is required of them.`,
+        "tooling/lib/founder-copy.ts",
+      ),
+    );
+  }
+}
+
+// A project past orientation needs a current founder-facing narrative.
+const statePath = path.join(root, "state/business-state.json");
+if (existsSync(statePath)) {
+  try {
+    const state: unknown = JSON.parse(readFileSync(statePath, "utf8"));
+    const phase = asString(getPath(state, "project.phase")) ?? "";
+    const projectName = (asString(getPath(state, "project.name")) ?? "").trim();
+    if (isPastOrientPhase(phase)) {
+      if (/^(app name|untitled app|your app|project name|tbd|todo)$/i.test(projectName)) {
+        issues.push(
+          issue(
+            "error",
+            "founder_copy.template_project_name",
+            `project.name still contains template text (${projectName || "blank"}) after setup. Record the working name before presenting the status as current.`,
+            "state/business-state.json",
+          ),
+        );
+      }
+
+      for (const field of ["sinceLastTime", "rightNow", "yourCall"] as const) {
+        const value = (asString(getPath(state, `narrative.${field}`)) ?? "").trim();
+        if (value.length === 0 || /^(todo|tbd|n\/a|placeholder|\.\.\.)$/i.test(value)) {
+          issues.push(
+            issue(
+              "error",
+              `founder_copy.narrative_stale.${field}`,
+              `narrative.${field} is empty or placeholder text while the project is past orient (${phase}). ` +
+                `The narrated update is the founder's first read on current work — write what actually happened, in plain language.`,
+              "state/business-state.json",
+            ),
+          );
+        }
+      }
+
+      const narrativeValues = ["sinceLastTime", "rightNow", "yourCall"]
+        .map((field) => ({ field, value: (asString(getPath(state, `narrative.${field}`)) ?? "").trim() }))
+        .filter((entry) => entry.value.length >= 20);
+      for (let left = 0; left < narrativeValues.length; left += 1) {
+        for (let right = left + 1; right < narrativeValues.length; right += 1) {
+          if (normalizeSentence(narrativeValues[left]!.value) !== normalizeSentence(narrativeValues[right]!.value)) continue;
+          issues.push(
+            issue(
+              "error",
+              "founder_copy.repeated_update",
+              `narrative.${narrativeValues[left]!.field} and narrative.${narrativeValues[right]!.field} repeat the same update. Use one concrete sentence for what changed, one for what happens next, and one current founder action.`,
+              "state/business-state.json",
+            ),
+          );
+        }
+      }
+    }
+
+    const tools = isRecord(getPath(state, "providers")) ? (getPath(state, "providers") as Record<string, unknown>) : {};
+    for (const [name, value] of Object.entries(tools)) {
+      const record = isRecord(value) ? value : {};
+      const explicitStatus = (asString(record.connectionStatus) ?? asString(record.status) ?? "").toLowerCase();
+      const route = (asString(record.accessRoute) ?? "").toLowerCase();
+      const connected = ["active", "connected", "done", "ready", "verified"].includes(explicitStatus);
+      const waiting = ["blocked", "access_pending", "founder_action_needed"].includes(explicitStatus) || route.includes("blocked");
+      if (connected && waiting) {
+        issues.push(
+          issue(
+            "error",
+            "founder_copy.connected_tool_contradiction",
+            `${name} is recorded as connected but its route is still blocked. Reconcile the service state before reporting it to the founder.`,
+            "state/business-state.json",
+          ),
+        );
+      }
+    }
+  } catch {
+    // Malformed state is validate-project-state's finding, not this gate's.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 4: the experience-card naming decision
+//
+// The twelve technique names are deliberately NOT translated (see the reasoning on
+// experienceCardUmbrella in tooling/lib/founder-copy.ts). A decision to leave
+// something alone rots faster than a decision to change it, because nothing in the
+// tree records that the absence was chosen. These three rules are that record.
+//
+// Skipped when the card stubs are not present — a business repo does not vendor the
+// playbook, and the founder-copy half of the rule has nothing to compare against.
+// ---------------------------------------------------------------------------
+
+const cardStubDir = path.join(skillRoot, "knowledge/experience/experience-cards");
+
+if (existsSync(cardStubDir)) {
+  const stubs = readdirSync(cardStubDir)
+    .filter((name) => name.endsWith("-card.md"))
+    .sort()
+    .map((name) => {
+      const source = readFileSync(path.join(cardStubDir, name), "utf8");
+      return {
+        // The filename minus "-card" is the technique's id everywhere it is addressed:
+        // the Retention Mechanics MCP key, the stub path, and the routing link.
+        id: name.replace(/-card\.md$/, ""),
+        name: (/^#\s+(.+?)\s+Card\s*$/m.exec(source)?.[1] ?? "").trim(),
+        tier: (/^\*\*Risk tier\.\*\*\s*([A-Za-z]+)/m.exec(source)?.[1] ?? "").toUpperCase(),
+      };
+    });
+
+  // 4a. attestedTechniques is the founder-facing half of the HIGH tier. If a card is
+  // promoted to HIGH in its stub and this list is not updated, a founder would attest
+  // to a mechanic whose name the copy layer no longer pins.
+  const highIds = stubs
+    .filter((stub) => stub.tier === "HIGH")
+    .map((stub) => stub.id)
+    .sort();
+  const attestedIds = attestedTechniques.map((technique) => technique.id).sort();
+  if (highIds.join(",") !== attestedIds.join(",")) {
+    issues.push(
+      issue(
+        "error",
+        "founder_copy.attested_technique_drift",
+        `attestedTechniques lists ${attestedIds.join(", ") || "nothing"} but the card stubs tier ${highIds.join(", ") || "nothing"} as HIGH. ` +
+          `A founder attests to the HIGH-risk techniques by name — the two lists are one decision and must move together.`,
+        "tooling/lib/founder-copy.ts",
+      ),
+    );
+  }
+
+  // 4b. Banning a technique name is how the aliasing decision would be reversed by
+  // accident: bannedFounderVocabulary's contract is "say this instead", so an entry
+  // here forces a euphemism onto exactly the surfaces that must not have one.
+  const techniqueNames = new Set(
+    [...stubs.map((stub) => stub.name), ...attestedTechniques.map((technique) => technique.name)].filter(Boolean).map((name) => name.toLowerCase()),
+  );
+  for (const { term } of bannedFounderVocabulary) {
+    if (!techniqueNames.has(term.toLowerCase())) continue;
+    issues.push(
+      issue(
+        "error",
+        "founder_copy.technique_alias_banned",
+        `"${term}" is an experience-card technique name and cannot be banned founder vocabulary. These twelve are terms of art and live MCP keys, ` +
+          `so a "say instead" entry would mint a second vocabulary for one concept. Use the umbrella phrase for the deck as a whole instead.`,
+        "tooling/lib/founder-copy.ts",
+      ),
+    );
+  }
+}
+
+// 4c. The umbrella is only real if a founder meets it. Declaring the phrase as a constant
+// proves nothing; it has to be in the emotional_design lane blurb, which is the row a
+// founder actually reads when this part of the launch comes up. Read from source for the
+// same reason as the beats above — an imported blurb cannot be varied by a fixture.
+const emotionalBlurb = /emotional_design:\s*\{[\s\S]*?blurb:\s*"([^"]*)"/.exec(founderCopySource)?.[1] ?? "";
+if (!emotionalBlurb.toLowerCase().includes(experienceCardUmbrella.toLowerCase())) {
+  issues.push(
+    issue(
+      "error",
+      "founder_copy.umbrella_unreachable",
+      `The emotional_design lane blurb does not contain the umbrella phrase "${experienceCardUmbrella}". ` +
+        `That blurb is where a founder meets this part of the launch as a whole — without it the twelve technique names have nothing to sit behind, ` +
+        `and the deck reads as twelve unexplained psychology terms.`,
+      "tooling/lib/founder-copy.ts",
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Rules 2 and 3: scan founder-visible surfaces
+// ---------------------------------------------------------------------------
+
+for (const surface of founderSurfaces) {
+  const absolute = path.join(root, surface.relative);
+  if (!existsSync(absolute)) continue;
+  const source = readFileSync(absolute, "utf8");
+  const scannable = surface.kind === "html" ? founderVisibleHtmlText(source) : founderVisibleMarkdownText(source);
+
+  for (const token of rawIdentifiers(scannable)) {
+    issues.push(
+      issue(
+        "error",
+        "founder_copy.raw_identifier",
+        `"${token}" is a machine value in text a founder reads. Route it through tooling/lib/founder-copy.ts, or move it inside the technical-details disclosure.`,
+        surface.relative,
+      ),
+    );
+  }
+
+  for (const { term, sayInstead } of bannedFounderVocabulary) {
+    if (!containsTerm(scannable, term)) continue;
+    issues.push(issue("error", "founder_copy.internal_vocabulary", `"${term}" appears in text a founder reads. Say instead: ${sayInstead}.`, surface.relative));
+  }
+}
+
+reportAndExit("Founder copy", issues);
+
+function normalizeSentence(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+/** Match renderer output without turning this validator into a second HTML renderer. */
+
+// ---------------------------------------------------------------------------
+// Text extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Founder-visible text from an HTML surface: drops style/script bodies, drops every tag
+ * (so attributes never reach the scan), and drops any <details> block, which is the
+ * sanctioned home for technical detail.
+ */
+function founderVisibleHtmlText(source: string): string {
+  const stripped = source
+    .replace(/<details[\s\S]*?<\/details>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    // <code> marks a value AS an identifier, the same way backticks do in markdown. A
+    // secret name a founder must paste into a provider belongs there; the same string
+    // dropped into a sentence does not.
+    .replace(/<code[\s\S]*?<\/code>/gi, " ")
+    // Mustache placeholders are substituted before a founder ever sees the page.
+    .replace(/\{\{[^}]*\}\}/g, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replaceAll("&amp;", "&")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"');
+
+  // A <script> body is dropped above as code, not prose -- but some pages (renderSourceArtifactPage
+  // in tooling/lib/artifact-pages.ts) base64-embed real Markdown in a script and decode it
+  // client-side into a target element by id, specifically so the *encoded* string in the source
+  // never contains raw identifiers for the naive scan above to trip on. That decoded text is
+  // exactly the founder-visible prose this gate exists to check, so decode it here too. A payload
+  // whose target element sits inside the sanctioned <details> disclosure is exempt like any other
+  // technical detail; one that lands outside it is scanned like any other founder-visible text.
+  const detailsBlocks = source.match(/<details[\s\S]*?<\/details>/gi) ?? [];
+  const decodedOutsideDetails = decodedScriptPayloads(source)
+    .filter(({ elementId }) => !detailsBlocks.some((block) => block.includes(`id="${elementId}"`)))
+    .map(({ text }) => text);
+
+  return [stripped, ...decodedOutsideDetails].join(" ");
+}
+
+function decodedScriptPayloads(source: string): Array<{ elementId: string; text: string }> {
+  const results: Array<{ elementId: string; text: string }> = [];
+  for (const scriptMatch of source.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)) {
+    const scriptBody = scriptMatch[1] ?? "";
+    const base64 = /atob\(\s*"([A-Za-z0-9+/=]+)"\s*\)/.exec(scriptBody)?.[1];
+    const elementId = /getElementById\(\s*"([^"]+)"\s*\)/.exec(scriptBody)?.[1];
+    if (!base64 || !elementId) continue;
+    try {
+      results.push({ elementId, text: Buffer.from(base64, "base64").toString("utf8") });
+    } catch {
+      // Malformed base64 is not this gate's concern; whatever renders the page will fail first.
+    }
+  }
+  return results;
+}
+
+/**
+ * Founder-visible text from a markdown surface: drops fenced blocks, inline code spans,
+ * link targets, and HTML comments. Identifiers inside backticks are how this repo names
+ * real files and commands, so they are legitimate there.
+ */
+function founderVisibleMarkdownText(source: string): string {
+  return source
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/~~~[\s\S]*?~~~/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/\]\([^)]*\)/g, "] ")
+    .replace(/^\s{4,}\S.*$/gm, " ");
+}
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+/** Machine-shaped tokens found in founder-visible text, deduplicated and allowlisted. */
+function rawIdentifiers(text: string): string[] {
+  const found = new Set<string>();
+
+  // snake_case and SCREAMING_SNAKE_CASE: two or more segments joined by underscores.
+  for (const match of text.matchAll(/\b[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+\b/g)) {
+    const token = match[0];
+    if (isAllowed(token)) continue;
+    found.add(token);
+  }
+
+  // Pipe-delimited multi-segment values, e.g. "high | founder | open" — a serialized
+  // record dropped into a sentence. Markdown table rows are excluded: a table is
+  // structure a reader understands, not a value pretending to be prose.
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("|")) continue;
+    for (const match of trimmed.matchAll(/[^\n|]{2,60}\|[^\n|]{2,60}\|[^\n|]{2,60}/g)) {
+      const token = match[0].trim().replace(/\s+/g, " ");
+      if (/^[\s|:-]+$/.test(token)) continue;
+      found.add(token.length > 80 ? `${token.slice(0, 77)}...` : token);
+    }
+  }
+
+  return [...found];
+}
+
+function isAllowed(token: string): boolean {
+  if (allowedTokens.has(token)) return true;
+  // Allowlisted filenames are matched without their extension too, because the token
+  // regex stops at the dot ("operations/BUSINESS_ACCESS.md" is scanned as "BUSINESS_ACCESS").
+  return [...allowedTokens.keys()].some((allowed) => allowed.replace(/\.[A-Za-z0-9]+$/, "") === token);
+}
+
+/** Whole-word term match with per-term exemptions for words that merely contain it. */
+function containsTerm(text: string, term: string): boolean {
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`(^|[^A-Za-z0-9-])${escaped}([^A-Za-z0-9-]|$)`, "i");
+  if (!pattern.test(text)) return false;
+  const exemptions = vocabularyExemptions.get(term.toLowerCase());
+  if (!exemptions) return true;
+  // Re-test with exempt words removed, so "delegate" does not trip the "gate" rule.
+  let stripped = text;
+  for (const exemption of exemptions) {
+    stripped = stripped.replace(new RegExp(exemption.source, "gi"), " ");
+  }
+  return pattern.test(stripped);
+}

package/checks/validation/business/words/check-no-slop.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * check-no-slop.ts — the repo's own front door follows the writing standard it ships.
+ *
+ * knowledge/words/no-slop-writing.md §2 names a "third surface" this file's rules cover
+ * beyond founder-facing and generated marketing copy: the repo's own public docs. The
+ * enforcement primitives (banned words, mechanical slop patterns, the em-dash budget) have
+ * lived in tooling/lib/no-slop-rules.ts since they were built for check:app-copy, but
+ * nothing ever pointed them at this third surface — a skill that ships a writing standard
+ * and exempts its own front door from it is enforcing words rather than work.
+ *
+ * Two severity tiers, both from the reference's own text: README.md, CONTRIBUTING.md,
+ * SECURITY.md, and CODE_OF_CONDUCT.md are the repo's public face and fail the gate.
+ * AGENTS.md and CLAUDE.md are maintainer-only guidance — a slip there gets a warning, not
+ * a blocked merge. Empty adverbs and empty phrases stay warnings on every file regardless
+ * of tier, matching their documented advisory nature in no-slop-rules.ts: they are cut when
+ * they add nothing and kept when they carry real emphasis, which is a judgment call this
+ * gate cannot make, only flag.
+ *
+ * npm script: check:no-slop
+ * Usage: tsx checks/validation/business/words/check-no-slop.ts [--repo-root /path] [--skill-root /path] [--skip-repo-front-door]
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { flagBoolean, flagString, issue, parseFlags, reportAndExit, type Issue, type Severity } from "../../../../tooling/lib/launch-state.js";
+import { findGitRoot } from "../../../../tooling/lib/git-root.js";
+import { emDashProblem, loadNoSlopRules, matchesTerm, slopPatterns } from "../../../../tooling/lib/no-slop-rules.js";
+import { communityHealthPaths, frontDoorPolicyFor } from "../../../../catalog/repository-profiles/registry.js";
+import { readAcceptedRepositoryProfile } from "../../../../catalog/repository-profiles/workspace.js";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const defaultSkillRoot = path.resolve(scriptDir, "../../../..");
+
+const flags = parseFlags(process.argv.slice(2), [
+  { flags: ["--repo-root"], key: "repoRoot" },
+  { flags: ["--skill-root"], key: "skillRoot" },
+  { flags: ["--skip-repo-front-door"], key: "skipRepoFrontDoor", kind: "boolean" },
+]);
+const skillRoot = path.resolve(flagString(flags, "skillRoot") ?? defaultSkillRoot);
+const repoRoot = path.resolve(flagString(flags, "repoRoot") ?? findGitRoot(skillRoot) ?? path.resolve(skillRoot, "../.."));
+const skipRepoFrontDoor = flagBoolean(flags, "skipRepoFrontDoor");
+const acceptedProfile = readAcceptedRepositoryProfile(repoRoot);
+const frontDoorPolicy = acceptedProfile ? frontDoorPolicyFor(acceptedProfile.id) : { requireReadme: true, requireCommunityHealth: true };
+const communityFiles = new Set(communityHealthPaths());
+
+const issues: Issue[] = [];
+
+/**
+ * The third surface, verbatim from knowledge/words/no-slop-writing.md §2. SECURITY.md and
+ * CODE_OF_CONDUCT.md live under .github/ — GitHub's standard community-health-file
+ * location — while the other four sit at the repo root.
+ */
+const publicFrontDoor: { relative: string; tier: Severity }[] = [
+  { relative: "README.md", tier: "error" },
+  { relative: "CONTRIBUTING.md", tier: "error" },
+  { relative: ".github/SECURITY.md", tier: "error" },
+  { relative: ".github/CODE_OF_CONDUCT.md", tier: "error" },
+  { relative: "AGENTS.md", tier: "warning" },
+  { relative: "CLAUDE.md", tier: "warning" },
+];
+
+const referencePath = path.join(skillRoot, "knowledge/words/no-slop-writing.md");
+const rules = loadNoSlopRules(referencePath);
+
+for (const surface of skipRepoFrontDoor ? [] : publicFrontDoor) {
+  const absolute = path.join(repoRoot, surface.relative);
+  if (!existsSync(absolute)) {
+    const skipReadme = surface.relative === "README.md" && !frontDoorPolicy.requireReadme;
+    const skipCommunity = communityFiles.has(surface.relative) && !frontDoorPolicy.requireCommunityHealth;
+    if (skipReadme || skipCommunity) continue;
+    issues.push(
+      issue(
+        "error",
+        "no_slop.front_door_missing",
+        `${surface.relative} is part of the repo's public front door per knowledge/words/no-slop-writing.md §2 but does not exist at ${absolute}.`,
+        surface.relative,
+      ),
+    );
+    continue;
+  }
+  const source = readFileSync(absolute, "utf8");
+  const scannable = proseText(source);
+
+  for (const word of rules.bannedWords) {
+    if (!matchesTerm(scannable, word)) continue;
+    issues.push(
+      issue(
+        surface.tier,
+        "no_slop.banned_word",
+        `"${word}" is banned outright by no-slop-writing.md §4. Cut it or use the plain word it stands in for.`,
+        surface.relative,
+      ),
+    );
+  }
+
+  for (const pattern of slopPatterns) {
+    if (!pattern.pattern.test(scannable)) continue;
+    const severity: Severity = surface.tier === "warning" ? "warning" : pattern.severity;
+    issues.push(issue(severity, `no_slop.pattern.${pattern.id}`, `${pattern.problem} ${pattern.fix}`, surface.relative));
+  }
+
+  for (const adverb of rules.emptyAdverbs) {
+    if (!matchesTerm(scannable, adverb)) continue;
+    issues.push(
+      issue(
+        "warning",
+        "no_slop.empty_adverb",
+        `"${adverb}" is an often-empty adverb (no-slop-writing.md §4). Cut it unless it carries real emphasis.`,
+        surface.relative,
+      ),
+    );
+  }
+
+  for (const phrase of rules.emptyPhrases) {
+    if (!matchesTerm(scannable, phrase)) continue;
+    issues.push(
+      issue(
+        "warning",
+        "no_slop.empty_phrase",
+        `"${phrase}" is an often-empty phrase (no-slop-writing.md §4). Cut it unless it earns its place.`,
+        surface.relative,
+      ),
+    );
+  }
+
+  const emDash = emDashProblem(scannable, false);
+  if (emDash) {
+    issues.push(issue("warning", "no_slop.em_dash_overuse", emDash, surface.relative));
+  }
+}
+
+reportAndExit("No-slop: repo front door", issues);
+
+/**
+ * Prose a reader actually reads: drops fenced and inline code (command names, file paths,
+ * and env vars are not writing slop), HTML comments, and link targets (a URL segment like
+ * "cutting-edge-features" is not the writer's prose). Link text is kept — it is real
+ * sentence content the reader sees.
+ */
+function proseText(source: string): string {
+  return source
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/~~~[\s\S]*?~~~/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/\]\([^)]*\)/g, "] ");
+}

package/checks/validation/repository/README.md

@@ -0,0 +1,31 @@
+# The Skill's Own Upkeep
+
+What a maintainer touches to keep this skill green. Nothing here is about running a business, and an agent mid-launch has no reason to load it.
+
+The line matters: durable expertise lives in manifest-backed `../knowledge/`; workflow order lives in `../catalog/`. Repository validation stays here.
+
+The same line decides where a validator lives. **`checks/validation/business/` grades a business launch; `checks/validation/repository/` grades the skill itself** — judged by the subject of the assertion, not by whether the validator takes `--skill-root`. These validators sit here for that reason:
+
+| Validator                      | Grades                                                                                                                                             |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check-package-parity.ts`      | the root and runtime package manifests and lockfiles agree with `skill-version.json`                                                               |
+| `check-repository-boundary.ts` | hosted product UI and publication authority stay outside the local B2C App Builder package; the top-level allowlist ignores gitignored local files |
+| `check-skill-version.ts`       | the installed runtime is not behind source                                                                                                         |
+| `check-version-discipline.ts`  | a pending change carries a matching version bump and release notes                                                                                 |
+| `check-source-freshness.ts`    | every tracked external source in `source-registry.yaml` is current                                                                                 |
+| `check-reference-size.ts`      | no knowledge file blows the per-file context budget, and every folder indexes its children                                                         |
+| `check-autopilot-contract.ts`  | `SKILL.md`'s frontmatter still triggers, against the triggering eval                                                                               |
+| `check-catalog.ts`             | stable catalog identities, edges, workflow contracts, and generated-projection drift (`catalog/validate.ts` + `catalog/render-routing.ts --check`) |
+| `check-task-skills.ts` | catalog-backed task skills, public navigation, portable reference closure, source hashes, and create-only exports |
+| `check-upstreams.ts`           | every manifest in `catalog/upstreams/` parses under `b2c.contribution/v1`, names its retained notice, and agrees with its recorded observation     |
+
+Everything else that grades an app lives in [`../validation/business/`](../business), mirroring the knowledge areas. Nothing may hardcode either directory: `../tooling/lib/script-paths.ts` resolves a script by basename and throws on an unknown or ambiguous name.
+
+| Load when                                                                                                                                 | Reference                                                                                | Produces / gate                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Writing or auditing a LaunchBench scenario, adding a failure mode to the regression suite, or deciding whether a miss deserves a new gate | [`launchbench-evals.md`](./launchbench-evals.md)                                         | `npm run launchbench` lints scenario definitions and runs the deterministic validator fixtures; `npm run evals:behavioral` is a different gate against a live agent — never claim one as the other |
+| Checking whether the installed runtime is behind source, syncing runtime copies, or cutting a version                                     | [`skill-versioning.md`](./skill-versioning.md)                                           | `check:skill-version`, `check:version-discipline`                                                                                                                                                  |
+| Adding an external link, refreshing an upstream pack, reviewing the weekly source diff, or changing fast-moving setup commands            | [`source-freshness-maintenance.md`](./source-freshness-maintenance.md)                   | `check:source-freshness`                                                                                                                                                                           |
+| Registering a new external source the skill depends on                                                                                    | [`source-registry.yaml`](./source-registry.yaml)                                         | machine-read by `check-source-freshness` and the weekly refresh workflow — one row per tracked source, not prose                                                                                   |
+| Changing domains, workflows, phases, lanes, operators, providers, context packs, knowledge, or generated routing                          | [`../../catalog/`](../../../catalog) (start at `domains.ts`, `workflows/`, `knowledge/`) | `knowledge:check`, `catalog:render-routing`, `check:catalog`                                                                                                                                       |
+| Checking an upstream for a release, license change, or host drift; preparing an upgrade plan; regenerating credits                        | [`../../../docs/guides/adopt-external-sources.md`](../../../docs/guides/adopt-external-sources.md) | `check:upstreams`, `check:credits`; `b2c contribute upstream-check --upstream <id> --fetch --observe-host --write` records the dated observation the gate reads                                    |