naive-framework 0.0.0-stage → 0.1.0

package/evidence/skills/fidelity-ladder-audit/SKILL.md

@@ -0,0 +1,121 @@
+---
+type: knowledge
+tags: [everything-ecosystem, skills, fidelity-ladders, design-system, audit]
+ai-model: claude-opus-5
+created: 2026-09-09
+source: hybrid
+name: fidelity-ladder-audit
+description: >
+  Audit a project's component tree as a set of fidelity ladders — one domain
+  object, many renderings ordered by how much of the object each shows — and
+  produce the field-projection matrix, kernel, and gap list for each. Use when
+  auditing a design system, cataloguing components, reconciling a component
+  library against a data model, planning a new surface, or asking "how many
+  ways do we render X?" Also use before adding a rendering of an object that
+  already has one. Implements [[FIDELITY_LADDERS]]. MANDATORY TRIGGERS: fidelity
+  ladder, component bundle, component audit, design system audit, component
+  inventory, representation, view mode, kernel, projection matrix, how many
+  ways do we render, object model, card variants, component gaps.
+---
+
+# Fidelity Ladder Audit
+
+Audits a codebase against [[FIDELITY_LADDERS]]. The census is mechanical; the matrix is not.
+
+## What this skill will and will not do
+
+It **will** inventory a component tree, propose ladders from naming and prop shapes, and find components that render the same object at the same tier while disagreeing about its fields.
+
+It **will not** decide what a component renders. Names and props are evidence, not truth. Every candidate the script emits is a question for a human, and the matrix is always hand-built from reading the components.
+
+## Procedure
+
+### Step 0 · Ground the session
+
+Invoke [[skills/time-awareness/SKILL|time-awareness]]. The audit produces dated artifacts.
+
+### Step 1 · Get the object lexicon from the data model, not from intuition
+
+The object axis comes from the project's own vocabulary. In order of preference:
+
+1. An entity-type enum in the code (`ENTITY_TYPES`, a discriminated union, a table list). This is authoritative — it is what the system already believes its objects are.
+2. `DATA_MODEL_SPEC` headings or table names.
+3. Frequency analysis of domain nouns in the data model, as a fallback.
+
+```bash
+grep -rn "ENTITY_TYPES\|EntityType =" <repo>/packages <repo>/apps --include=*.ts | grep -v node_modules
+```
+
+**If more than one entity-type enum exists, stop and record it.** Competing enums mean the system disagrees with itself about what its objects are, and no ladder built on either one is trustworthy. This is a finding, not an obstacle.
+
+### Step 2 · Run the census
+
+```bash
+node ladder-census.mjs <components-dir> --json out.json
+```
+
+It reports three sections:
+
+- **Candidate ladders** — components grouped by object, sorted by fidelity tier, with props and absent rungs.
+- **Object-named, no representation suffix** — named for an object but not declaring a fidelity. Each is a question: a rung that needs renaming, or not a rendering at all?
+- **Representation suffix, no object** — generic primitives, or objects missing from the lexicon.
+
+### Step 3 · Re-run with the codebase's own nouns
+
+The default lexicon is the *specified* vocabulary. Codebases drift from it, and the drift is where ladders hide. In one audit the largest ladder was invisible on the first pass because the spec says `officeholder` and the components say `Rep`.
+
+Scan the third section for recurring nouns the lexicon missed, then re-run:
+
+```bash
+node ladder-census.mjs <components-dir> --objects Rep,Post,Event,Vault
+```
+
+**A ladder found only on the second pass is itself a finding** — it means the component names and the data model use different words for the same object.
+
+### Step 4 · Read the top ladders and build the matrix by hand
+
+Take the three or four objects with the most rungs. For each, open every rung and record what it actually renders. Then build the matrix from [[FIDELITY_LADDERS]] §4: fields down the side, rungs across the top, cells as full / reduced / promoted / absent.
+
+Two things to watch for that the script cannot see:
+
+- **Same-tier forks.** Two components at the same rung rendering the same object under different names. Compare their prop lists directly — near-identical shapes with different field names are the signature.
+- **Encoding disagreements.** The same fact carried at different resolutions in different rungs — a boolean in one, a six-value enum in another. The richest encoding is usually the correct one, and the flattened ones are lossy.
+
+### Step 5 · Name the kernel
+
+For each ladder, the fields present in every rung. The script offers a `kernelCandidate` from prop intersection; treat it as a starting point, since props and rendered fields are not the same thing.
+
+Then apply Rule K1: does every rung actually render the whole kernel? A rung that does not is either a defect or proof the kernel is drawn too wide.
+
+### Step 6 · Add the machine rungs
+
+The census only sees components. Find the non-visual renderings by hand — embed fragments, OG tags, JSON-LD, public API responses — and add them as columns. Per Rule K4 an audit without them is half an audit.
+
+```bash
+ls <repo>/apps/*/src/app/embed <repo>/apps/*/src/app/api 2>/dev/null
+grep -rn "openGraph\|application/ld+json" <repo>/apps --include=*.tsx | grep -v node_modules
+```
+
+### Step 7 · Write the gap list
+
+Per object, in this order of severity:
+
+1. **Forked rungs** — same object, same tier, two components, disagreeing fields.
+2. **Kernel violations** — a rung missing a kernel field.
+3. **Lossy encodings** — a fact carried at lower resolution than the object supports.
+4. **Missing rungs** — a fidelity the product needs and does not have.
+5. **Naming drift** — components whose names do not state object and fidelity.
+
+Missing rungs rank fourth deliberately. An absent rung is a gap; a forked rung is a bug that is already shipping.
+
+## Output
+
+An audit artifact with, per object: the ladder, the kernel, the projection matrix, and the gap list. Plus one project-level section for cross-cutting findings — competing enums, vocabulary drift, subsystems that implement the method in isolation.
+
+File it per the vault's document-placement rule. An audit is a finding, not a contract: `product/research/` while it is a report, `product/spec/` only once it is elevated to a binding ladder contract — and per the authority gate, elevation and relocation are one edit.
+
+## Notes
+
+- The tier list in the script (page / panel / card / row / glyph / preview) is a default, not a truth. Projects with a genuinely different fidelity vocabulary should edit `TIERS` rather than force their components into these six.
+- `NON_REPRESENTATION` filters infrastructure — filters, providers, shells. When the census looks empty for an object, check whether its components are being filtered out as infrastructure.
+- The script never writes to the audited repo.

