# Stencil — Everything in `avidtech6/pact` (Consolidated Dossier)

> **Source repo**: `avidtech6/pact` (a sub-folder of `avidtech6/freshvibestudio`, private, MIT). Cloned via the `GITHUB_PAT_FG_1` PAT.
> **Compiled**: 2026-07-21 by Mavis from a full read of every file under `pact/` that references "stencil" (case-insensitive).
> **Copy-paste box**: paste the content below this line into any chat / doc.

---

## 0. TL;DR

In the Pact, **Stencil** is the **authored, declarative, technology-agnostic source of truth for visual structure and layout** in the FreshVibe Studio platform. It sits in the middle of the **Visual Truth Pipeline (VTPS)**:

```
Pact → Blueprint → Stencil → VSIL-App → Codex → Sketch
```

Stencil is the **single confirmation gateway**: nothing proceeds to VSIL-App, Codex, or Sketch until Stencil is explicitly confirmed. It is **branchable** (you can fork visual exploration), **deterministic** (same Blueprint + same author intent = same output), and **reversible** (every element traces back to a Pact fragment via `@pact:` DNA tags).

> **Important historical baggage**: the word "Stencil" was used for a **completely different thing** in FreshVibe Way v5.1 (`pact/legacy/freshvibe-way/v5.1/11-import-mode.md`): an auto-generated, machine-derived snapshot of a *foreign* project's DOM used during Import Mode. That older meaning is **archived as legacy**. The current meaning is the authored, design-time visual layout. The two have nothing to do with each other; the v5.1 docs explicitly describe the older Stencil as `pact/imports/<id>/stencil.json`.

---

## 1. Canonical Sources (the two real specs)

There are exactly **two constitutional Stencil files** in the repo, and every other mention refers back to these:

### 1.1 `pact/pipeline/stencil/stencil.md` — *Stencil System Specification (SSS)*

**File purpose**: defines Stencil's **authoritative constitutional role** in the Visual Truth Pipeline. This is the spec the rest of the system cites.

Key fragments (paraphrased — see file for exact text):

- **`pipeline.stencil.definition.what.is.stencil.001`** — "Stencil is the authored, declarative, technology-agnostic source of truth for UI structure and layout. Stencil declares regions, elements, geometry, hierarchy, and intent in a form that can be rendered into concrete UI frameworks. Stencil is the origin of the visual truth pipeline, not derived from Codex."
- **`pipeline.stencil.definition.scope.001`** — Stencil receives structural specs from **Blueprint** and produces authored declarations that proceed to **VSIL-App**. Forward-only. Cannot receive truth from VSIL-App, Codex, or Sketch.
- **`pipeline.stencil.confirmation.gateway.only.001`** — "Stencil is the **sole and only confirmation gateway** in the Visual Truth Pipeline. No element may proceed from Stencil to VSIL-App without passing confirmation validation. Bypassing the Stencil confirmation gateway is a constitutional violation."
- **`pipeline.stencil.confirmation.validation.checks.002`** — Confirmation requires: (1) elements match Blueprint surface anatomy, (2) region structure matches Blueprint, (3) deterministic output, (4) no contradictions with referenced Pact fragments, (5) visual intent accurately represented.
- **`pipeline.stencil.confirmation.semantics.irreversible.003`** — Confirmation is **irreversible** through normal workflow; undoing it requires explicit governance rollback with documented justification.
- **`pipeline.stencil.branching.is.branchable.001`** — Stencil is branchable. Authors can fork variants from confirmed Stencils for creative exploration without affecting canonical pipeline.
- **`pipeline.stencil.branching.merge.rules.003`** — Merge requires (1) re-validation against current Blueprint, (2) governance resolution of conflicts, (3) re-passing confirmation, (4) then proceeds through VSIL-App/Codex normally.
- **`pipeline.stencil.allowed.*`** (3 fragments) — Stencil is allowed to receive Blueprint specs, author declarative UI declarations (regions/elements/layout/interaction), create branch variants for exploration.
- **`pipeline.stencil.not.allowed.*`** (3 fragments) — Stencil is NOT allowed to: receive truth from downstream stages, produce rendered output, skip VSIL-App, bypass confirmation, become a source of truth for Blueprint/Pact.
- **`pipeline.stencil.blueprint.relationship.*`** (3 fragments) — Stencil derives from Blueprint. Must validate against Blueprint. May propose Blueprint updates through governance, never directly.
- **`pipeline.stencil.sketch.relationship.no.direct.connection.001`** — Stencil has **no direct connection to Sketch**. Influence flows `Stencil → VSIL-App → Codex → Sketch` only.
- **`pipeline.stencil.idea.net.relationship.*`** (3 fragments) — Stencil is in the **Visual Universe**; Idea Net is in the **Conceptual Universe**. Independent branching; linked only via governance.
- **`pipeline.stencil.invariant.structural.determinism.001`** — Same Blueprint input + same authored declarations = same output. Non-determinism = pipeline error.
- **`pipeline.stencil.invariant.region.correspondence.002`** — Stencil regions must derive from Blueprint anatomy 1:1 or with documented expansion.
- **`pipeline.stencil.invariant.blueprint.conformance.003`** — Declarations must not contradict Blueprint.
- **`pipeline.stencil.invariant.pact.reference.004`** — Every element must reference its originating Pact fragment via `@pact:` DNA tag. **No tag = constitutional violation**.
- **`pipeline.stencil.invariant.reversibility.005`** — Every element traceable back to its originating Blueprint + Pact fragment. Orphans = constitutional risk.
- **`pipeline.stencil.timing.*`** (3 fragments) — Author only after Blueprint is validated+confirmed; confirm before any downstream work; on Pact changes propagate in order: Pact → Blueprint → Stencil re-author → re-confirm → VSIL re-derive → Codex → Sketch.
- **`pipeline.stencil.visual.first.guarantees.*`** (4 fragments) — Visual-first, technology-agnostic, creative-freedom-within-Blueprint, **explicit-not-implicit intent**. "Authors must declare regions, elements, geometry, hierarchy, and relationships explicitly in Stencil. Implicit intent creates ambiguity that propagates through the pipeline."
- **`pipeline.stencil.mainline.integration.rules.*`** (3 fragments) — Single canonical Stencil, only confirmed Stencil may enter MAINLINE, version tracking mandatory.
- **`pipeline.stencil.dna.interoperability.*`** (3 fragments) — Mandatory `@pact:`, `@deps:`, and `@lineage:` tags on every element.
- **`pipeline.stencil.trace.atlas.interoperability.*`** (3 fragments) — Trace Atlas observes all Stencil events (create, modify, confirm, branch, merge) for forensic trail and drift detection.
- **`pipeline.stencil.vtps.interoperability.*`** (5 fragments) — Stencil is stage 3 of 6 in VTPS. Sole confirmation gateway. Forward-only truth. Determinism + reversibility guarantees required by VTPS.

