Customer-Facing Prose Hygiene

← Back to Enforcement Layer customer-facing-prose-hygiene.md

Customer-Facing Prose Hygiene

Established: 2026-05-18 (N=2 threshold reached) Owner: Hone (enforcement infrastructure) — codename hone Dewey: 410 (Enforcement) Load when: Writing, reviewing, or publishing any content to customer-facing scope

1. Why This Exists

VFT's internal AI agents operate with a shared vocabulary that is precise and load-bearing for agent-to-agent work. Codenames, artifact paths, authoring provenance markers, internal process language, and the AI org chart's specialist taxonomy are all optimized for internal use. That vocabulary reads as natural operating language to the agents who author it. To clients, it reads as professional-quality-undermining noise.

Two incidents proved memory-only was failing:

Precedent 1 — Paragon, 2026-05-07 A customer-facing portal milestone page on clients.valuefirstteam.com/paragon/... named USS staff (Leo Tristao, Carter McKay) and VFT travel logistics (Ryan in Brazil, international move) on the May 18 milestone. Caught post-publish. Captured as memory/feedback_no_internal_staffing_in_customer_docs.md. Scope at the time: one class of leak (people names).

Precedent 2 — Abs Company, 2026-05-18 A Current-State Brief on compass.valuefirstteam.com/abs-company/data-model exposed nine agent codenames in csb_agent_skill_inventory, phrases like "VFT property-index," "Hone in the explainer doc," "V/Sage/Pax + 88 specialist agents," "Showcase's prior mining," "Mirror found this on 2026-05-14," "Derived from V1 Part III tier 3," and similar leaks — approximately 47 violations across 14 of 15 rendered properties. Caught via a four-lens review. Required 1,039 lines of rewrites across 14 csb_* properties.

Two incidents in eleven days. Failure mode expanding, not narrowing.

The failure mechanism: Agents authoring content under orchestration inherit the orchestrator's vocabulary. Internal vocabulary is precise and load-bearing for handoffs. There is no explicit translation step at the authoring-to-publish boundary, so internal vocabulary survives to the rendered surface. Authors who are themselves AI agents do not naturally read their own codename in prose as noise — it reads as accurate attribution.

The cost: Deliverable quality degraded. Client trust eroded. Rework measured in hundreds of lines and multiple session-hours. The gateway pattern (Ledger, Canon) exists precisely for this class of problem. This skill specifies the enforcement that Ledger and Canon will implement.

2. When to Load This Skill

Load this skill before writing, reviewing, or publishing any content in the following scopes:

Surface Scope Trigger
clients.valuefirstteam.com/* (V1 portal) Any Listing, Project, or Company property write rendered to a client user
compass.valuefirstteam.com/* (V2 Compass) Story So Far, Current-State Brief (CSB), Future-State Data Model (FSDM), Library, Canvas, Walkthrough — any authored field
valuefirstteam.com/* (public website) Articles, show pages, methodology pages, Collective pages, course content — any authored field
HubSpot Listings rendered in portals or Compass listing_content_type values: document, fsdm, csb, roadmap_item, playbook — any hs_title or hs_body write
HubSpot Company or Contact properties rendered in portals Properties pulled into portal sections visible to client users
Sanity documents rendered to clients aiNativeShift, walkthrough, storysoFar, blogPost, tool, course, listing schema documents — body text, description, and prose fields
Customer-facing email bodies Any email sent via Correspondent/Gmail dispatches to client contacts

When in doubt: If the output will be read by anyone who is not a VFT internal team member or advisory committee member, this skill applies.

3. The Five Leak Classes

These are the categories of internal language that must not survive into customer-facing prose.

Class 1: Codenames

Agent codenames by their operating names. The full roster as of 2026-05-18:

Leaders (3): V, Sage, Pax

Specialists (91+ and growing): accord, aegis, alms, analyst, anvil, architect, archivist, atlas, audit, baldwin, beacon, blueprint, broadcast, canon, caption, catalog, chorus, chronicle, conductor, correspondent, counsel, courier, curator, dean, director, dub, echo, encore, envoy, exchange, forecast, forge, foundry, framer, herald, hone, horizon, klaxon, leaf, ledger, link, litmus, lookout, loom, marquee, marshal, mason, mender, meridian, mint, mirror, navigator, nexus, oracle, patron, pavilion, pixel, prelude, primer, prism, provost, pulse, q, quill, quinn, quorum, relay, sage, scout, scribe, scrivener, sentinel, settler, showcase, slate, spark, splice, squire, steward, sylvan, sync, tally, tether, tide, trellis, tributary, tuner, usher, valuestone, vault, vestibule, vigil, voice, waypoint, writ

At scan time: Generate the current list from .claude/agents/*.md filenames (strip .md extension). This roster grows as new agents are commissioned. Scanning the filesystem at runtime gives the most current list.

Codename violation examples:

  • "Showcase's prior mining of the data model" → violation
  • "Herald prepared this brief" → violation
  • "Per Architect's analysis" → violation
  • "The Ledger gateway refused this write" → violation (Ledger is internal infrastructure)
  • "Mirror found this on 2026-05-14" → violation

Note — V as letter: The letter "v" appearing as a variable name in a code block, as a version prefix in a version string (e.g., v1.2), or as part of a URL slug is NOT a violation. See Section 6 for false-positive guards.

Class 2: Internal Artifact Paths

Literal filesystem path substrings that reference VFT's internal monorepo structure.

Forbidden path fragments (case-insensitive substring match):

memory/
clients/
skills/
wiki/
docs/plans/
agents/
.claude/
apps/portal/src/
apps/website/src/
property-index/
Leadership/
data/agent-office
scripts/
explainer doc
internal Listing

Artifact path violation examples:

  • "Per the property-index/contact.json mapping" → violation
  • "Reference: memory/feedback_no_internal_staffing_in_customer_docs.md" → violation
  • "This aligns with what wiki/conventions.md specifies" → violation
  • "The apps/portal/src/sections/SubwayMapV3/ component renders this" → violation

Class 3: Authoring Provenance Markers

Phrases that reveal the internal authoring process, delivery cadence, or derivation chain.

Forbidden provenance phrases (case-insensitive substring match):

Snapshot built from
Derived from V1
Derived from Part
V1 [thing]     (e.g., "V1 /abs-company/data-model document")
Wave N output  (where N is a number or ordinal — "Wave 13 output", "Wave 1 deliverable")
Part II tier
Part III tier
from the explainer doc
from explainer
built from V1
commit [hash]
commit reference
per commit

Additional pattern — "V1" as provenance: The string "V1" in context of describing WHERE content came from is a violation. "V1 portal" as a product name (e.g., "Your V1 portal at clients.valuefirstteam.com") is NOT a violation — see Section 6.

Provenance marker violation examples:

  • "Snapshot built from V1 /abs-company/data-model document" → violation
  • "Derived from V1 Part III tier 3" → violation
  • "Wave 13 output — Navigator + Showcase" → violation

Class 4: Process Language

Internal workflow descriptions that describe VFT's operational machinery.

Forbidden process language phrases (case-insensitive substring match):

subagent
expertise pack
enforcement skill
gateway refused
Ledger refused
Canon refused
canon mutation
schema-rename routing
FSDM/CSB pipeline
dispatch
spawn [agent]
agent team
three-org model         (as internal organizational framing — see Section 6)
customer org
operations org
finance org
VFT internal
VFT delivery surface
VFT property-index
skill pack
skill inventory         (when used as a VFT agent skill inventory — see Section 6)
88 specialist agents
88 agents
94 agents
the [codename] agent    (e.g., "the Architect agent")

Process language violation examples:

  • "Dispatched to Showcase for implementation" → violation
  • "Subagent spawning confirmed this pattern" → violation
  • "Ledger refused the write due to schema mismatch" → violation
  • "VFT property-index shows this field as enumerable" → violation
  • "V/Sage/Pax + 88 specialist agents manage this" → violation

Class 5: AI-Org-Chart Taxonomy

Language that reveals VFT's internal AI leadership structure in ways a client should not be reading.

Forbidden taxonomy phrases (case-insensitive substring match):

AI Leadership Team         (as internal org framing)
AI leadership team
Three-Org Model            (as internal org framing)
Customer Org               (as VFT internal org label)
Operations Org             (as VFT internal org label)
Finance Org                (as VFT internal org label)
specialist agents
VFT agents
our agents
the agent team
AI org chart
agent roster
VFT's AI
our AI team

Taxonomy violation examples:

  • "The AI Leadership Team designed this architecture" → violation
  • "VFT's specialist agents handle this dimension" → violation
  • "This reflects the Three-Org Model's customer-facing layer" → violation
  • "Our agents synthesized this from 14 client sessions" → violation

4. The Scan Rule

Scan algorithm for agents and gateways:

FOR EACH string property being written to customer-facing scope:
  FOR EACH term in the Canonical Dictionary (Section 5):
    IF term appears in property value (case-insensitive substring):
      FLAG as violation with:
        - property name
        - leak class (1-5)
        - matched substring
        - character offset (optional, for multi-violation properties)
  
  IF violations found:
    REFUSE the write
    RETURN structured violation list
  ELSE:
    PERMIT the write

Scope detection rule (for Ledger and Canon implementations):

A property write is in customer-facing scope when ANY of the following is true:

  1. Ledger writes: The target object is Listing (0-420) AND listing_content_type is one of: document, fsdm, csb, roadmap_item, playbook, methodology, case_study, or is blank/unset (conservative default). Also applies to hs_title and hs_body on ANY Listing write.

  2. Ledger writes: The target object is Company (0-2) AND the property being written is one of: portal_notes, subway_map_config, story_so_far, csb_* (any property with csb_ prefix), fsdm_* (any property with fsdm_ prefix), or any property whose name contains client_facing, portal_, or compass_.

  3. Ledger writes: The target object is Contact (0-1) AND the property value will be rendered in a customer-accessible view (properties containing compass_, portal_, public_).

  4. Canon writes: The target Sanity document _type is one of: aiNativeShift, storysoFar, walkthrough, listing, blogPost, tool, course, episode, show. AND the field being written is a prose field (body, description, hs_body, content, summary, excerpt, overview).

  5. Any write to a Compass-surface document: Any Sanity document with a slug containing a client slug pattern (/abs-company/, /paragon/, /gorout/, etc.) or with clientSlug set.

  6. Agent-level determination (pre-gateway): When an agent is authoring content for a surface listed in Section 2, the agent must scan before handing off to Ledger or Canon. The agent-level scan is the first gate; the gateway scan is the second.

Conservative default: When uncertain whether a property renders to customers, treat it as customer-facing scope. False refusals can be overridden (see Section 5); false approvals cannot be un-published without cost.

5. The Canonical Scan Dictionary

The following terms and patterns constitute the canonical scan dictionary. Gateways (Ledger, Canon) and agents both read from this list. Case-insensitive substring match applies unless noted.

5.1 Codename Dictionary

At scan time, resolve the full agent codename list dynamically from:

  • .claude/agents/*.md filenames (strip .md extension, exclude _template)

For sessions where filesystem access is not available, use this static snapshot (updated 2026-05-18):

v, sage, pax, accord, aegis, alms, analyst, anvil, architect, archivist, atlas, audit,
baldwin, beacon, blueprint, broadcast, canon, caption, catalog, chorus, chronicle,
conductor, correspondent, counsel, courier, curator, dean, director, dub, echo, encore,
envoy, exchange, forecast, forge, foundry, framer, herald, hone, horizon, klaxon, leaf,
ledger, link, litmus, lookout, loom, marquee, marshal, mason, mender, meridian, mint,
mirror, navigator, nexus, oracle, patron, pavilion, pixel, prelude, primer, prism,
provost, pulse, q, quill, quinn, quorum, relay, scout, scribe, scrivener, sentinel,
settler, showcase, slate, spark, splice, squire, steward, sylvan, sync, tally, tether,
tide, trellis, tributary, tuner, usher, valuestone, vault, vestibule, vigil, voice,
waypoint, writ

Word-boundary rule for codenames: Codename matches require a word boundary on both sides, OR the codename appears in a possessive form ('s), OR the codename is used as a subject/object in a sentence about the agent performing an action.

Examples of word-boundary application:

  • "showcase" in "Showcase built this page" → VIOLATION (sentence-level subject, capitalized)
  • "showcase" in "A showcase of our work" → NOT a violation (common noun, different meaning)
  • "herald" in "Herald prepared the brief" → VIOLATION
  • "herald" in "a harbinger, a herald of change" → NOT a violation (common word, contextual)
  • "forge" in "Forge authored this article" → VIOLATION
  • "forge" in "forged in experience" → NOT a violation

Short codenames with high false-positive risk: v, q, link, leaf, mint, forge, echo, pulse, relay, tide, vault, proxy, wave, arc — apply word-boundary checking strictly. When these appear as part of compound words, product names, or technical terms that are not agent references, they are not violations.

5.2 Path Fragment Dictionary

All path substrings below trigger a violation when found in prose fields:

memory/
clients/
skills/
wiki/
docs/plans/
.claude/
agents/
apps/portal/src/
apps/website/src/
property-index/
Leadership/
data/agent-office
scripts/hubspot/
scripts/sanity/
scripts/google/
/AGENT.md
codebase-index.md
explainer doc
internal Listing

5.3 Provenance Marker Dictionary

Snapshot built from
Derived from V1
Derived from Part
Wave [0-9]               (regex: "Wave \d")
Wave [0-9]+              (regex: "Wave \d+")
from the explainer
per the explainer
built from V1
V1 [a-z]                 (regex: "V1 [a-z]" — "V1 document", "V1 portal" when used as provenance)
commit [0-9a-f]{6,}      (regex: commit hash references)
per commit
Part [IVX]+ tier         (regex: Roman numerals indicating internal document tiers)
Part [0-9]+ tier

5.4 Process Language Dictionary

subagent
expertise pack
enforcement skill
gateway refused
ledger refused
canon refused
canon mutation
schema-rename routing
FSDM/CSB pipeline
the dispatch
spawn [a-z]              (regex: "spawn" followed by an agent codename)
spawned [a-z]            (regex: "spawned" followed by an agent codename)
VFT property-index
VFT delivery surface
VFT internal
skill inventory          (when in context of agent capabilities — not a client's skill inventory)
88 specialist
94 agents
the [codename] agent     (e.g., "the Architect agent", "the Mirror agent")

5.5 AI-Org-Chart Taxonomy Dictionary

AI Leadership Team
three-org model
customer org
operations org
finance org
specialist agents
VFT agents
our agents
agent roster
AI org chart
our AI team
VFT's AI

6. What Is NOT a Violation

High-frequency false-positive guards. These patterns match words in the dictionary but are legitimate in customer-facing prose.

Pattern Why It's Not a Violation
v1.2, v2.0, v3 (version strings) Version numbers are not agent references
"V1 portal" as product name When referring to the V1 portal as a client-facing product, not as internal provenance
"v" as a variable name in a code block Code blocks are technical context, not prose
"wave" as a generic word ("wave of disruption", "tidal wave") Common word; requires agent-action context to be a violation
"forge" in "forged in" / "forge ahead" Common word; requires capitalized agent-subject context
"echo" as a product name, AWS service, or generic word Context determines; "Echo reports" → violation; "echo chamber" → not
"herald" as historical/literary term Common word; requires agent-subject context
"leaf" as botanical term Common word
"mint" as flavor or financial term Common word
"link" as URL or chain metaphor Common word; "Link analyzed..." → violation
"relay" as sports/communication term Common word; "Relay reports..." → violation
"vault" as safe/architecture term Common word; "Vault indexed..." → violation
"tide" as ocean/metaphor Common word; "Tide assessed..." → violation
"pulse" as health metric or generic Common word; "Pulse scored..." → violation
Q as a mystery, letter, or entertainment reference Only a violation when "Q reports", "per Q's analysis" etc.
Customer-side staff names The client's own people — explicitly appropriate to surface
Client's own internal path references A client's own ~/Documents/... style reference is fine
The client's own HubSpot portal IDs Those ARE customer-internal; surfacing them is appropriate
"AI" as a generic technology term "Our AI-powered platform" is fine; "our AI agents" → violation
navigator as product/compass metaphor "Navigate to the next page" is fine; "Navigator prepared..." → violation
catalyst as chemistry/program name "The Catalyst program" (our AI-Native Shift program brand name) is fine
compass as product name "Your Compass" referring to the client-facing product is fine
blueprint as architectural noun "The blueprint for your data model" is fine; "Blueprint drew..." → violation

Decision rule for ambiguous cases: If the word is used as a subject or agent performing an action (e.g., "Architect designed", "Sentinel found", "Mirror verified"), it is a violation regardless of capitalization. If it is used as a common noun with no agent-subject relationship, it is not a violation.

7. Override Mechanism

There are rare legitimate cases where a scan term appears in customer-facing prose without being a violation — for example, a retrospective changelog post that uses "Wave 9" as a feature-release name, or a methodology document that references the "Value Path" alongside the word "arc."

Override syntax:

<!-- HYGIENE-EXCEPT: {reason} -->
{content containing the otherwise-flagged term}
<!-- END-HYGIENE-EXCEPT -->

In HubSpot Listing or Company property values (where HTML comments are stripped), use the JSON override wrapper:

{
  "_hygiene_exception": "reason for exception",
  "value": "The actual content with Wave 9 as a feature name here"
}

Ledger and Canon parse the _hygiene_exception key and log it before permitting the write.

Override rules:

  1. The reason must be explicit — vague reasons like "approved" or "needed" are rejected
  2. Override markers are loud by design — easy to grep for, hard to abuse silently
  3. Overrides are logged to Echo's pattern memory for trend tracking
  4. More than three overrides in a single write batch requires human review before the batch proceeds

Searching for overrides: grep -r "HYGIENE-EXCEPT" apps/ wiki/ docs/ or grep "hygiene_exception" will surface all active exceptions.

8. Echo-Style Logging

When a violation is caught and corrected (or a write is refused), the catching agent logs to Echo's pattern memory.

Log format:

Pattern name: customer-facing-prose-hygiene-violation
Date: YYYY-MM-DD
Surface: [surface name — e.g., compass.valuefirstteam.com/abs-company/data-model]
Detected by: [agent codename that ran the scan]
Leak class: [1-5]
Violations: [count]
Violation detail: [matched terms and properties]
Resolution: [corrected | refused-pending-correction | overridden with reason]

Where to write: Append to /home/coach_chris/.claude/projects/-mnt-d/memory/pattern_internal_agent_prose_leakage.md — the Echo file where this pattern is tracked.

Trend signal: If violations appear three or more times in a week from the same agent or the same surface, surface to V as a structural authoring pattern failure rather than a one-off hygiene miss. The fix is to update the authoring agent's startup protocol to load this skill — not to rely on gateway refusal as the sole gate.

9. Implementation Notes for Ledger and Canon

This section is the specification for the gateway implementation wave. The implementation agents (Squire or domain agents) build the scan from this skill.

Ledger scan specification

Trigger: Any write where listing_content_type matches the customer-facing set (Section 4), or any csb_* / fsdm_* property write on Company, or any write to a property with portal_ / compass_ in its name.

Scan target: All string-type properties in the write payload.

Scan algorithm: Case-insensitive substring match against Sections 5.1-5.5. Word-boundary application per Section 5.1 for short codenames.

Refusal response format:

{
  "refused": true,
  "reason": "customer_facing_prose_hygiene",
  "violations": [
    {
      "property": "hs_body",
      "leak_class": 1,
      "leak_class_name": "codename",
      "matches": ["architect", "herald"],
      "context": "...per Architect's analysis and Herald's relationship brief..."
    }
  ],
  "remediation": "Remove or replace flagged internal language. Load skills/enforcement/customer-facing-prose-hygiene.md for the full correction guide.",
  "override_available": true
}

Refusal display to caller:

Writes refused — N hygiene violations across M properties.
Violations: [property → leak class → matched terms]
Correct the prose or apply HYGIENE-EXCEPT override with explicit reason, then retry.

Canon scan specification

Trigger: Any write to a Sanity document of type aiNativeShift, storysoFar, walkthrough, listing, blogPost, tool, course, episode, or any document with clientSlug set. Scan only prose fields (body, description, content, summary, excerpt, overview, hs_body).

Same scan algorithm and refusal response format as Ledger.

Post-verify requirement: Canon's "complete" confirmation still requires the post-write GROQ verification query (per memory/feedback_canon_verify_after_write.md). If the scan passes, write proceeds. Canon verifies the written value matches intent via read-back.

10. Related Skills

  • skills/enforcement/vf-platform-context.md — runtime enforcement mental model (load every session)
  • skills/enforcement/vf-output-enforcement.md — pre-delivery output scanning (covers forbidden language; this skill adds the internal-vocabulary layer)
  • skills/enforcement/ledger-gateway-override.md — HubSpot write gateway enforcement pattern
  • wiki/agent-guide.md § Gateway patterns — canonical gateway routing (Ledger, Canon)
  • wiki/conventions.md § Language rules — forbidden customer-facing language (separate but complementary)
  • memory/feedback_no_internal_staffing_in_customer_docs.md — Precedent 1 capture (narrower, Class 1 only)
  • memory/feedback_gateways_reactive_not_preventive.md — the policy that required N=2 before this gateway was warranted
  • /home/coach_chris/.claude/projects/-mnt-d/memory/pattern_internal_agent_prose_leakage.md — Echo's pattern file (where violations are logged)