package/evidence/skills/fidelity-ladder-audit/ladder-census.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// ladder-census — inventory a component tree and propose fidelity ladders.
+//
+// Usage:
+//   node ladder-census.mjs <components-dir> [--objects a,b,c] [--json out.json]
+//
+// Emits, for each domain object in the lexicon, the components that render it,
+// bucketed into fidelity tiers by their representation suffix. Components that
+// name an object but carry no representation suffix are reported separately —
+// they are the ambiguous middle where ladders usually go wrong.
+//
+// This is a *proposal* generator, not an authority. It reads names and prop
+// shapes; it cannot see what a component actually renders. Every candidate it
+// emits is a question for a human, and the field matrix is always hand-built.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, extname, basename } from "node:path";
+
+// ---------------------------------------------------------------- lexicons
+
+// Representation suffixes, ordered richest to thinnest. The tier number is the
+// rung on the ladder; L1 is always the canonical full rendering.
+const TIERS = [
+  { tier: 1, name: "page", match: /(Page|View|Screen|Detail|Article|Profile)$/ },
+  { tier: 2, name: "panel", match: /(Panel|Sheet|Modal|Drawer|Dialog|Section|Block)$/ },
+  { tier: 3, name: "card", match: /(Card|Tile|Cell)$/ },
+  { tier: 4, name: "row", match: /(Row|Item|ListItem|Entry|Line)$/ },
+  { tier: 5, name: "glyph", match: /(Chip|Pill|Badge|Tag|Marker|Avatar|Portrait|Dot|Icon)$/ },
+  { tier: 6, name: "preview", match: /(Preview|Tooltip|Hover|Popover|Summary|Snippet)$/ },
+];
+
+// Components that are infrastructure, not renderings of a domain object.
+const NON_REPRESENTATION = /(Filters?|Provider|Context|Boundary|Shell|Nav|Menu|Form|Manager|Controls?|Handler|Wrapper|Layout|Skeleton|Loader|Portal|Toggle|Switch|Selector|Picker|Search|Pagination|Breadcrumb)$/;
+
+const DEFAULT_OBJECTS = [
+  "Officeholder", "Bill", "Address", "Position", "Citation", "Source",
+  "Committee", "Chamber", "District", "Person", "Office", "Body", "Vote",
+  "Term", "Party", "Election", "Court", "Race", "Measure", "Candidate",
+  "Agency", "Jurisdiction",
+];
+
+// ---------------------------------------------------------------- arguments
+
+const argv = process.argv.slice(2);
+const root = argv.find((a) => !a.startsWith("--"));
+if (!root) {
+  console.error("usage: node ladder-census.mjs <components-dir> [--objects a,b] [--json out.json]");
+  process.exit(1);
+}
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? null : argv[i + 1];
+};
+const objects = (flag("objects")?.split(",").map((s) => s.trim()).filter(Boolean)) ?? DEFAULT_OBJECTS;
+const jsonOut = flag("json");
+
+// ---------------------------------------------------------------- traversal
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry.startsWith(".")) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) walk(full, acc);
+    else if (extname(entry) === ".tsx" && !/\.(test|spec|stories)\.tsx$/.test(entry)) acc.push(full);
+  }
+  return acc;
+}
+
+// Pull prop names off the component's props type. Deliberately shallow: this is
+// a signal for comparing siblings on one ladder, not a type checker.
+function extractProps(src, componentName) {
+  const patterns = [
+    new RegExp(`(?:interface|type)\\s+${componentName}Props\\s*=?\\s*\\{([\\s\\S]*?)\\n\\}`),
+    /(?:interface|type)\s+Props\s*=?\s*\{([\s\S]*?)\n\}/,
+  ];
+  for (const re of patterns) {
+    const m = src.match(re);
+    if (!m) continue;
+    return [...m[1].matchAll(/^\s*(?:readonly\s+)?([a-zA-Z_][\w]*)\??\s*:/gm)].map((x) => x[1]);
+  }
+  return [];
+}
+
+function classify(name) {
+  for (const t of TIERS) if (t.match.test(name)) return t;
+  return null;
+}
+
+// ---------------------------------------------------------------- census
+
+const files = walk(root);
+const components = files.map((f) => {
+  const name = basename(f, ".tsx");
+  const src = readFileSync(f, "utf8");
+  return {
+    name,
+    file: f.replace(root, "").replace(/^\//, ""),
+    props: extractProps(src, name),
+    lines: src.split("\n").length,
+    tier: classify(name),
+    infra: NON_REPRESENTATION.test(name),
+  };
+});
+
+const ladders = {};
+const unsuffixed = {};
+
+for (const obj of objects) {
+  const owned = components.filter((c) => c.name.toLowerCase().includes(obj.toLowerCase()));
+  if (!owned.length) continue;
+  const rungs = owned.filter((c) => c.tier && !c.infra);
+  const loose = owned.filter((c) => !c.tier && !c.infra);
+  if (rungs.length) {
+    ladders[obj] = rungs
+      .sort((a, b) => a.tier.tier - b.tier.tier)
+      .map((c) => ({ tier: `L${c.tier.tier}`, kind: c.tier.name, component: c.name, file: c.file, props: c.props }));
+  }
+  if (loose.length) unsuffixed[obj] = loose.map((c) => ({ component: c.name, file: c.file, props: c.props }));
+}
+
+// A component carrying a representation suffix but matching no object in the
+// lexicon is either a generic primitive or an object the lexicon is missing.
+const unclaimed = components
+  .filter((c) => c.tier && !c.infra)
+  .filter((c) => !objects.some((o) => c.name.toLowerCase().includes(o.toLowerCase())))
+  .map((c) => ({ tier: `L${c.tier.tier}`, component: c.name, file: c.file }));
+
+// ---------------------------------------------------------------- shared-field analysis
+
+// Where a ladder has two or more rungs, the props common to every rung are the
+// candidate kernel; props on exactly one rung are candidate context fields.
+for (const [obj, rungs] of Object.entries(ladders)) {
+  const withProps = rungs.filter((r) => r.props.length);
+  if (withProps.length < 2) continue;
+  const common = withProps
+    .map((r) => new Set(r.props))
+    .reduce((a, b) => new Set([...a].filter((x) => b.has(x))));
+  ladders[obj].kernelCandidate = [...common];
+}
+
+// ---------------------------------------------------------------- report
+
+const pad = (s, n) => String(s).padEnd(n);
+const out = [];
+out.push(`ladder census · ${root}`);
+out.push(`${files.length} components scanned · ${Object.keys(ladders).length} candidate ladders\n`);
+
+out.push("CANDIDATE LADDERS");
+out.push("-".repeat(72));
+for (const [obj, rungs] of Object.entries(ladders)) {
+  out.push(`\n${obj}  (${rungs.length} rung${rungs.length > 1 ? "s" : ""})`);
+  for (const r of rungs) {
+    out.push(`  ${pad(r.tier, 4)} ${pad(r.kind, 8)} ${pad(r.component, 30)} ${r.props.length ? r.props.join(", ") : "—"}`);
+  }
+  if (rungs.kernelCandidate?.length) out.push(`  kernel candidate: ${rungs.kernelCandidate.join(", ")}`);
+  const present = new Set(rungs.map((r) => r.tier));
+  const missing = TIERS.filter((t) => !present.has(`L${t.tier}`)).map((t) => `L${t.tier}/${t.name}`);
+  if (missing.length) out.push(`  absent rungs: ${missing.join("  ")}`);
+}
+
+out.push(`\n\nOBJECT-NAMED, NO REPRESENTATION SUFFIX`);
+out.push("-".repeat(72));
+out.push("Named for an object but not declaring a fidelity. Each is a question:");
+out.push("is it a rung that should be renamed, or not a rendering at all?\n");
+for (const [obj, list] of Object.entries(unsuffixed)) {
+  out.push(`${obj}: ${list.map((c) => c.component).join(", ")}`);
+}
+
+out.push(`\n\nREPRESENTATION SUFFIX, NO OBJECT`);
+out.push("-".repeat(72));
+out.push("Generic primitives, or objects missing from the lexicon.\n");
+out.push(unclaimed.map((c) => `${c.tier} ${c.component}`).join("\n"));
+
+console.log(out.join("\n"));
+
+if (jsonOut) {
+  writeFileSync(jsonOut, JSON.stringify({ root, scanned: files.length, ladders, unsuffixed, unclaimed }, null, 2));
+  console.error(`\nwrote ${jsonOut}`);
+}

package/evidence/skills/findability/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: findability
+type: reference
+source: hybrid
+created: 2026-10-14T03:30:00Z
+ai-model: claude-opus-5.5
+description: "Check whether an entity's documents and decisions can be found (SAD v3.0.16 §NEW.26). Free structural inventory at every phase boundary; paid TypeSafe deep pass for domain classification and decision contradictions. Use when the owner says findability, orphans, rediscovery, scattered, discombobulated, vault audit, or at phase boundaries."
+tags: [skill, methodology, findability, registries, rediscovery]
+---
+
+# Findability
+
+Ratified in [[SAD_SKILL_v3_AMENDMENT_2026-10-13_findability-product-harness-and-repository-structure]] (v3.0.16). Built from an organization campaign.
+
+## 1. Structural inventory (free, every phase boundary)
+
+```bash
+ruby -E UTF-8 evidence/skills/findability/inventory.rb <vault>/projects/<entity>
+```
+
+Reports: notes without frontmatter, YAML errors, orphans, governance notes missing `governed-by` or `authority`, authority-gate violations, wholly superseded notes not archived (partly superseded notes are excluded on purpose), and governance notes with lock language but no D- or ADR number. `--json out.json` writes the full rows.
+
+## 2. Rediscovery check (every session, SAD PART 4 step 4d)
+
+Before creating a decision, ADR, term, source, dependency, skill, contract, risk or open question, search the entity's ledger, ADR register and `_meta/registers/`; cite what exists.
+
+## 3. Deep pass (paid, phase boundaries and campaigns)
+
+Reference implementation: a private synthesis project (`synth.mjs` classifies notes by domain, product, layer and kind; `decisions.mjs` compares ledger decisions pairwise within a domain). TypeSafe Jev, cached; key from the repo's `.env.local`, never printed. Lessons from the first run:
+- Ask *wholly* versus *partly* superseded; 11 of 12 "superseded" flags were partial.
+- A domain list that misses areas leaves decisions uncompared (27 of 120 in the first run); include company-structure and peer-company domains.
+- Treat results as leads to confirm, not findings.

package/evidence/skills/findability/inventory.rb

@@ -0,0 +1,41 @@
+# Findability inventory (SAD v3.0.16 §NEW.26). Free; no model calls.
+# Usage: ruby -E UTF-8 inventory.rb <entity folder> [vault root, default $VAULT_ROOT or the Documents folder] [--json out.json]
+require 'yaml'; require 'date'; require 'json'
+root = File.expand_path(ARGV[0] || abort("usage: inventory.rb <entity folder> [vault root] [--json out]"))
+vault = File.expand_path(ARGV[1] && !ARGV[1].start_with?('--') ? ARGV[1] : ENV['VAULT_ROOT'] || File.join(Dir.home, 'Documents'))
+jout = (i = ARGV.index('--json')) ? ARGV[i + 1] : nil
+files = Dir.glob("#{root}/**/*.md").reject { |f| f.include?('/_archive/') || f.include?('/node_modules/') }
+inbound = Hash.new(0)
+Dir.glob("#{vault}/**/*.md").each do |f|
+  next if f.include?('/node_modules/')
+  t = (File.read(f, encoding: 'UTF-8') rescue ''); me = File.basename(f, '.md')
+  t.scan(/\[\[([^\]|#]+)/) { |m| n = File.basename(m[0].strip); inbound[n] += 1 unless n == me }
+end
+gov = %w[planning planning-note architecture-spec spec research policy]
+lock = /\b(locked|lock\b|decided|in force|ratified)\b/i
+rows = files.map do |f|
+  t = File.read(f, encoding: 'UTF-8'); fm = nil; err = false
+  if t.start_with?('---')
+    begin; fm = YAML.safe_load(t.split(/^---\s*$/, 3)[1], permitted_classes: [Date, Time]) || {}; rescue StandardError; err = true; fm = {}; end
+  end
+  fm = {} unless fm.is_a?(Hash) || fm.nil?
+  rel = f.sub(root + '/', ''); body = t.split(/^---\s*$/, 3)[2] || t
+  { path: rel, folder: File.dirname(rel), type: fm&.dig('type'), authority: fm&.dig('authority'), governed: !!fm&.dig('governed-by'),
+    status: [fm&.dig('decision-status'), fm&.dig('status')].compact.join(' '), nofm: fm.nil?, yaml_error: err,
+    inbound: inbound[File.basename(f, '.md')], lock_language: !!(body =~ lock), cites_decision: !!(body =~ /\bD-\d{3}\b|ADR-\d{4}/) }
+end
+g = rows.select { |r| gov.include?(r[:type].to_s) }
+checks = {
+  'no frontmatter' => rows.select { |r| r[:nofm] },
+  'YAML errors' => rows.select { |r| r[:yaml_error] },
+  'orphans (no inbound wikilink)' => rows.select { |r| r[:inbound].zero? },
+  'governance docs missing governed-by' => g.reject { |r| r[:governed] },
+  'governance docs missing authority' => g.reject { |r| r[:authority] },
+  'authority gate (architectural+ in research/ or planning/)' => rows.select { |r| %w[constitutional strategic architectural].include?(r[:authority].to_s) && r[:folder] =~ %r{(^|/)(research|planning)(/|$)} },
+  'wholly superseded but not archived' => rows.select { |r| r[:status] =~ /\b(superseded|withdrawn)\b/i && r[:status] !~ /in part|partly/i },
+  'lock language without a D- or ADR number' => g.select { |r| r[:lock_language] && !r[:cites_decision] && r[:authority].to_s != 'exploratory' },
+}
+puts "Findability inventory: #{root} (#{rows.size} notes)"
+checks.each { |k, v| puts format('  %-58s %d', k, v.size) }
+checks.each { |k, v| next if v.empty? || k.start_with?('orphans'); puts "\n#{k}:"; v.first(15).each { |r| puts "  #{r[:path]}" } }
+File.write(jout, JSON.pretty_generate(rows: rows, checks: checks.transform_values { |v| v.map { |r| r[:path] } })) if jout

package/evidence/skills/foreshadowing-audit/SKILL.md

@@ -0,0 +1,183 @@
+---
+type: knowledge
+tags: [everything-ecosystem, skills, foreshadowing-audit]
+ai-model: claude
+created: 2026-05-15
+source: hybrid
+name: foreshadowing-audit
+description: >
+  Run the V[N] → V[N+1] foreshadowing audit. Verify that V[N] foreshadows
+  V[N+1]'s audience and capabilities — anything that will exist later must be
+  named or hinted at now, or V[N]'s identity gets revised when V[N+1] ships.
+  Also verify brand continuity invariants (I-series) hold across versions.
+  Brand-pillar discipline; CMO-sponsored. Per SAD foreshadowing discipline
+  (encoded in build-roadmap §19) + version-identity skill.
+  MANDATORY TRIGGERS: foreshadowing, foreshadowing audit, V1 to V2, V2 to V3,
+  version evolution, audience evolution, brand continuity, brand invariants,
+  one persona per version, what does V[N+1] add, version boundary, /foreshadowing-audit.
+---
+
+# Foreshadowing Audit Skill
+
+The Brand-pillar discipline that prevents brand whiplash across product versions. Runs at every version boundary.
+
+## Why foreshadowing-audit exists
+
+V[N] establishes an audience, a persona, a register. V[N+1] expands or shifts. If V[N+1] introduces audience or capabilities V[N] didn't foreshadow at all, existing users experience whiplash: "this isn't the product I signed up for."
+
+The discipline: **V[N] must foreshadow V[N+1]'s audience and capabilities.** Anything that will exist later must be named or hinted at now. The brand audit is what catches this.
+
+Companion to the [[../version-identity/SKILL|version-identity skill]] (one-new-persona-per-version rule). Together they prevent the two major brand-evolution failure modes:
+
+- **Surprise pivot** — V[N+1] introduces a persona V[N] didn't foreshadow → existing audience leaves
+- **Identity drift** — V[N+1] silently changes invariants V[N] established → trust erosion
+
+## When to invoke
+
+- **Approaching a version boundary** (authoring VERSION_SPEC for V[N+1])
+- **V[N] ship is imminent and V[N+1] articulation has begun** (parallel-track work)
+- **Brand changes are being proposed for an existing version** (e.g., V1.x patches that touch identity)
+- **The user explicitly asks for a foreshadowing audit**
+
+## The two audits
+
+### Audit 1 — Audience foreshadowing
+
+For each new audience V[N+1] introduces:
+
+1. **Is this audience visible in V[N]?** Either:
+   - Explicitly named (e.g., "V2 is for citizens who want to annotate the wiki")
+   - Hinted via affordances (e.g., V1 includes a "save for later" button that hints at the V2 personalization layer)
+   - Visible in the wiki / public artifacts (e.g., a roadmap page that shows the version-identities arc)
+2. **If not, what's the foreshadowing gap?** Surface specifically:
+   - "V2 introduces X audience. V1 has no mention of X. The closest hint is Y, which doesn't really cover this."
+3. **What can be added to V[N] (or V[N+1] articulation) to close the gap?** Concrete options:
+   - Add an affordance to V[N] that hints at X
+   - Reword V[N]'s public copy to acknowledge X is coming
+   - Explicitly name X in V[N]'s "what's next" / roadmap surfaces
+
+### Audit 2 — Invariant verification
+
+Brand invariants (I-series; a typical project defines I1–I9) are the things that must hold across versions. For each invariant:
+
+1. **Does V[N+1] preserve this invariant?** Check the V[N+1] artifacts (brand identity, voice, key surfaces) against the invariant statement.
+2. **If not, is this a deliberate change?** Either:
+   - The invariant needs updating (and the change is documented)
+   - V[N+1] needs adjustment to preserve the invariant
+3. **For deliberate changes:** is the change foreshadowed in V[N]? Same audit as Audit 1, applied to invariants rather than audiences.
+
+## The invariant pattern (I-series)
+
+A brand invariant has the form:
+
+```
+I1: <Invariant statement>
+- What it means in practice: <concrete description>
+- How V[N] expresses it: <specific surfaces / artifacts>
+- Risk if broken: <what happens to the audience's trust>
+```
+
+Example:
+
+```
+I3: The product speaks in the user's register, not the institution's.
+- What it means in practice: copy uses second-person + active voice + concrete
+  scenarios; doesn't sound like government documentation.
+- How V1 expresses it: every wiki article opens with "When you ___" or
+  "Your ___" framing; microcopy in error states is human, not stilted.
+- Risk if broken: The product reads like another corporate website; existing
+  audience disengages because the differentiator is the register.
+```
+
+V[N+1]'s foreshadowing audit verifies I3 still holds in every V[N+1] surface.
+
+## How to run a foreshadowing audit
+
+When this skill is loaded, the AI should:
+
+### Step 1 — Load the version-identities document
+
+Read `<entity>/brand/version-identities*.md` (or equivalent). Identify:
+- V[N]'s declared persona / audience
+- V[N+1]'s declared persona / audience
+- The continuity invariants (I-series)
+
+If no version-identities document exists, surface the gap — the audit needs this as input.
+
+### Step 2 — Run Audit 1 (audience foreshadowing)
+
+For each new audience or capability V[N+1] introduces, walk the visibility check. Produce:
+
+```
+Audience Foreshadowing Audit · V[N] → V[N+1]
+
+| V[N+1] addition | Foreshadowed in V[N]? | Gap | Proposed fix |
+|---|---|---|---|
+| <addition 1> | ✓ / ↺ / ✗ | <if not, what's missing> | <concrete option> |
+| ...
+```
+
+### Step 3 — Run Audit 2 (invariant verification)
+
+For each I-series invariant, walk the preservation check. Produce:
+
+```
+Invariant Verification · V[N+1]
+
+| Invariant | Preserved in V[N+1]? | Notes | Action |
+|---|---|---|---|
+| I1: <statement> | ✓ / ↺ / ✗ | <specific evidence or gap> | <action if needed> |
+| ...
+```
+
+### Step 4 — Surface the audit results
+
+Walk the operator through:
+- Which audiences need additional foreshadowing in V[N]
+- Which invariants are at risk in V[N+1]
+- Which gaps can be closed before V[N] ships (vs. which require V[N+1] adjustment)
+
+### Step 5 — Update artifacts
+
+For each accepted fix:
+- Update V[N] artifacts (if foreshadowing-by-adding-to-V[N])
+- Update V[N+1] artifacts (if adjusting V[N+1])
+- Update the version-identities document to reflect the audit
+- Update the brand foreshadowing inventory
+
+### Step 6 — Update the per-project orchestration HTML
+
+Per [[../../_ideas/build-roadmap-and-html-orchestration-2026-05-12|§32]], surface the audit results in the brand-pillar deliverables section of the orchestration HTML.
+
+## Posture
+
+Foreshadowing-audit runs in **office-hours mode**. The work is convergent (verifying invariants, finding gaps); sharp framing is appropriate.
+
+## What foreshadowing-audit is NOT
+
+- **Not a one-shot.** Audits run at every version boundary and whenever V[N+1] articulation surfaces a major change.
+- **Not a substitute for brand discipline.** The audit catches drift; it doesn't author the version-identities document or the invariants. Those are upstream.
+- **Not a Product-pillar check.** It's Brand-pillar work. Product-pillar capability changes that don't affect brand identity / persona / audience don't trigger it.
+
+## Relationship to other skills
+
+- [[../version-identity/SKILL|version-identity]] — produces the version-identities document this audit reads
+- [[../brand-pillar/SKILL|brand-pillar]] — auto-loads when brand work surfaces; foreshadowing-audit is one of its workflows
+- [[../articulation-closure/SKILL|articulation-closure]] — V[N+1]'s articulation closure should include a passed foreshadowing audit before Phase 2 begins
+
+## Backfill / missing assets
+
+Follow `operations/skills/_patterns/gate-backfill.md`. Skill-specific notes:
+
+1. **Detect** — V[N+1]+ capabilities vs foreshadowed / gap / N/A on shipped V[N].
+2. **Triage** — brand-discontinuity on shipping surfaces = blocker; pure V[N+1]
+   gaps = queued with version trigger.
+3. **Order** — audit shipped affordances first; patch foreshadowing only where
+   cheap; else record discontinuity + brand decision.
+4. **Freeze** — do not market or UI-promise red V[N+1] capabilities without a plan.
+5. **Exit** — audit grid exists; red cells have fix or recorded brand decision.
+
+## Status
+
+- **2026-05-14:** Initial authoring per build-roadmap §19 foreshadowing discipline.
+- **2026-07-26:** Backfill / missing-assets recovery mode added.