### 1.2 `pact/platform/stencil/stencil.md` — *Platform Stencil Spec*

A **shorter companion** to the SSS, focused on the *implementation contract* of Stencil (vs. the SSS which focuses on constitutional role):

- **`platform.stencil.definition.what.is.stencil.001`** — "Stencil is the declarative, technology-agnostic description of UI structure and layout, **derived from Codex** and suitable for rendering into concrete UI frameworks."
  - ⚠️ **Note the conflict**: this fragment says "derived from Codex" but the SSS says Stencil is the *origin*, not derived. This is the documented gap from `audit/SECOND-GAP-ANALYSIS.md` §3.1 / §4.1 / §4.3 — see §7 below.
- **`platform.stencil.definition.region.001`** — A Stencil **region** is a logical grouping of UI elements that share a purpose, layout context, or interaction model — mid-level structure between surfaces and components.
- **`platform.stencil.law.stable.structure.001`** — For a given Codex input, Stencil must produce a stable structural tree; structural changes must be explicit and diffable.
- **`platform.stencil.law.layout.determinism.001`** — Layout decisions must be deterministic + reproducible across runs (visual diffing + snapshot comparison).
- **`platform.stencil.behaviour.interaction.mapping.001`** — Interactive elements must be explicitly mapped to Codex interactions, preserving intent.

### 1.3 `pact/pipeline/codex/codex-overlays/vibecoder/overlay-stencil-authoring.md`

**Status**: NEW (v0018.4 addendum). **Source**: Codex-v0018.4 §29, fragment `vibecoder.stencil.authoring.001`.

This is the **VibeCoder authoring tool spec** — the actual editor surface where a human designs a Stencil. Defines:

- **DOM structure**: `div.stencil-authoring` containing a `div.stencil-toolbar` (40px high, add-region / add-component dropdowns / undo / redo / preview), a `div.stencil-canvas` (with horizontal+vertical 8px rulers and draggable `div.stencil-region` containers with `region-handle` top/bottom grips), and a `div.stencil-properties` right panel (280px collapsible).
- **Region types**: header (60px default, 40-120), footer (48px), sidebar (100% height, 100-400), content (flex:1), list (200px), grid (200px).
- **Region visual states**: default (1px dashed border), selected (1px solid accent + 5% accent bg), hover, dragging (2px solid + 10% bg).
- **Component types**: button (44×44), input (100%×44), card (160×120), image (100%×16:9), text (200×auto), icon (24×24).
- **Properties panel sections**: General (name, description, category: app/landing/settings/form/dashboard/custom), Dimensions (375×812 mobile default), Breakpoints (mobile <768, tablet 768-1024, desktop >1024 → 375×812, 768×1024, 1440×900), Metadata (created/modified dates, Export Stencil button).
- **Behaviour rules** (8 fragments): create / resize / move region; add / edit component; preview; undo; redo.
- **Invariants**: nesting max 3 levels; regions cannot overlap (auto-resolve); max 50 components per region; units px/%/vw/vh/auto; preview always reflects current state; undo history max 50; **all resize/move snaps to 8px grid**.
- **Snap config**: grid size 8px, snap threshold 5px, ruler increment 8px.
- **Export format** (VSIL-App JSON shape with `stencilId`, `name`, `breakpoints`, `regions[]` with `id`/`type`/`position`/`dimensions`/`children`, and `metadata.created`/`modified`/`version`).
- **Inherits from**: core-layout, core-behaviour. Themeable via Design System tokens (`ds.component.*`, `ds.spacing.*`, `ds.grid.*`, `ds.radius.component.*`).

This overlay was created because the engine-alignment audit (`pipeline/codex/codex-overlays/alignment/MISMATCH-TABLE-ENGINE-ALIGNMENT.md` §4.5) flagged **"Stencil authoring: MISSING → NEW → overlay-stencil-authoring.md"**.

---

## 2. The Visual Truth Pipeline (VTPS) — where Stencil fits

Pact defines a 6-stage pipeline. Stencil is **stage 3**.

From `pipeline/architecture-map.md`, `pipeline/vsil/vsil-app.md`, `pipeline/sketch/sketch.md`, `pipeline/blueprint/blueprint.md`, and `platform/_core/platform-architecture.md`:

```
Pact  →  Blueprint  →  Stencil  →  VSIL-App  →  Codex  →  Sketch
(frag)   (structural) (authored)  (semantic)  (struct)  (visual preview)
```

Per-stage role:

| Stage | Role | Truth source | Key rule |
|---|---|---|---|
| **Pact** | Constitutional authority | — | Supreme. All DNA tags reference back here. |
| **Blueprint** | Structural specifications (anatomy, surfaces, relationships) | Pact | Must not be conflated with Codex or Sketch. Deterministic for given Pact input. |
| **Stencil** | **Authored declarative visual layout** (regions, elements, geometry) | Blueprint | **Sole confirmation gateway**; no element proceeds without confirmation. |
| **VSIL-App** | Semantic interpretation of confirmed Stencil (geometry, objects, relationships, intent) | Stencil | Cannot render pixels. Derivation is automatic upon Stencil confirmation. |
| **Codex** | Structured system representation (the executable shape) | VSIL-App | Deterministic; same Stencil → same Codex. |
| **Sketch** | Runtime, interactive visual preview | Codex | Terminal stage. No pipeline output. |

**Forward-only rule**: at every stage, truth flows left → right. Reverse flows are constitutional violations. Stencil specifically is forbidden from receiving truth from VSIL-App, Codex, or Sketch.

**The two competing flow statements** (from `audit/SECOND-GAP-ANALYSIS.md` §4.1):
- `platform/_core/architecture.md` and `platform/_core/platform-architecture.md` say: `STENCIL → CODEX → SKETCH` (4 stages, no VSIL-App).
- `pipeline/*` and `codex-v0018.2` say: `STENCIL → VSIL-App → CODEX → SKETCH` (5 stages, with VSIL-App in the middle).
- The newer pipeline specs (post-v0018.2) consistently use the 5-stage form, which is the canonical one. The 4-stage form is legacy architecture that was never fully purged. See §7.

---

## 3. Stencil's contracts with neighbouring stages

### 3.1 Stencil ↔ Blueprint (upstream source)

- Stencil **receives** structural specs from Blueprint surfaces.
- Blueprint provides anatomy definitions, relationship declarations, constraint boundaries.
- Stencil **must not contradict** Blueprint. Contradictions = constitutional violations unless processed through governance.
- **Stencil may propose Blueprint updates** through explicit governance workflow (when exploration reveals gaps), but may not unilaterally alter Blueprint.
- Per `pipeline/blueprint/blueprint.md`: "Blueprint surfaces must not bypass or skip any step in the constitutional pipeline. Surface specifications must flow through `Stencil → VSIL-App → Codex → Sketch`. Shortcuts that generate Codex directly from Blueprint without Stencil ... are forbidden constitutional violations."
- **Blueprint validation is mandatory** before Stencil can be confirmed (`pipeline.stencil.blueprint.relationship.must.validate.002`).

### 3.2 Stencil ↔ VSIL-App (downstream derivation)

- VSIL-App **derives from confirmed Stencil only**. Derivation is automatic on confirmation; no manual intervention.
- VSIL-App cannot receive unconfirmed Stencil. VSIL-App from unconfirmed Stencil = constitutional violation.
- VSIL-App interprets authored declarations as geometry, spatial relationships, interaction models, and behavioural specs — **but does not render pixels**.

### 3.3 Stencil ↔ Codex (the gap — see §7)

- Per SSS: Codex derives from VSIL-App (which derives from Stencil). Codex is 2 stages downstream.
- Per `platform/stencil/stencil.md`: Stencil is "derived from Codex". ← **Contradicts the SSS.**
- Per `platform/builder/contract-v1.1.md`: Builder is the only subsystem authorized to apply FVW to a Stencil and emit VSIL + App-Codex. Builder reads `stencil_id` and `source_fingerprint` (hash of input Stencil); VSIL must be byte-identical for same Stencil. `vsil_fingerprint` must be stable across runs and machines; no timestamps, machine IDs, randomness, comments, or debug strings in the VSIL body.

### 3.4 Stencil ↔ Sketch (no direct connection)

- Per `pipeline/sketch/sketch.md` (3 fragments): Sketch has no direct connection to Stencil. Sketch receives truth **exclusively from Codex**, which is derived from VSIL-App, which is derived from Stencil. "Sketch must not receive runtime feedback or influence from Stencil directly. Stencil intent manifests in Sketch only through the complete pipeline transformation."
- This is the "broken chain of custody" prevention rule.

### 3.5 Stencil ↔ Idea Net (different universe)

- Stencil lives in the **Visual Universe** (concrete UI structure).
- Idea Net lives in the **Conceptual Universe** (abstract concepts, branches, links).
- They are **independent branching systems**. Visual exploration at Stencil level does not create corresponding conceptual branches in Idea Net. Linked only through explicit governance.
- A conceptual Idea promoted through the pipeline → `Idea → Idea Net → Pact → Blueprint → Stencil`. Stencil never receives Ideas without Blueprint mediation.

### 3.6 Stencil ↔ Engines

Per `behaviour/engines.behaviour.md` and `platform/engines/engines.md`:
- "An engine is a deterministic executor that **transforms Codex and Stencil** into concrete runtime behavior while respecting Pact constraints."
- Engines consume the Stencil-authored state (along with Codex) and produce runtime behavior. They are downstream of the pipeline.

### 3.7 Stencil ↔ Builder

Per `platform/builder/contract-v1.1.md` and `contract.md`:
- The Builder is the **only subsystem authorized** to "apply FVW" to a Stencil and emit VSIL.
- Inputs to Builder: approved Stencil, module metadata, FVW version.
- Outputs: VSIL Document (`vsil_id`, `stencil_id`, `source_fingerprint`, `vsil_fingerprint`, `reproducibility_guarantee: true`, deterministic body), plus Bundles (BSG/BR/BEB).
- Determinism: byte-identical VSIL for same Stencil + same FVW version + same module metadata. Must be reproducible across runs and machines.
- v1.1 Scaffolding rule: in Studio Emulation Mode, Builder may produce app-level scaffolding **only when explicitly invoked by Orchestrator**; must NOT infer scaffolding from Stencil content. Scaffolds are `/modules/<module-id>/` with `module.seed` + `module.meta` only, and 4 empty subfolders: `codex/`, `recipe/`, `trace/`, `runtime/`. No pre-population.
- Lineage rule: every internal subsystem that produces a constitutional artefact must record lineage (Stencil, Module Codex, FVW version, etc.) in the artefact and in the Trace Atlas.

