@clossys/writer 0.3.9 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clossys/writer",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -27,18 +27,207 @@
     "src",
     "!src/**/*.test.ts",
     "templates",
-    "CHANGELOG.md",
+    "fit-signals.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skill"
   ],
   "sideEffects": false,
   "foundry": {
     "assessment": {
       "bin": "writer-rate-check",
       "invocation": "single-json-input"
-    }
+    },
+    "capabilities": [
+      {
+        "id": "voice-record",
+        "subQuestion": "Is the voice record itself complete — every field bound, every rule derived from a real brand attribute?",
+        "worldClass": "The voice record is fully bound (no unedited template placeholder) and every rule traces to a brand-derivation attribute — checked as a record, before any copy is ever measured against it.",
+        "inputs": [
+          {
+            "producerRole": "@clossys/strategist",
+            "artifact": "brand-derivation"
+          }
+        ],
+        "outputs": [
+          "clossys/writer/voice.json"
+        ],
+        "proofCase": "voice-derivation-violated",
+        "maturity": "partial",
+        "v0": true,
+        "businessLifecycleStage": "define"
+      },
+      {
+        "id": "copy-registry",
+        "subQuestion": "Is every registry entry itself schema-valid, unique, and free of unfilled placeholders?",
+        "worldClass": "Every registry entry is schema-valid, has a unique id, and every declared placeholder is present in its own text — registry validity only; whether a component actually USES the registry by id is addressability's own question.",
+        "inputs": [],
+        "outputs": [
+          "clossys/writer/copy-registry.json"
+        ],
+        "proofCase": "registry-placeholder-missing",
+        "maturity": "built",
+        "v0": true,
+        "businessLifecycleStage": "build"
+      },
+      {
+        "id": "copy-coverage",
+        "subQuestion": "Does every user-facing string in code trace to a registered copy entry, by literal match or citation?",
+        "worldClass": "Every component string either matches a registered CopyRecord entry's text/alias or carries a copy:<id> citation -- the \"approved copy coverage rate\" metric this role owns (docs/contracts/role-loop-archetypes.json), and what writer-check's default command (copy-clean) actually proves. Distinct from `copy-registry` (is the registry entry itself valid) and from `claims-to-copy-traceability` (does a claim-SHAPED sentence cite an approved Strategist claim).",
+        "inputs": [
+          {
+            "producerRole": "@clossys/writer",
+            "artifact": "copy-registry"
+          }
+        ],
+        "outputs": [
+          "clossys/writer/.generated/copy-coverage-report.json"
+        ],
+        "proofCase": "copy-clean",
+        "maturity": "built",
+        "v0": true,
+        "businessLifecycleStage": "build"
+      },
+      {
+        "id": "claims-to-copy-traceability",
+        "subQuestion": "Does every claim-shaped or numeric sentence in shipped copy trace to an approved registry claim, by citation?",
+        "worldClass": "A currency amount, percentage, multiplier, or superlative sentence in live copy either matches a registered claim's text or carries a claim:<id> citation to one -- checked on the COPY side. Whether Strategist's own facts/markers gate should stop scanning shipped surfaces at all (leaving this the one place that check happens) is a decision pending #1271, not yet a settled boundary -- today `strategist-check` still scans authored prose too (its own facts-clean fixture is an announcement.md).",
+        "inputs": [
+          {
+            "producerRole": "@clossys/strategist",
+            "artifact": "claims"
+          }
+        ],
+        "outputs": [
+          "clossys/writer/.generated/claim-citations-report.json"
+        ],
+        "proofCase": "live-magnitude-unmarked",
+        "maturity": "partial",
+        "v0": true,
+        "businessLifecycleStage": "build"
+      },
+      {
+        "id": "live-copy-conformance",
+        "subQuestion": "Does live, shipped copy still match its registry source and stay within its word-budget and fold rules?",
+        "worldClass": "Shipped copy never drifts silently from its registry source, and the above-the-fold word budget is enforced, not eyeballed.",
+        "inputs": [],
+        "outputs": [
+          "clossys/writer/.generated/live-copy-report.json"
+        ],
+        "proofCase": "live-fold-wallpaper",
+        "maturity": "partial",
+        "v0": false,
+        "businessLifecycleStage": "operate"
+      },
+      {
+        "id": "addressability",
+        "subQuestion": "Is every piece of user-facing prose resolved from the registry by id, never typed directly into a component?",
+        "worldClass": "A rename is always cheap: renaming a piece of copy means editing one registry entry, never hunting every component that typed the sentence — #1208's site template reads copy by id on this guarantee.",
+        "inputs": [],
+        "outputs": [
+          "clossys/writer/.generated/addressability-report.json"
+        ],
+        "proofCase": "addressability-violated",
+        "maturity": "built",
+        "v0": true,
+        "businessLifecycleStage": "build"
+      },
+      {
+        "id": "locale-coverage",
+        "subQuestion": "Does the whole set of a project's locales actually cover the same ground, current and correctly interpolating?",
+        "worldClass": "Every target locale covers what the source locale covers, with no orphaned or stale translation — governance over WHICH locales are covered, not runtime translation itself.",
+        "inputs": [],
+        "outputs": [
+          "clossys/writer/.generated/locale-coverage-report.json"
+        ],
+        "proofCase": "locale-coverage-missing",
+        "maturity": "built",
+        "v0": false,
+        "businessLifecycleStage": "operate"
+      },
+      {
+        "id": "voice-conformance",
+        "subQuestion": "Is shipped copy actually well said — in voice, in tense, in person, every claim supported?",
+        "worldClass": "Every mechanically detectable voice violation (forbidden term, wrong tense or person, an unsupported claim marked as requiring support) is caught against the bound voice record — the answer to \"is it well said\", not merely \"does it trace\".",
+        "inputs": [
+          {
+            "producerRole": "@clossys/writer",
+            "artifact": "voice-record"
+          }
+        ],
+        "outputs": [
+          "clossys/writer/.generated/voice-conformance-report.json"
+        ],
+        "proofCase": "live-claim-unsupported",
+        "maturity": "partial",
+        "v0": false,
+        "businessLifecycleStage": "operate"
+      },
+      {
+        "id": "messaging-kit",
+        "subQuestion": "Does the product have one governed tagline, pitch-length set, boilerplate, and FAQ that everything else derives from?",
+        "worldClass": "One governed messaging kit (tagline, short/medium/long pitch, short/medium/long boilerplate, FAQ) exists and every surface's short-form copy derives from it, per #1204's Identity layer, rather than being improvised per surface.",
+        "inputs": [
+          {
+            "producerRole": "@clossys/strategist",
+            "artifact": "positioning"
+          }
+        ],
+        "outputs": [
+          "clossys/writer/messaging-kit.json"
+        ],
+        "proofCase": null,
+        "maturity": "planned",
+        "v0": true,
+        "businessLifecycleStage": "launch"
+      },
+      {
+        "id": "privacy-and-terms-placeholders",
+        "subQuestion": "Do the placeholder privacy notice and terms say, in the brand's voice, only what the supplied data-holding facts support, and say plainly that they are not legal advice?",
+        "worldClass": "Placeholder privacy-notice and terms text is drafted in the brand's voice from the facts Keeper supplies (what data is held, why, and for how long), never from assumption, and each page is labelled clearly as not legal advice pending review by counsel (#1213). Legal work beyond placeholders is out of scope for this role.",
+        "inputs": [],
+        "outputs": [
+          "clossys/writer/policy-placeholders.json"
+        ],
+        "proofCase": null,
+        "maturity": "planned",
+        "v0": true,
+        "businessLifecycleStage": "launch"
+      }
+    ],
+    "outputs": [
+      "clossys/writer/copy-registry.json",
+      "clossys/writer/voice.json"
+    ],
+    "feeds": [
+      {
+        "artifact": "copy-registry",
+        "path": "clossys/writer/copy-registry.json"
+      }
+    ],
+    "needs": [
+      {
+        "producerRole": "@clossys/strategist",
+        "artifact": "brand-derivation"
+      },
+      {
+        "producerRole": "@clossys/strategist",
+        "artifact": "claims"
+      }
+    ],
+    "solves": [
+      {
+        "problem": "writer-unapproved-copy",
+        "statement": "We ship words nobody signed off on.",
+        "metric": "approved copy coverage rate",
+        "proofCase": "copy-violated",
+        "evidence": "designed",
+        "capability": "copy-coverage"
+      }
+    ],
+    "fit": "fit-signals.json"
   },
