TidyFactor · alwkala · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.tidyfactor b/.tidyfactor
@@ -2,10 +2,10 @@
   "ecosystem": "tidyfactor",
   "track": "design",
   "name": "tidyfactor-design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "npmPackage": "@alwkala/tidyfactor-design",
   "github": "https://github.com/TidyFactor/Design",
-  "skillFile": "../tidyfactor-design-v1.7.0.skill",
+  "skillFile": "../tidyfactor-design-v1.8.0.skill",
   "category": "design-system",
   "type": "interactive-prototyping",
   "outputs": [

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to the **[@tidyfactor/design](https://www.npmjs.com/package/@tidyfactor/design)** package will be documented in this file.
 
+## [1.8.0] - 2026-09-02
+
+### ⚡ Added — Declarative Decision Gates, Staleness Tracking & Manifest v1.1.0
+- **Declarative `decision_gates[]` Contract (`manifest.json`)**: Formally declared Required Decisions (`audience_mode`, `surface_type`, `tone_school`), priority ranks, discovery sources, and conservative fallbacks conforming to `skill-manifest.decision-gates.schema.json`.
+- **Mechanical Context Delta Resolution (`workflows/brief.md`)**: Replaced heuristic agent arbitration with a deterministic set-difference algorithm: $\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$.
+- **Local Staleness Tracking (`track_staleness: true`)**: Implemented local hash checking on `brand.json` within `.tidyfactor/design-brief.snapshot.json`—re-opening modified parameters into `Unknowns` without network or MCP round-trips.
+- **SSOT Single-Direction Push Architecture**: Enforced local snapshot as the sole immutable source of truth, with Brain MCP persistence acting strictly as an outbound replica via `--sync-brain`.
+- **Tooling Consolidation**: Unified media optimization under `scripts/optimize_images.py` across `manifest.json`, `assets.md`, and documentation.
+
+---
+
 ## [1.7.0] - 2026-09-02
 
 ### 🧠 Added — Sovereign Brain MCP Integration & Deterministic Fail-Open Protocol

diff --git a/brand.json b/brand.json
@@ -1,12 +1,12 @@
 {
   "name": "TidyFactor Design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "schemaVersion": "brand-core-v2",
   "meta": {
     "product": "TidyFactor Design System",
     "tagline": "Code-Native Interactive Prototyping Engine",
     "description": "A zero-bundler, framework-free design system and UI prototyping engine with pluggable CSS foundations and full Arabic/RTL support.",
-    "version": "1.7.0",
+    "version": "1.8.0",
     "lastUpdated": "2026-09-02"
   },
   "identity": {

diff --git a/dist/tidyfactor-design.skill b/dist/tidyfactor-design.skill
diff --git a/dist/tidyfactor-design/.tidyfactor b/dist/tidyfactor-design/.tidyfactor
@@ -2,10 +2,10 @@
   "ecosystem": "tidyfactor",
   "track": "design",
   "name": "tidyfactor-design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "npmPackage": "@alwkala/tidyfactor-design",
   "github": "https://github.com/TidyFactor/Design",
-  "skillFile": "../tidyfactor-design-v1.7.0.skill",
+  "skillFile": "../tidyfactor-design-v1.8.0.skill",
   "category": "design-system",
   "type": "interactive-prototyping",
   "outputs": [

diff --git a/dist/tidyfactor-design/CHANGELOG.md b/dist/tidyfactor-design/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to the **[@tidyfactor/design](https://www.npmjs.com/package/@tidyfactor/design)** package will be documented in this file.
 
+## [1.8.0] - 2026-09-02
+
+### ⚡ Added — Declarative Decision Gates, Staleness Tracking & Manifest v1.1.0
+- **Declarative `decision_gates[]` Contract (`manifest.json`)**: Formally declared Required Decisions (`audience_mode`, `surface_type`, `tone_school`), priority ranks, discovery sources, and conservative fallbacks conforming to `skill-manifest.decision-gates.schema.json`.
+- **Mechanical Context Delta Resolution (`workflows/brief.md`)**: Replaced heuristic agent arbitration with a deterministic set-difference algorithm: $\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$.
+- **Local Staleness Tracking (`track_staleness: true`)**: Implemented local hash checking on `brand.json` within `.tidyfactor/design-brief.snapshot.json`—re-opening modified parameters into `Unknowns` without network or MCP round-trips.
+- **SSOT Single-Direction Push Architecture**: Enforced local snapshot as the sole immutable source of truth, with Brain MCP persistence acting strictly as an outbound replica via `--sync-brain`.
+- **Tooling Consolidation**: Unified media optimization under `scripts/optimize_images.py` across `manifest.json`, `assets.md`, and documentation.
+
+---
+
 ## [1.7.0] - 2026-09-02
 
 ### 🧠 Added — Sovereign Brain MCP Integration & Deterministic Fail-Open Protocol

diff --git a/dist/tidyfactor-design/brand.json b/dist/tidyfactor-design/brand.json
@@ -1,12 +1,12 @@
 {
   "name": "TidyFactor Design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "schemaVersion": "brand-core-v2",
   "meta": {
     "product": "TidyFactor Design System",
     "tagline": "Code-Native Interactive Prototyping Engine",
     "description": "A zero-bundler, framework-free design system and UI prototyping engine with pluggable CSS foundations and full Arabic/RTL support.",
-    "version": "1.7.0",
+    "version": "1.8.0",
     "lastUpdated": "2026-09-02"
   },
   "identity": {

diff --git a/dist/tidyfactor-design/package.json b/dist/tidyfactor-design/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "TidyFactor Design track — code-native UI design lifecycle engine (Figma alternative) with Contextual Decision Layer (CDL)",
   "main": "SKILL.md",
   "bin": {

diff --git a/dist/tidyfactor-design/references/workflows/brief.md b/dist/tidyfactor-design/references/workflows/brief.md
@@ -1,36 +1,56 @@
 # Workflow: brief
 
-Discovers and records core design system baselines (Foundation, School, Typography, Archetype) using the Contextual Decision Layer (CDL).
+Discovers and records core design system baselines (Audience Mode, Surface Type, Tone School) using declarative Context Delta Resolution.
 
 ---
 
-## Steps
+## 📋 Step 0: Mechanical Context Delta Resolution
 
-1. **Check Existing State (Local Auto-Sensing First)**:
-   - Scan workspace for `BRAND-GUIDELINES.md`, `brand.json`, and `.tidyfactor/design-brief.md`.
-   - If present, immediately extract tokens, typography, and palette baselines without prompting.
+Evaluate the declared decision contract in `manifest.json["decision_gates"]["brief"]`:
 
-2. **Check Active MCP Acceleration (Fail-Open Fallback)**:
-   - If local files do not exist AND `search_knowledge_base` is available in active agent tools:
-     Query `search_knowledge_base(query="design tokens", scope="project")` for existing project baselines.
-   - If MCP is unavailable, empty, or returns error: Silently proceed to Step 3 with 0ms delay.
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
 
-3. **Conduct Structured Discovery (Max 3 Questions)**:
-   - If parameters remain unresolved, present at most 3 concise multiple-choice options:
-     1. **CSS Foundation (D1)**: (A) Native CSS (Default), (B) Tailwind CSS, (C) daisyUI, (D) Pico CSS.
-     2. **Design School (D2)**: (A) Swiss Modern, (B) Neo-Brutalism, (C) Editorial Luxury, (D) Egyptian / Regional Heritage.
-     3. **Layout Archetype (D4)**: (A) Split Hero Canvas, (B) Narrative Editorial, (C) Command Dashboard.
+1. **Local Discovery & Staleness Check**:
+   - Check `.tidyfactor/design-brief.snapshot.json` and `brand.json`.
+   - If `brand.json` has changed since the snapshot was saved (`track_staleness: true`), invalidate the cached value and mark `surface_type` / `tone_school` as `Unknown`.
+2. **Optional Brain MCP Lookup (Fail-Open)**:
+   - If decisions remain Unknown and `search_knowledge_base` is active, query `search_knowledge_base(query="design context", scope="project")`.
+   - If absent or empty, proceed with 0ms silent bypass.
+3. **Delta Evaluation**:
+   - If $\text{Unknowns} = \emptyset$: Skip all questioning immediately and emit confirmed baseline.
+   - If $\text{Unknowns} \neq \emptyset$: Proceed to Step 1 for **only the missing keys**.
 
-4. **Record Decisions**:
-   - Persist confirmed parameters into `.tidyfactor/design-brief.md`.
+---
+
+## 💬 Step 1: Surgical Micro-Discovery (Only for Unknown Decisions)
+
+> **Anti-Bot Constraint**: Never greet the user or ask for facts already resolved on disk. Present at most `max_interactive_questions` (3) sorted by priority:
+
+- **Audience Mode (Priority 1)**: `(A) act` (Default), `(B) inspire`, `(C) evaluate`, `(D) learn`.
+- **Surface Type (Priority 2)**: `(A) landing` (Default), `(B) dashboard`, `(C) product`, `(D) editorial`, `(E) interface`, `(F) minimal`.
+- **Tone School (Priority 3)**: `(A) minimal` (Default), `(B) neo-brutalism`, `(C) luxury`, `(D) swiss`, `(E) bento`, `(F) heritage-nilotic`, `(G) heritage-kufic`.
+
+---
+
+## 💾 Step 2: SSOT Local Persistence & Outbound Push
+
+1. **Write Local SSOT**: Persist resolved choices + source file hashes to `.tidyfactor/design-brief.snapshot.json` and `.tidyfactor/design-brief.md`.
+2. **Outbound Push to Brain (`--sync-brain`)**:
+   - If and ONLY IF invoked with `--sync-brain`, push the resolved `design_context` KI via `extract_knowledge_item`.
+   - The local snapshot remains the immutable source of truth.
+
+---
+
+## 🎯 Step 3: Summary & Actionable Handoff
 
-5. **Report Summary**:
-   - Present a concise baseline summary and suggest next action (`/init`, `/tokens`, `/components`).
+Display a concise 4-line baseline summary and suggest next action (`/tokens`, `/layout`, `/components`).
 
 ---
 
 ## Validation checklist
 
-- [ ] `.tidyfactor/design-brief.md` exists and contains confirmed values for D1–D5.
-- [ ] No more than 3 questions were asked in a single round.
-- [ ] Design baseline conforms to `references/memory/quality-bar.md`.
+- [ ] Evaluated Context Delta Resolution against `manifest.json["decision_gates"]`.
+- [ ] Only truly Unknown decisions were surfaced to the user.
+- [ ] `.tidyfactor/design-brief.snapshot.json` and `.tidyfactor/design-brief.md` written as local SSOT.
+- [ ] If `--sync-brain` was passed, outbound push was executed without blocking local output.
+- [ ] Baseline conforms to `references/memory/quality-bar.md`.
diff --git a/dist/tidyfactor-design/tools/build-skill.js b/dist/tidyfactor-design/tools/build-skill.js
@@ -68,6 +68,7 @@ function build() {
   log('staging single-source-of-truth files from repo root...');
   const whitelist = [
     'SKILL.md',
+    'manifest.json',
     'references',
     'memory',
     'templates',

diff --git a/manifest.json b/manifest.json
@@ -1,5 +1,5 @@
 {
-  "manifest_schema_version": "1.0.0",
+  "manifest_schema_version": "1.1.0",
   "skill_id": "tidyfactor-design",
   "skill_root_anchor": "self",
   "tools": [
@@ -40,7 +40,7 @@
     {
       "name": "optimize_media",
       "description": "Compresses images, removes backgrounds, and generates WebP variants.",
-      "entrypoint": { "runtime": "python3", "script": "scripts/optimize_assets.py" },
+      "entrypoint": { "runtime": "python3", "script": "scripts/optimize_images.py" },
       "invocation": {
         "cli_pattern": "{runtime} \"{skill_root}/{script}\" --target \"{target_path}\" {flags}",
         "args": [
@@ -55,5 +55,78 @@
       },
       "invoked_by_commands": ["assets"]
     }
+  ],
+  "decision_gates": [
+    {
+      "command": "brief",
+      "description": "Design Context Gate — determines audience mode, surface type, and design school before scaffolding.",
+      "max_interactive_questions": 3,
+      "decisions": [
+        {
+          "key": "audience_mode",
+          "description": "What should this surface primarily do for the visitor?",
+          "type": "enum",
+          "options": ["inspire", "evaluate", "act", "learn"],
+          "default": "act",
+          "priority": 1,
+          "discovery": [
+            { "source": "local_file", "path": ".tidyfactor/design-brief.snapshot.json", "field": "audience_mode" },
+            { "source": "brain_ki", "ki_type": "design_context", "field": "audience_mode" }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/design-brief.snapshot.json", "field": "audience_mode" },
+            "brain_ki": {
+              "ki_type": "design_context",
+              "field": "audience_mode",
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "surface_type",
+          "description": "What kind of layout archetype is this surface?",
+          "type": "enum",
+          "options": ["landing", "dashboard", "product", "editorial", "interface", "minimal", "spatial", "auto"],
+          "default": "landing",
+          "priority": 2,
+          "discovery": [
+            { "source": "local_file", "path": "brand.json", "field": "surfaceType", "track_staleness": true },
+            { "source": "workspace_scan", "path": "pages/", "field": "dominant_page_type" },
+            { "source": "brain_ki", "ki_type": "design_context", "field": "surface_type" }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/design-brief.snapshot.json", "field": "surface_type" },
+            "brain_ki": {
+              "ki_type": "design_context",
+              "field": "surface_type",
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "tone_school",
+          "description": "What aesthetic design school should visual styling follow?",
+          "type": "enum",
+          "options": ["minimal", "neo-brutalism", "luxury", "swiss", "bento", "heritage-nilotic", "heritage-kufic", "corporate"],
+          "default": "minimal",
+          "priority": 3,
+          "discovery": [
+            { "source": "local_file", "path": "brand.json", "field": "voice", "track_staleness": true },
+            { "source": "brain_ki", "ki_type": "design_context", "field": "tone_school" }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/design-brief.snapshot.json", "field": "tone_school" },
+            "brain_ki": {
+              "ki_type": "design_context",
+              "field": "tone_school",
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        }
+      ]
+    }
   ]
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/design",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "TidyFactor Design track — code-native UI design lifecycle engine (Figma alternative) with Contextual Decision Layer (CDL)",
   "main": "SKILL.md",
   "bin": {

diff --git a/references/workflows/brief.md b/references/workflows/brief.md
@@ -1,36 +1,56 @@
 # Workflow: brief
 
-Discovers and records core design system baselines (Foundation, School, Typography, Archetype) using the Contextual Decision Layer (CDL).
+Discovers and records core design system baselines (Audience Mode, Surface Type, Tone School) using declarative Context Delta Resolution.
 
 ---
 
-## Steps
+## 📋 Step 0: Mechanical Context Delta Resolution
 
-1. **Check Existing State (Local Auto-Sensing First)**:
-   - Scan workspace for `BRAND-GUIDELINES.md`, `brand.json`, and `.tidyfactor/design-brief.md`.
-   - If present, immediately extract tokens, typography, and palette baselines without prompting.
+Evaluate the declared decision contract in `manifest.json["decision_gates"]["brief"]`:
 
-2. **Check Active MCP Acceleration (Fail-Open Fallback)**:
-   - If local files do not exist AND `search_knowledge_base` is available in active agent tools:
-     Query `search_knowledge_base(query="design tokens", scope="project")` for existing project baselines.
-   - If MCP is unavailable, empty, or returns error: Silently proceed to Step 3 with 0ms delay.
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
 
-3. **Conduct Structured Discovery (Max 3 Questions)**:
-   - If parameters remain unresolved, present at most 3 concise multiple-choice options:
-     1. **CSS Foundation (D1)**: (A) Native CSS (Default), (B) Tailwind CSS, (C) daisyUI, (D) Pico CSS.
-     2. **Design School (D2)**: (A) Swiss Modern, (B) Neo-Brutalism, (C) Editorial Luxury, (D) Egyptian / Regional Heritage.
-     3. **Layout Archetype (D4)**: (A) Split Hero Canvas, (B) Narrative Editorial, (C) Command Dashboard.
+1. **Local Discovery & Staleness Check**:
+   - Check `.tidyfactor/design-brief.snapshot.json` and `brand.json`.
+   - If `brand.json` has changed since the snapshot was saved (`track_staleness: true`), invalidate the cached value and mark `surface_type` / `tone_school` as `Unknown`.
+2. **Optional Brain MCP Lookup (Fail-Open)**:
+   - If decisions remain Unknown and `search_knowledge_base` is active, query `search_knowledge_base(query="design context", scope="project")`.
+   - If absent or empty, proceed with 0ms silent bypass.
+3. **Delta Evaluation**:
+   - If $\text{Unknowns} = \emptyset$: Skip all questioning immediately and emit confirmed baseline.
+   - If $\text{Unknowns} \neq \emptyset$: Proceed to Step 1 for **only the missing keys**.
 
-4. **Record Decisions**:
-   - Persist confirmed parameters into `.tidyfactor/design-brief.md`.
+---
+
+## 💬 Step 1: Surgical Micro-Discovery (Only for Unknown Decisions)
+
+> **Anti-Bot Constraint**: Never greet the user or ask for facts already resolved on disk. Present at most `max_interactive_questions` (3) sorted by priority:
+
+- **Audience Mode (Priority 1)**: `(A) act` (Default), `(B) inspire`, `(C) evaluate`, `(D) learn`.
+- **Surface Type (Priority 2)**: `(A) landing` (Default), `(B) dashboard`, `(C) product`, `(D) editorial`, `(E) interface`, `(F) minimal`.
+- **Tone School (Priority 3)**: `(A) minimal` (Default), `(B) neo-brutalism`, `(C) luxury`, `(D) swiss`, `(E) bento`, `(F) heritage-nilotic`, `(G) heritage-kufic`.
+
+---
+
+## 💾 Step 2: SSOT Local Persistence & Outbound Push
+
+1. **Write Local SSOT**: Persist resolved choices + source file hashes to `.tidyfactor/design-brief.snapshot.json` and `.tidyfactor/design-brief.md`.
+2. **Outbound Push to Brain (`--sync-brain`)**:
+   - If and ONLY IF invoked with `--sync-brain`, push the resolved `design_context` KI via `extract_knowledge_item`.
+   - The local snapshot remains the immutable source of truth.
+
+---
+
+## 🎯 Step 3: Summary & Actionable Handoff
 
-5. **Report Summary**:
-   - Present a concise baseline summary and suggest next action (`/init`, `/tokens`, `/components`).
+Display a concise 4-line baseline summary and suggest next action (`/tokens`, `/layout`, `/components`).
 
 ---
 
 ## Validation checklist
 
-- [ ] `.tidyfactor/design-brief.md` exists and contains confirmed values for D1–D5.
-- [ ] No more than 3 questions were asked in a single round.
-- [ ] Design baseline conforms to `references/memory/quality-bar.md`.
+- [ ] Evaluated Context Delta Resolution against `manifest.json["decision_gates"]`.
+- [ ] Only truly Unknown decisions were surfaced to the user.
+- [ ] `.tidyfactor/design-brief.snapshot.json` and `.tidyfactor/design-brief.md` written as local SSOT.
+- [ ] If `--sync-brain` was passed, outbound push was executed without blocking local output.
+- [ ] Baseline conforms to `references/memory/quality-bar.md`.
diff --git a/tools/build-skill.js b/tools/build-skill.js
@@ -68,6 +68,7 @@ function build() {
   log('staging single-source-of-truth files from repo root...');
   const whitelist = [
     'SKILL.md',
+    'manifest.json',
     'references',
     'memory',
     'templates',