### 3.8 Stencil ↔ VibeCoder workspace (governance)

Per `governance/vibecoder-workspace.governance.md`:
- Vibe Layout in VibeCoder may **propose and apply changes** to Stencil, VSIL-App, Codex, Sketch, Idea, and Idea Net — but every change must be (1) explainable in natural language, (2) reversible, (3) traceable into Trace Atlas, (4) aligned with Pact and Blueprint. **Must never bypass Pact or Blueprint**.
- Coder Layout (manual code editing) must trigger sync checks against Stencil, Codex, Sketch, Idea, and Idea Net. **No silent changes**.
- Primary VibeCoder surfaces: **Stencil editor, Preview, Inspector** (Chip: Vibe).

### 3.9 Stencil ↔ Trace Atlas

Per `pipeline/trace-atlas/trace-atlas.md` and SSS §trace-atlas:
- Trace Atlas observes and records every Stencil pipeline event: creation, modification, confirmation, branching, merge.
- When Stencil is confirmed, Trace Atlas records the transformation event that enables VSIL-App to proceed.
- **Drift detection**: Trace Atlas monitors Stencil for changes that contradict Blueprint or that introduce elements without proper Pact backing. Triggers governance alerts on drift.

### 3.10 Stencil ↔ Execution

Per `behaviour/execution.behaviour.md`:
- "Transitions from Stencil → Codex → Sketch must be **explicit, atomic, and reversible**, with clear validation at each stage to ensure structural integrity and prevent invalid intermediate states."

### 3.11 Stencil ↔ Governance

Per `governance/governance.md`:
- Governance validates Stencil confirmation workflows, addresses Trace Atlas drift reports, and can **rule on Stencil confirmation exceptions** (but cannot alter confirmation semantics without proper governance workflow).
- Governance conducts **cascading impact assessment** before any Pact amendment: identifies all Blueprint surfaces, Stencil authored fragments, VSIL interpretations, Codex encodings, Sketch renderings affected. Approval only when impact is understood and remediation path defined.

---

## 4. Stencil invariants (the rules that cannot be broken)

Synthesized from `pipeline/stencil/stencil.md`, `platform/stencil/stencil.md`, `behaviour/execution.behaviour.md`, `behaviour/sketch.behaviour.md`, `behaviour/vsil.behaviour.md`, and the codex overlays:

1. **Determinism** — same Blueprint + same authored declarations = same output. Required for visual diffing, snapshot comparison, regression detection.
2. **Region correspondence** — every Stencil region traces to a Blueprint anatomy element (1:1 or documented expansion).
3. **Blueprint conformance** — Stencil declarations must not contradict Blueprint specifications.
4. **Pact reference (DNA tag)** — every element carries `@pact:[fragment_id][:line_range]`. No tag = constitutional violation.
5. **Dependency tag** — every element declares `@deps:` listing required Pact + Blueprint fragments (for transitive impact analysis).
6. **Lineage tag** — every element declares `@lineage:` (creation / modification / deprecation history).
7. **Reversibility** — every element traceable back through Blueprint to its originating Pact fragment. Orphans = constitutional risk.
8. **Forward-only truth** — Stencil must not receive truth from VSIL-App, Codex, or Sketch.
9. **Confirmation is irreversible** — except via explicit governance rollback with documented justification.
10. **Visual-first, technology-agnostic** — declared in canonical form; transformable to any target framework.
11. **Explicit intent** — regions, elements, geometry, hierarchy, relationships all declared explicitly; no implicit intent.
12. **No rendered output** — Stencil produces authored declarations only; transformation to runtime form is exclusive to downstream stages.
13. **No bypass** — cannot skip VSIL-App to produce Codex directly. Cannot skip confirmation gateway. Cannot derive visual truth independently without Blueprint mediation.
14. **VTPS stage 3 of 6** — fixed position; may not skip or bypass any pipeline stage.
15. **8px grid snap** — all resize/move operations snap to 8px grid (5px threshold).
16. **Stable structural tree** — structural changes must be explicit and diffable.
17. **Layout determinism + reproducibility** — required for visual diffing and snapshot comparison.
18. **Interaction mapping preserved** — interactive elements explicitly mapped to Codex interactions.

---

## 5. Stencil lifecycle

Synthesized from the SSS, overlay, and governance docs:

```
   [Idea] → [Idea Net] → [Pact] → [Blueprint (validated+confirmed)]
                                          │
                                          ▼
                                ┌─────────────────────┐
                                │  AUTHOR STENCIL     │  ← creative surface,
                                │  (exploratory)      │    branchable, mutable
                                └──────────┬──────────┘
                                           ▼
                                ┌─────────────────────┐
                                │  CONFIRM            │  ← validation gateway
                                │  (Blueprint match,  │
                                │   determinism,      │
                                │   @pact: tags,      │
                                │   no contradictions)│
                                └──────────┬──────────┘
                                           ▼
                              CONFIRMED CANONICAL STENCIL
                              (MAINLINE-integrated, versioned)
                                           │
                                           ▼
                            [VSIL-App auto-derives] → [Codex] → [Sketch]
```

**Branch lifecycle**:

