diff --git a/.tidyfactor b/.tidyfactor index 82fafa3..085507c 100644 --- 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 index 04ca2b6..cd42149 100644 --- 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 index a4ee2de..30ff51b 100644 --- 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 index 279de5d..9c49cd7 100644 Binary files a/dist/tidyfactor-design.skill and b/dist/tidyfactor-design.skill differ diff --git a/dist/tidyfactor-design/.tidyfactor b/dist/tidyfactor-design/.tidyfactor index 82fafa3..085507c 100644 --- 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 index 04ca2b6..cd42149 100644 --- 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 index a4ee2de..30ff51b 100644 --- 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 index 0c2bff2..c6e2ee2 100644 --- 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 index 55ad3f2..d47e3ec 100644 --- 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 index a2ea5e5..7a9cc00 100644 --- 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 index 66c97bf..73bcf7d 100644 --- 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 index 0c2bff2..c6e2ee2 100644 --- 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 index 55ad3f2..d47e3ec 100644 --- 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 index a2ea5e5..7a9cc00 100644 --- 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',