-  "description": "The writer role: is it well said? A consumer-owned language system: voice rules, glossary and claims validation, addressable copy records, source traceability, locale coverage, and passage-layer composition — five gates reachable from one bin. Ships machinery and templates, never a consumer's actual copy or voice.",
+  "description": "The writer role: is it well said? A consumer-owned language system: voice rules, glossary and claims validation, addressable copy records, source traceability, locale coverage, and passage-layer composition \u2014 five gates reachable from one bin. Ships machinery and templates, never a consumer's actual copy or voice.",
   "keywords": [
     "writer",
     "copy",
@@ -70,7 +259,7 @@
   "devDependencies": {
     "@types/node": "^26.5.1",
     "typescript": "~6.0.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skill/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: clossys-writer
+description: Copy registry, voice conformance, and approved-language coverage. Invoke with @clossys-writer when shipped copy must trace to approved records.
+disable-model-invocation: true
+---
+# clossys-writer
+
+You are Writer. Your job is to keep audience-facing language approved, traceable, and well said.
+
+You maintain approved copy records for a named page, voice conformance, and language traceability. With Designer you supply the copy ids and block kinds the in-tree page document cites by reference, and iterate until a local render of that document is the page; Publisher authors and owns the surface document itself (#1205). You do not invent strategy facts, treat yourself as outline-only for Publisher to finish, or publish surfaces.
+
+
+## Foundry voices
+
+The same team is in every inventoried repo. Name another `@clossys-<package>` to talk to them. A missing mention is a bug, not a compatibility signal. Hiring and fit always go through `@clossys-advisor`.
+
+## Operating wave
+
+1. **Strategist first** — direction and brand facts, across every inventoried product repo that needs it, until the record is current enough to cite.
+2. **Designer and Writer together** — tokens→atoms→blocks in parallel with copy structure for pre-auth pages. Do not start if Strategist still has no citable direction.
+3. **Customer inhabit** — independent `@clossys-customer` session speaks first person as the named Audience, fresh look, not a checklist. That person can also be asked for lived feedback on any topic, comparison from their consideration set, what it would take to start or to refer, whether it is worth what it costs them, and what would make them leave. This role does not inhabit the user.
+4. **Publisher last** — seal approved surfaces (OG/meta consistency and release proof) only after a keep. Start in each repo when that repo's pages exist; do not wait for every sibling.
+
+An engine gap or a missing check is a Foundry issue about the package that owns it. Never dump a consumer's strategy. Never name a consumer.
+
+## Handoff citations
+
+Cite the strategist handoff: an audience id, approved strategist claim ids (`claim:<id>` in prose), applicable constraint ids (`constraint:<id>`), and the current direction id. Do not edit `clossys/strategist/`. Voice-glossary claims in this package are not strategist claims.
+
+## Pre-auth page
+
+Done is exceptional (5) as defined in PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`). `designer-hero-css-check`, `designer-fold-check`, and `writer-check --live` prove 3 only — never call 3 done or world class. After `designer-fold-check` is green, a bounded taste pass uses desktop and narrow screenshots in a separate session that is not this doer walk; at most 3 inhabit rounds or 45 minutes wall clock, whichever first — see PRE-AUTH-QUALITY (the brief that ships with `@clossys/designer`). This walk does not self-certify exceptional keep. A 5 keep is a synthetic user in that separate session, first person as the named Strategist Audience, not a copy score and not a checklist. This role does not author keep-review evidence and does not inhabit the persona. Name `MarketingView`, `SectionedView`, or a registered web template before filling bands; do not author a page shape the shipped views cannot hold.
+
+## When this package is installed
+
+If `node_modules/@clossys/writer` is present (or this package's bins are on PATH), use the exact pin in the tree. Read `package.json` `bin` for the real command names.
+- Assessment CLI: `writer-rate-check`
+- Additional gate CLI: `writer-check`
+
+Summarize gate results in human language; keep machine kinds for tooling, not as the default reply.
+
+## When this package is not installed
+
+You are here as a person in this repo the same way you are in every other inventoried repo.
+
+- Intro and quick questions are always in scope.
+- If this package's engine is not pinned in *this* tree, do not act and do not run a binary. Ask `@clossys-advisor` whether to hire you **in this repository**.
+- Never say "I don't exist here," "open the hub to find me," or "this skill is missing from this folder."
+- Never imply they should npm-install the whole catalogue.

package/src/addressability.ts

@@ -157,8 +157,8 @@
  *     position classified, and no inline user-facing prose found.
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { extractCopyCandidates } from "./scan.js";
 import type { ParseFailure, SkippedFile } from "./scan.js";
 import {
@@ -182,6 +182,12 @@ export interface AddressabilityScanOptions {
   skipDirs?: string[];
   /** Same mechanism `scan.ts`'s `ScanOptions.pathExclusions` uses — see `path-exclusions.ts`. */
   pathExclusions?: PathExclusion[];
+  /**
+   * Consumer-declared persistent chrome (site header, footer, skip link, nav
+   * labels) — shell or layout files scanned in addition to the directory walk.
+   * Paths are relative to `root` unless absolute. Each file must exist.
+   */
+  chromeFiles?: string[];
 }
 
 const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
@@ -190,7 +196,7 @@ const DEFAULT_SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "cov
 /** `.test.ts(x)`, `.spec.ts(x)`, `.check.ts(x)`, and bare `.d.ts` — the identical pattern `scan.ts` and `@example/ui`'s `style-scan.ts` both use, reused verbatim rather than reinvented (not exported by `scan.ts`, so redefined locally here — the same precedent `style-scan.ts` sets for its own copy of this constant). */
 const SKIP_FILE_RE = /\.(test|spec|check)\.(ts|tsx|js|jsx)$|\.d\.ts$/;
 
-export type AddressabilityPosition = "markup-text" | "user-facing-attribute";
+export type AddressabilityPosition = "markup-text" | "user-facing-attribute" | "object-literal-copy";
 
 export interface AddressabilityViolation {
   file: string;
@@ -198,6 +204,10 @@ export interface AddressabilityViolation {
   position: AddressabilityPosition;
   /** Set only for `"user-facing-attribute"` — which of the four this literal was the value of. */
   attribute?: "aria-label" | "placeholder" | "alt" | "title";
+  /** Set only for `"object-literal-copy"` — the property key this literal was the value of. */
+  objectKey?: string;
+  /** Set only for `"object-literal-copy"` — dotted/bracket path when nested under `items`/`nav`/`links`. */
+  keyPath?: string;
   /** The literal's own raw source text, for a human auditing the finding. */
   raw: string;
 }
@@ -316,6 +326,12 @@ export function scanAddressabilitySources(root: string, options: AddressabilityS
 
   walk(root);
 
+  if (options.chromeFiles !== undefined) {
+    for (const chromePath of options.chromeFiles) {
+      scanAddressabilityChromeFile(root, chromePath, extensions, result);
+    }
+  }
+
   for (const exclusion of pathExclusionValidation.valid) {
     if ((matchCounts.get(exclusion) ?? 0) === 0) {
       result.pathExclusionFindings.push({
@@ -330,6 +346,62 @@ export function scanAddressabilitySources(root: string, options: AddressabilityS
   return result;
 }
 
+function scanAddressabilityChromeFile(
+  root: string,
+  chromePath: string,
+  extensions: Set<string>,
+  result: AddressabilityScanResult,
+): void {
+  const full = isAbsolute(chromePath) ? resolve(chromePath) : resolve(root, chromePath);
+  if (!existsSync(full)) {
+    throw new Error(`scanAddressabilitySources: chrome file "${chromePath}" does not exist (resolved "${full}")`);
+  }
+  let stat;
+  try {
+    stat = statSync(full);
+  } catch (error) {
+    throw new Error(
+      `scanAddressabilitySources: cannot read chrome file "${chromePath}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!stat.isFile()) {
+    throw new Error(`scanAddressabilitySources: chrome path "${chromePath}" is not a file`);
+  }
+
+  const relPath = relative(root, full).split(sep).join("/");
+  const displayPath = relPath.length > 0 && !relPath.startsWith("..") ? relPath : chromePath;
+  const entryName = full.slice(full.lastIndexOf(sep) + 1);
+
+  if (!extensions.has(extname(entryName).toLowerCase())) {
+    throw new Error(
+      `scanAddressabilitySources: chrome file "${chromePath}" has extension ${extname(entryName)} which is not in the scan extension set`,
+    );
+  }
+
+  if (SKIP_FILE_RE.test(entryName)) {
+    result.skippedByDesign.push({ file: displayPath, reason: "test-or-check-file" });
+    return;
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(full, "utf8");
+  } catch (error) {
+    throw new Error(
+      `scanAddressabilitySources: cannot read chrome file "${full}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const extracted = extractAddressabilityCandidates(content, displayPath);
+  if (extracted.parseFailure) {
+    result.parseFailures.push({ file: displayPath, detail: extracted.parseFailure });
+    return;
+  }
+  result.filesScanned++;
+  result.violations.push(...extracted.violations);
+  result.unchecked.push(...extracted.unchecked);
+}
+
 // ------------------------------------------------------------- extraction
 
 /** `ariaLabel` -> `arialabel`, `aria-label` -> `arialabel` — the identical case/hyphen-insensitive normalization `scan.ts`'s own `normalizeIdentifier` performs (not exported, so reimplemented locally — a one-line heuristic, not worth a cross-file dependency). */
@@ -414,6 +486,83 @@ const DESTRUCTURING_OR_PARAMETER_DEFAULT_RE =
  * `DESTRUCTURING_OR_PARAMETER_DEFAULT_RE`'s own doc comment for exactly
  * what is and is not matched.
  */
+/** Copy-bearing object-literal property keys (issue #1063) — normalized like `normalizeAttrName`. */
+const COPY_BEARING_OBJECT_KEYS = new Set([
+  "label",
+  "title",
+  "cta",
+  "caption",
+  "heading",
+  "kicker",
+  "body",
+  "description",
+  "arialabel",
+  "text",
+]);
+
+/** Non-copy object-literal keys — route targets, icons, tokens; not Writer surfaces. */
+const ALLOWLISTED_OBJECT_LITERAL_KEYS = new Set([
+  "href",
+  "to",
+  "path",
+  "pathname",
+  "icon",
+  "iconname",
+  "slug",
+  "token",
+  "variant",
+  "size",
+]);
+
+const OBJECT_LITERAL_CONTAINER_KEYS = ["items", "nav", "links"] as const;
+
+const OBJECT_LITERAL_PROP_NAME_RE =
+  /(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][A-Za-z0-9_$-]*))\s*:\s*$/;
+
+function literalStartIndex(content: string, line: number, raw: string): number | undefined {
+  const lines = content.split("\n");
+  const lineText = lines[line - 1];
+  if (lineText === undefined) return undefined;
+  const col = lineText.indexOf(raw);
+  if (col === -1) return undefined;
+  let start = 0;
+  for (let i = 0; i < line - 1; i++) start += lines[i]!.length + 1;
+  return start + col;
+}
+
+function objectLiteralPropertyName(content: string, start: number): string | undefined {
+  const from = Math.max(0, start - 120);
+  const before = content.slice(from, start);
+  const match = OBJECT_LITERAL_PROP_NAME_RE.exec(before);
+  if (!match) return undefined;
+  return match[1] ?? match[2] ?? match[3];
+}
+
+function objectLiteralKeyPath(content: string, start: number, propName: string): string {
+  const from = Math.max(0, start - 500);
+  const slice = content.slice(from, start);
+  for (const container of OBJECT_LITERAL_CONTAINER_KEYS) {
+    const re = new RegExp(`\\b${container}\\s*:\\s*\\[`, "g");
+    let lastIndex = -1;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(slice)) !== null) lastIndex = m.index;
+    if (lastIndex !== -1) return `${container}[].${propName}`;
+  }
+  return propName;
+}
+
+/** Route/icon-shaped literal values that are never copy, regardless of key. */
+function looksLikeAllowlistedConstantValue(raw: string): boolean {
+  const quote = raw[0];
+  if (quote !== '"' && quote !== "'") return false;
+  const text = raw.slice(1, -1).trim();
+  if (text.length === 0) return false;
+  if (/^\/[^\s]*$/.test(text)) return true;
+  if (/^#[\w-]+$/.test(text)) return true;
+  if (/^https?:\/\//.test(text)) return true;
+  return false;
+}
+
 function isDestructuringOrParameterDefault(lines: string[], line: number, raw: string): boolean {
   const lineText = lines[line - 1];
   if (lineText === undefined) return false;
@@ -575,13 +724,46 @@ export function extractAddressabilityCandidates(content: string, filePath: strin
     violations.push({ file: c.file, line: c.line, position: "user-facing-attribute", attribute, raw: c.raw });
   }
 
-  // ---- position 3: everything else scan.ts kept as a real candidate —
+  // ---- position 3a: copy-bearing object-literal property values (issue
+  // #1063) — chrome config bags (`{ label: "...", href: "/join" }`) are
+  // Writer surfaces; allowlisted keys and route/icon-shaped values are not.
+  const objectLiteralClaimed = new Set<string>();
+  for (const c of candidates) {
+    if (c.kind !== "string") continue;
+    if (claimed.has(`${c.line}::${c.raw}`)) continue;
+    if (looksLikeUtilityClassList(c.raw)) continue;
+    const start = literalStartIndex(content, c.line, c.raw);
+    if (start === undefined) continue;
+    const propName = objectLiteralPropertyName(content, start);
+    if (propName === undefined) continue;
+    const normalizedProp = normalizeAttrName(propName);
+    if (ALLOWLISTED_OBJECT_LITERAL_KEYS.has(normalizedProp) || looksLikeAllowlistedConstantValue(c.raw)) {
+      objectLiteralClaimed.add(`${c.line}::${c.raw}`);
+      continue;
+    }
+    if (!COPY_BEARING_OBJECT_KEYS.has(normalizedProp)) continue;
+    if (isDestructuringOrParameterDefault(lines, c.line, c.raw)) continue;
+    if (!hasProse(c.raw)) continue;
+    const keyPath = objectLiteralKeyPath(content, start, propName);
+    objectLiteralClaimed.add(`${c.line}::${c.raw}`);
+    violations.push({
+      file: c.file,
+      line: c.line,
+      position: "object-literal-copy",
+      objectKey: propName,
+      keyPath,
+      raw: c.raw,
+    });
+  }
+
+  // ---- position 3b: everything else scan.ts kept as a real candidate —
   // never silently treated as clean, never treated as a violation either
   // — except a plain string shaped like a utility class LIST, which is
   // definitively not prose (see looksLikeUtilityClassList).
   for (const c of candidates) {
     if (c.kind === "jsx-text") continue; // already position 1
     if (c.kind === "string" && claimed.has(`${c.line}::${c.raw}`)) continue; // already position 2
+    if (c.kind === "string" && objectLiteralClaimed.has(`${c.line}::${c.raw}`)) continue;
     if (c.kind === "string" && looksLikeUtilityClassList(c.raw)) continue; // a class-name list, not prose
     unchecked.push({
       file: c.file,