```
CONFIRMED STENCIL  ──fork──▶  BRANCH STENCIL (exploratory)
                                  │
                                  ├─ merge ──▶ re-validate ──▶ re-confirm ──▶ NEW CANONICAL
                                  └─ abandon ──▶ marked abandoned (kept in lineage record)
```

**Re-trigger on Pact change**: Pact modify → Blueprint surface update → Stencil re-author → confirmation validation → VSIL re-interpret → Codex update → Sketch refresh. Must propagate in this order to maintain lineage integrity.

---

## 6. The Living Stencil project (current real work, post-theory)

The SSS is the theory. The **Living Stencil** is the operator's current practical project to build the canonical visual layout for FreshVibe Studio itself. Per `pact/pipeline/codex/codex-v0024.5.md` and `pact/decisions/2026-06-16-stencil-baseline-preferences.md`:

> Operator quote (2026-06-16): *"I think you need to build the codex. From the codex we'd build a stencil. Because it's the stencil that I'll see and be able to manipulate. I will know if I don't like something. And then we can set the codex number 25 as the proper basis. Based on all my refinement. that goes into the stencil. stencil refinements can also inform pact just as its meant to be visual first."*

**The Living Stencil order** (per codex-v0024.5):
1. Code bump `v0024.0 → v0024.5` (compilation, in progress).
2. Build the **Living Stencil** (visual artefact, mock data).
3. Operator refines the stencil visually.
4. Stencil refinements inform the codex.
5. Build **codex v0025.0** (standalone, current) based on the approved stencil.
6. Rebuild the real implementation against the approved stencil + codex v0025.0.

**Operator's baseline preferences** (ADR `pact/decisions/2026-06-16-stencil-baseline-preferences.md`, APPROVED 2026-06-16 13:43 UTC by Mavis on operator's behalf):

| Element | Replit sketch (NOT preferred) | Operator prefers (Stencil uses) |
|---|---|---|
| Background | Deep navy `#03050a` | Light mode default `#fafbfc` |
| Accent | Blue `#5b8cff` | Cockpit purple `#6d28d9` light / `#7c3aed` dark |
| Topnav right side | Layout icons only | 3 FreshCards aspects (theme toggle, skin picker, user menu) |
| Logo | Gradient (orange/pink/blue/teal) | Current purple `F` logo |
| Title | "FreshVibe Studio" | "FreshVibe Studio" |

GZ-1 demotion tag: `GZ-1-DECISION-STENCIL-BASELINE-PREFERENCES-2026-06-16`. Drift-check status: PENDING (stencil not yet built as of 2026-06-16).

**Conflict that this triggered** (per `pact/decisions/2026-06-19-doctrine-merge-logic-check.md`):
- The 2026-06-16 decision explicitly says: *"Use the CURRENT colour scheme, NOT the replit sketch's dark scheme. The operator's exact words: 'I 100% prefer the colour scheme we have now to the replit sketch'."*
- But `pact/decisions/2026-06-18-vanilla-chrome-swap.md` (merged shortly after) **adopted the vanilla chrome, which IS the replit sketch's dark scheme**. The new StudioContext initial state conflicts with the stencil baseline preference.
- The merge was clean (no git conflicts) because the doctrine branch was on `pact/` and the chrome swap was on `studio/` — orthogonal file trees. But logically the two decisions contradict each other. Status: still open.

The Living Stencil baseline uses:
- Light mode by default with cockpit purple accent.
- Topbar containing 3 FreshCards aspects: theme toggle, skin picker (slate/dawn/dusk/forest), user menu.
- Cross-refs: `pact/blueprint/ui/top-bar.md`, `pact/blueprint/panels/vibe-panel.md`, `pact/blueprint/panels/peek-panel.md`, `pact/legacy/archived/living-sketch-baseline-2026-06-08/`.

The Replit sketch recipe (`pact/replit-sketch-rv0001-recipe/`) explicitly notes: *"Light theme (per `pact/decisions/2026-06-16-stencil-baseline-preferences.md`) — the replit sketch is dark; we apply light when implementing."*

---

## 7. Known contradictions / open gaps in the repo

Documented in `pact/audit/SECOND-GAP-ANALYSIS.md` (HIGH and CRITICAL severity):

### 7.1 §3.1 Stencil Scope Conflict (HIGH)
- `platform/stencil/stencil.md`: Stencil is "derived from Codex".
- `platform/vibecoder/vibecoder.md`: Stencil is a source FOR Codex through VSIL-App.
- `platform/architecture.md`: `Stencil → Codex → Sketch`.
- **Open question**: which direction is authoritative for Stencil ↔ Codex?

### 7.2 §3.3 VSIL Role in Visual Universe (MEDIUM)
- `vsil.md` `vsil.truth_direction.001`: "VSIL does not sit between Stencil and Codex and does not influence the truth direction."
- `platform.vibecoder.visual-universe.definition.001`: Visual Universe is `Stencil → VSIL-App → Codex → Sketch`.
- **Open question**: how does VSIL-App sit in the pipeline but "not influence truth direction"?

### 7.3 §4.1 Visual Universe Flow Contradiction (CRITICAL)
- `platform/architecture.md`: `Stencil → Codex → Sketch` (4 stages, no VSIL).
- `platform/vibecoder/vibecoder.md`: `Stencil → VSIL-App → Codex → Sketch` (5 stages).
- **Authoritative flow** (in current canonical specs): the 5-stage form. The 4-stage form is legacy architecture from `platform/_core/` that has not been fully reconciled.

### 7.4 §4.2 VSIL Truth Direction Contradiction (HIGH)
- `vsil.md` simultaneously says "VSIL does not influence truth direction" AND "Codex-level VSIL participates in the Stencil → Codex → Sketch truth direction". What does "participate" mean here?

### 7.5 §4.3 Stencil Derivation Contradiction (MEDIUM)
- `stencil.md` (platform): Stencil is derived from Codex.
- `vibecoder.md`: Stencil is the canonical visual layout that VSIL-App derives from.
- **Resolution direction** (per the SSS in `pipeline/stencil/stencil.md`): the SSS is the newer, constitutional role definition. The `platform/stencil/stencil.md` "derived from Codex" line is the older/contradictory formulation that hasn't been fully purged. The pipeline flow `Blueprint → Stencil → VSIL-App → Codex → Sketch` is authoritative.

### 7.6 §1.12 Stencil Collapse Rule (Sidestep 6.1, deferred)
Per `pact/plans/sidestep-6.1/PLAN-SIDESTEP-6.1.md`:
> "STENCIL COLLAPSE RULE — Conceptually new. Stencil collapses into App-Codex + App-Recipe on approval; Stencil diffs do not carry forward. The Stencil's lifecycle is currently governed by the Builder v1.1 contract §5 (Studio Emulation Mode). Adding a 'collapse rule' without amending the Builder contract would create a partial declaration. Must be introduced via a Builder v1.x addendum or a new codex amendment."

Meaning: when a Stencil is *approved* (not just confirmed in the pipeline — *approved as final*), it collapses into runtime artefacts (App-Codex + App-Recipe) and the Stencil's intermediate diffs don't carry forward. Only the final approved Stencil becomes runtime truth. This rule is **deferred** — not yet in the constitution.

---

## 8. Legacy interpretation of "Stencil" (FreshVibe Way v5.1)

> **CRITICAL**: do not confuse this with the current meaning.

Per `pact/legacy/freshvibe-way/v5.1/11-import-mode.md` §11.2, `12-bootstrap-mode.md`, `13-compatibility-mode.md`, and `V5-MIGRATION.md`:

In v5.1, **Stencil** was:
- "A preliminary, **auto-generated snapshot of the foreign project's structure** (DOM tree, layout, content, styles). Not authored — derived."
- Produced during **Import Mode** when a UI Module was introduced into a foreign (non-FreshVibe) project.
- Stored at `pact/imports/<import-id>/stencil.json` with surface candidates, content candidates, layout candidates, style candidates, behaviour candidates — **each with a `provenance: 'REAL'` or `provenance: 'MOCK'` flag**.
- **REAL** = content extracted from the foreign project (must never be overwritten). **MOCK** = generated by mock engines (overridden by REAL when both present).
- In **Bootstrap Mode** (v5.1 §12): for a zero-structure project (no Sketch, no Stencil, no anchors, no metadata), the UI Module must produce a "Bootstrap Stencil" (all MOCK initially) and then a "Bootstrap Sketch" from it.
- The 8 Import Mode rules: Stencil generation, REAL data extraction, Sketch creation from foreign source, mock engine output, AI-facing Inspector surfaces, anchor system, lineage + metadata, regeneration safety.

This v5.1 Stencil was **derived from observation** (HTML scraping, file reading, DOM inspection, content extraction) and is **machine-authored baseline**, not human-authored design. The Sketch was then authored from the Stencil + REAL data, becoming the canonical ancestor for future refactors.

**Status**: archived under `pact/legacy/freshvibe-way/v5.1/`. The renaming refactor (`pact/plans/renaming-refactor-v2026.md`) lists "Stencil" as **"Unchanged"** in the rename pass — meaning the name Stencil was preserved but the meaning shifted entirely from "imported project snapshot" to "authored declarative UI structure". This is a **semantic collision** that the repo has not fully disambiguated, but context (current codex + SSS + decision records) clearly indicates the v5.1 meaning is legacy.

---

## 9. All files in `pact/` that reference Stencil (76 files)

### Canonical (2 files)
- `pact/pipeline/stencil/stencil.md` — **Stencil System Specification (SSS)**, the constitutional role definition
- `pact/platform/stencil/stencil.md` — Platform implementation contract

### Overlay / spec source (3 files)
- `pact/pipeline/codex/codex-overlays/vibecoder/overlay-stencil-authoring.md` — VibeCoder authoring tool overlay (the editor spec)
- `pact/pipeline/codex/ui-codex/Codex-v0018.2.md` — earlier codex defining VibeCoder Stencil as "canonical visual layout representation of an app UI in VibeCoder Vibe Mode"
- `pact/pipeline/codex/ui-codex/Codex-v0018.4.md` — adds Section 29 (VibeCoder Stencil Authoring) which was extracted into the overlay above

### Related canonical fragments in other pipeline files
- `pact/pipeline/architecture-map.md` — pipeline structure + `Pact → Blueprint → Stencil → VSIL → Codex → Sketch` diagram
- `pact/pipeline/blueprint/blueprint.md` — Stencil derives from Blueprint, must validate
- `pact/pipeline/codex/codex-v0022.0.md` — codex referencing `stencil/` family (5 fragments)
- `pact/pipeline/codex/codex-v0024.5.md` — current compilation; describes the Living Stencil build order
- `pact/pipeline/sketch/sketch.md` — Sketch has no direct connection to Stencil; Stencil → VSIL-App → Codex → Sketch
- `pact/pipeline/trace-atlas/trace-atlas.md` — Trace Atlas observes Stencil events; lists `overlay-stencil-authoring.md`
- `pact/pipeline/vsil/vsil.md` — VSIL-App sits between Stencil and Codex in pipeline
- `pact/pipeline/vsil/vsil-app.md` — VSIL-App derives from confirmed Stencil; auto-derivation
- `pact/pipeline/codex/codex-overlays/alignment/ALIGNMENT-SUMMARY-ENGINE.md`
- `pact/pipeline/codex/codex-overlays/alignment/MISMATCH-TABLE-ENGINE-ALIGNMENT.md` — flags Stencil authoring as MISSING, refers to overlay

### Behaviour files (4 files mention Stencil in fragment text)
- `pact/behaviour/engines.behaviour.md` — "engine ... transforms Codex and Stencil into concrete runtime behavior"
- `pact/behaviour/execution.behaviour.md` — "Transitions from Stencil → Codex → Sketch must be explicit, atomic, and reversible"
- `pact/behaviour/sketch.behaviour.md` — "Sketch is ... derived from Stencil"; "given the same Stencil ... Sketch must be visually deterministic"; Sketch has no direct connection to Stencil
- `pact/behaviour/vsil.behaviour.md` — "VSIL does not sit between Stencil and Codex"; "Codex-level VSIL participates in the Stencil → Codex → Sketch truth direction"

### Governance (4 files)
- `pact/governance/governance.md` — governance validates Stencil confirmation workflows, can rule on Stencil confirmation exceptions, conducts cascading impact assessment including Stencil fragments
- `pact/governance/dna/dna-tagging.md` — DNA tag format example uses `stencil.definition.what.is.stencil.001:1-5`; "DNA tags must not ... bypass Stencil and VSIL-App"
- `pact/governance/dna/fragment-registry.md` — registers `vibecoder.stencil.authoring.001` as VIBECODER active
- `pact/governance/vibecoder-workspace.governance.md` — VibeCoder Stencil editor / Preview / Inspector surfaces; sync check requirements

### Platform contract files
- `pact/platform/_core/architecture.md` — `Stencil → Codex → Sketch` (4-stage legacy)
- `pact/platform/_core/determinism.md` — "every transformation from Codex to Stencil to Sketch to Engine execution must be reproducible, traceable, and free from hidden state"
- `pact/platform/_core/global.md` — "Stencil → Codex → Sketch" (4-stage legacy)
- `pact/platform/_core/platform-architecture.md` — diagram `STENCIL ────► CODEX ────► SKETCH` (4-stage legacy)
- `pact/platform/_core/platform-fragments.md` — 167 fragments incl. Stencil references
- `pact/platform/builder/contract-v1.1.md` — Builder is the only subsystem authorized to apply FVW to a Stencil and emit VSIL; byte-identical VSIL for same Stencil; `stencil_id`, `source_fingerprint`, `vsil_fingerprint`; Studio Emulation Mode scaffolding rule
- `pact/platform/builder/contract.md` — earlier Builder contract with same Stencil input/output shape
- `pact/platform/engines/engines.md`
- `pact/platform/execution/execution.md`
- `pact/platform/format-standards/format-standards.md`
- `pact/platform/gallery/gallery-contract.md`
- `pact/platform/safety/safety.md`
- `pact/platform/sketch/sketch.md` (companion to pipeline sketch)
- `pact/platform/studio/assembly-engine.md`
- `pact/platform/studio/codex-integration.md`
- `pact/platform/vsil/vsil.md` (companion to pipeline vsil)

### Decisions (2 files)
- `pact/decisions/2026-06-16-stencil-baseline-preferences.md` — **APPROVED operator decision** on Living Stencil baseline (light mode, purple accent, 3 FreshCards aspects in topnav). GZ-1 demotion tag `GZ-1-DECISION-STENCIL-BASELINE-PREFERENCES-2026-06-16`. Codex bump `v0024.0 → v0024.5`.
- `pact/decisions/2026-06-19-doctrine-merge-logic-check.md` — documents the conflict with `2026-06-18-vanilla-chrome-swap.md` (merged dark scheme contradicts 2026-06-16 light scheme preference)

### Plans (4 files)
- `pact/plans/STAGE1.md` — Stage 1 = "Stencil → Sketch → App pipeline: Skeleton + decoration + future-fill"
- `pact/plans/renaming-refactor-v2026.md` — Stencil name preserved in renaming refactor (no rename)
- `pact/plans/sidestep-6.1/PLAN-SIDESTEP-6.1.md` — STENCIL COLLAPSE RULE (§1.12) deferred
- `pact/plans/wipe-and-promote-2026-06-08/codex-v0022.0/PROMOTION-PLAN.md` — `stencil/` listed as Family L subdir

### Drafts (2 files)
- `pact/drafts/stage1-stage2/stage3-file1-vsil-cinema-cockpit.md` — Stage 3 consolidation, references `pact/platform/stencil/stencil.md` as "declarative, technology-agnostic UI structure derived from Codex"
- `pact/drafts/stage1-stage2/stage3-file2-ui-activespec-engine.md` — UI+ActiveSpec+Engine consolidation, cross-references Stencil

### Audits (11 files mention Stencil)
- `pact/audit/CENTRESTAGE-INGESTION-CANDIDATES-2026-06-10.md`
- `pact/audit/CENTRESTAGE-INGESTION-PLAN-2026-06-10.md` — references files under `pact/pipeline/stencil/`
- `pact/audit/FVS-DEEP-AUDIT-2026-06-15.md` — structure tree `pipeline/stencil/stencil.md`
- `pact/audit/FVS-PROJECT-STRUCTURE-2026-06-15.html` (HTML audit)
- `pact/audit/PACT-AUDIT-PASS-A-2026-06-06.md`
- `pact/audit/PACT-AUDIT-PASS-C-2026-06-06.md`
- `pact/audit/SECOND-GAP-ANALYSIS.md` — **the document with the 3 Stencil conflicts (§3.1, §3.3, §4.1, §4.2, §4.3)**
- `pact/audit/SIDE-STEP-6-1-DEFERRED.md` — Stencil Collapse Rule deferred
- `pact/audit/STEP-3-BUILDER-CONTRACT-EXTRACTION-2026-06-10.md` — Builder input "Approved Stencil", output `stencil_id`, `source_fingerprint`
- `pact/audit/STEP-6-MULTI-SUBSYSTEM-EXTRACTION-2026-06-10.md` — Trace Atlas lineage: "Pact → Blueprint → Stencil → VSIL-App → Codex → Sketch"
- `pact/audit/UNIVERSAL-AUDIT.md` — `vsil.system.separation.truth.direction.001` references Stencil
- `pact/audit/WHAT-IS-BUILDER-V1.1.md` — "when you (the operator) say 'build me an app from this Stencil,' the Builder takes the Stencil, applies the FreshVibe Way doctrine, and produces the actual code (VSIL files, App Codex, Module Codex, etc.)"
- `pact/audit/v1.1-ingestion/CANDIDATE-FRAGMENTS-2026-06-10.md` — Stencil source / confirmation / drift detection fragments

### Legacy (9 files)
- `pact/legacy/archived/behaviour-misclassified-2026-05-21/engines.md`
- `pact/legacy/freshvibe-way/v5.1/11-import-mode.md` — **the v5.1 Stencil-as-imported-snapshot definition**
- `pact/legacy/freshvibe-way/v5.1/12-bootstrap-mode.md` — Bootstrap Stencil (all MOCK)
- `pact/legacy/freshvibe-way/v5.1/13-compatibility-mode.md` — Stencil anchors in compatibility mode
- `pact/legacy/freshvibe-way/v5.1/README.md` — Stencil referenced in §11/§12 summary
- `pact/legacy/freshvibe-way/v5.1/V5-MIGRATION.md` — Stencil as preliminary derived snapshot, `pact/imports/<id>/stencil.json`
- `pact/legacy/migration/archived-2026-06-05/blueprint-fragments-vibecoded/README.md` — "Template Engine: Stencil/template rendering"
- `pact/legacy/platform/codex/codex.md`
- `pact/legacy/platform/pipeline/visual-truth-pipeline.md`
- `pact/legacy/platform/runtime/runtime-safety.md`
- `pact/legacy/platform/trace/trace-atlas.md`
- `pact/legacy/platform/vibecoder/vibecoder.md` — Stencil as canonical visual layout for apps (vibecoder-specific)

### Other
- `pact/pact.json` — fragment registry (447 total fragments, 403 unique)
- `pact/snapshots/truth-snapshots/truth-snapshot-v0.1-2026-06-02.md` — "Stencil: `pact/pipeline/stencil/stencil.md` + `pact/platform/stencil/stencil.md` (2 files)"
- `pact/replit-sketch-rv0001-recipe/README.md` — light theme per 2026-06-16 decision
- `pact/replit-sketch-rv0001-recipe/recipe.md` — references the 2026-06-16 decision
- `pact/replit-sketch-rv0001-recipe/rules.md` — references the 2026-06-16 decision

### Top-level reports (outside `pact/`, but in the same repo)
- `./Phase-C-6-UI-Module-3-Mode-Update-Report.md`
- `./Phase-C-7-UI-Module-2nd-Update-Report.md`
- `./Phase-C-8-FreshVibe-Way-v5.1-PACT-Install-Report.md` (v5.1 PACT install)
- `./Phase-C-11-Unified-Builder-Contract-Report.md` (Builder)
- `./Codex-Drift-Audit-Report.md`
- `./Track-B-1-Platform-Alignment-Audit.md`
- `./Track-B-3-Post-Fix-Re-Audit.md`

---

## 10. Quick-reference cheat sheet

- **What is Stencil?** Authored, declarative, technology-agnostic source of truth for visual structure and layout, in the Visual Truth Pipeline.
- **Where in the pipeline?** Stage 3 of 6: `Pact → Blueprint → Stencil → VSIL-App → Codex → Sketch`.
- **What does Stencil receive?** Structural specs from Blueprint only.
- **What does Stencil produce?** Authored declarations (regions, elements, geometry, hierarchy) consumed by VSIL-App.
- **What is the confirmation gateway?** The single, irreversible handoff from confirmed Stencil to VSIL-App. Bypass = constitutional violation.
- **What tags must every element carry?** `@pact:`, `@deps:`, `@lineage:`.
- **What are the cardinal invariants?** Determinism, region correspondence with Blueprint, no Blueprint contradiction, Pact reference, reversibility, forward-only truth.
- **Who builds VSIL from Stencil?** The Builder subsystem (per `platform/builder/contract-v1.1.md`). Only authorized subsystem to apply FVW to a Stencil. Byte-identical output for same input.
- **What is the current operator project?** The Living Stencil — visual artefact built from codex v0024.5, then operator refines visually, refinements inform codex v0025.0, then real implementation rebuilds against approved stencil + codex v0025.0.
- **What is the v5.1 "Stencil"?** A different, now-archived concept: an auto-generated, machine-derived snapshot of a foreign project's DOM used during Import Mode. See §8.
- **What is the biggest open contradiction?** The `platform/stencil/stencil.md` fragment "Stencil is derived from Codex" vs the SSS "Stencil is the origin". The pipeline form (`Stencil → VSIL-App → Codex → Sketch`) is authoritative; the platform file is stale. Tracked in `audit/SECOND-GAP-ANALYSIS.md` §3.1 / §4.1 / §4.3.
- **What is the Stencil Collapse Rule (§1.12 in sidestep 6.1)?** Deferred. When a Stencil is *approved* (final), it collapses into App-Codex + App-Recipe; intermediate Stencil diffs don't carry forward. Not yet in the constitution.

---

*End of dossier. All content sourced from `avidtech6/freshvibestudio` (private repo) via `GITHUB_PAT_FG_1`. Total files reviewed: 76 under `pact/` + 7 top-level reports.*