Add product truth gate skill

README.md

@@ -9,12 +9,20 @@ Codex skills maintained by IgnitionAI.
 Collaborative application architecture design through Socratic brainstorming.
 This skill produces architecture specifications and diagrams only: domain models,
 database diagrams, layered architecture blueprints, stack decision records,
-API contracts, ADRs, and validation checklists.
+API contracts, ADRs, Product Truth Contracts, and validation checklists.
+
+### product-truth-gate
+
+Defines and enforces an observable product-outcome contract before a feature,
+application, integration, migration, or repair can be declared usable or done.
+It distinguishes architecture and internal checks from a verified end-to-end
+user journey, and supports same-scenario parity checks against a reference.
 
 ## Installation
 
 ```bash
 python /path/to/install-skill-from-github.py --repo IgnitionAI/skills --path app-architect-brainstorm
+python /path/to/install-skill-from-github.py --repo IgnitionAI/skills --path product-truth-gate
 ```
 
 After installation, restart Codex to pick up the skill.

app-architect-brainstorm/SKILL.md

@@ -1,22 +1,15 @@
 ---
 name: app-architect-brainstorm
 description: >
-  Collaborative application architecture design through Socratic brainstorming.
-  Produces complete architecture specification packages: domain models, UML database diagrams,
-  layered architecture blueprints, component specifications, technology stack recommendations,
-  architecture decision records, and UI/UX design prototypes (static HTML mockup pages).
-  Covers all application archetypes: web apps, mobile apps,
-  API-only services, ML/inference APIs, desktop, real-time systems, CLI tools.
-  Framework-agnostic and language-agnostic — the stack emerges from requirements.
-  This skill produces SPECIFICATIONS, DIAGRAMS, AND STATIC HTML DESIGN MOCKUPS ONLY.
-  It does not generate production source code, boilerplate files, or executable artifacts.
-  HTML mockups are design artifacts (one self-contained page per key screen), never
-  production front-end code. The output is a comprehensive architecture
-  document package that serves as the blueprint for implementation.
-  Triggers on: architecture, system design, database modeling, clean architecture, DDD,
-  tech stack selection, project structuring, how to structure my app, design my backend,
-  plan my architecture, model my domain, UI design, UX design, mockup, prototype,
-  wireframe, design my frontend, design my screens.
+  Design greenfield or existing application architecture through Socratic
+  brainstorming. Produces framework-agnostic specification packages with domain
+  models, database and architecture diagrams, API and component contracts,
+  stack decisions, ADRs, product-truth contracts, guardian rules, and static HTML
+  UI/UX mockups. Covers web, mobile, API, ML, desktop, real-time, CLI, and data
+  systems. Use for architecture, system design, database modeling, DDD, stack
+  selection, project structure, reverse engineering, UI/UX flows, mockups, or
+  prototypes. Produces specifications and static design artifacts only, never
+  production code, boilerplate, configuration, or executable projects.
 license: MIT
 ---
 
@@ -38,6 +31,7 @@ Collaborative architecture design through structured Socratic brainstorming. Age
 | Architecture Decision Records | Markdown | ADR-xxx for each significant decision |
 | Component Specification | Markdown | Per-component responsibilities and interfaces |
 | Architecture Contract | Markdown | Machine-verifiable rules for the project |
+| Product Truth Contract | Markdown | Observable critical journey, runtime topology, failure signals, and future E2E proof |
 | Guardian Checklist | Markdown | Validation rules to prevent architectural drift |
 | UI/UX Design Package | Static HTML pages | One self-contained mockup per key screen + user flows, screen inventory, design tokens |
 
@@ -65,6 +59,7 @@ When the user has no existing codebase — designing a new application.
 
 ```
 Phase 1: Domain Discovery     → Business model, entities, constraints, archetype
+Phase 1.5: Product Truth      → Observable outcome contract and required runtime topology
 Phase 2: Stack Selection      → Language, frameworks, databases (evidence-based)
 Phase 3: Database Modeling    → ER diagram (Mermaid), relations, access patterns
 Phase 4: Architecture Design  → Layers, components, services, API design
@@ -80,6 +75,7 @@ When the user provides an existing codebase — analyze, document, and plan migr
 Phase R1: Codebase Discovery     → Understand what exists (files, deps, patterns)
 Phase R2: Architecture Mapping   → Map files to layers (or identify no layers)
 Phase R3: Violation Detection    → Find anti-patterns, coupling, leaks
+Phase R3.5: Product Truth        → Reconstruct the real runnable journey and its topology
 Phase R4: Architecture Blueprint → Produce diagrams of the AS-IS state
 Phase R5: Migration Plan         → Roadmap to TO-BE Clean Architecture
 ```
@@ -137,6 +133,8 @@ Challenge the domain understanding before any technical decision:
 8. **"What is the scale in 6 months? Users, requests/day, data volume?"**
 9. **"What is the team size and experience?"**
 10. **"What is the budget for infrastructure?"**
+11. **"What exact sentence may we say only when the product truly works?"**
+12. **"What is the first meaningful action after the initial screen or response?"**
 
 ### Step 1C: Extract the Domain Model
 
@@ -153,6 +151,31 @@ Reference: [references/brainstorming-method.md](references/brainstorming-method.
 
 ---
 
+## Phase 1.5: Product Truth Contract
+
+Architecture quality and product success are separate claims. Before selecting
+the stack, define one Product Truth Contract per P0 critical journey:
+
+- actor and intended starting state;
+- exact trigger, observable outcome, and first meaningful continuation;
+- complete required runtime topology (UI, APIs, workers, stores, queues,
+  assets, auth, external systems, configuration);
+- concrete failure signals;
+- forbidden substitutes such as mocks, manual database edits, hidden setup,
+  skipped services, or product-specific patches outside the intended workflow;
+- one planned deterministic E2E test that can fail on the user's exact symptom;
+- a same-scenario parity bar when a reference product is named.
+
+Trace every required topology item to a component and operational owner in the
+later architecture. This phase produces a specification only and must end in
+state `architected`, never `product_verified`.
+
+When available, use `product-truth-gate` during implementation and validation
+to execute this contract. The architecture package must remain usable without
+that skill by containing the full contract itself.
+
+---
+
 ## Phase 2: Stack Selection (Evidence-Based)
 
 ### The Rule
@@ -369,8 +392,9 @@ Reference: [references/ui-ux-design.md](references/ui-ux-design.md) — **read i
 5. **Stack Decision Record**: Justified choices with rejected alternatives
 6. **ADR files** (from template): One per significant decision
 7. **Architecture Contract**: Machine-verifiable rules for the project
-8. **UI/UX Design Package** (UI archetypes only): HTML mockups gallery, user flows, screen inventory, design tokens
-8. **Guardian Checklist**: Rules to prevent drift during implementation
+8. **Product Truth Contract**: P0 journey, topology, failure signals, forbidden substitutes, planned E2E proof
+9. **UI/UX Design Package** (UI archetypes only): HTML mockups gallery, user flows, screen inventory, design tokens
+10. **Guardian Checklist**: Rules to prevent architectural and product-proof drift during implementation
 
 ### Architecture Contract
 
@@ -391,6 +415,9 @@ Provide the implementation team with:
 - Verification commands (grep patterns to check layer boundaries)
 
 **Note**: The guardian validates the implementation against this architecture contract. It does not generate code.
+It must also reject completion claims whose Product Truth Contract has not been
+executed at the required proof level; architecture checks cannot substitute for
+that future runtime evidence.
 
 ---
 
@@ -408,6 +435,9 @@ Provide the implementation team with:
 | **UI designed with lorem ipsum** | "Show me the real longest value. Does the layout survive it?" |
 | **No empty/error states** | "Zero items is the FIRST thing a new user sees. What does the API-down screen look like?" |
 | **UX skipped for a UI archetype** | "You specified an interface layer without knowing what users see. Mock the key screens first." |
+| **Internal-green means product-done** | "Which Product Truth Contract proves the critical journey and its first meaningful continuation?" |
+| **Single component for a multi-service journey** | "Which required API, worker, store, asset, auth, or external dependency is being skipped?" |
+| **Screenshot or HTTP 200 as E2E proof** | "Could this evidence pass while the next user action, API call, or asset still fails?" |
 
 ## Reference Loading Guide
 

app-architect-brainstorm/assets/VALIDATION-CHECKLIST.md

@@ -7,6 +7,25 @@ This checklist prevents the agent from generating "pragmatic" code that bypasses
 
 ---
 
+## Section 0: Product Truth Contract
+
+Before accepting the architecture package, verify that every P0 journey has a
+Product Truth Contract containing:
+
+- an exact product claim, actor, intended starting state, trigger, observable
+  outcome, and first meaningful continuation;
+- the complete required runtime topology, including APIs, workers, stores,
+  assets, auth, external systems, and configuration where applicable;
+- explicit failure signals and forbidden substitutes;
+- one planned deterministic E2E proof that can fail on the user's exact symptom;
+- a same-scenario parity bar when a reference product is named.
+
+The architecture package must label this evidence state `architected`. Static
+mockups, diagrams, guardian checks, and internal tests must never be described
+as `product_verified`.
+
+---
+
 ## Section A: Folder Structure Compliance
 
 Verify the generated folders match the required architecture exactly:

app-architect-brainstorm/assets/templates/arch-spec-template.md

@@ -20,6 +20,30 @@
 - {Metric 1}
 - {Metric 2}
 
+## 2.1 Product Truth Contract
+
+| Field | Decision |
+|-------|----------|
+| Contract ID | `PTC-001` |
+| Product claim | {Exact sentence allowed only when the journey passes} |
+| Required proof level | {L4 product outcome / L5 reference parity} |
+| Actor and starting state | {Role, repository/data/auth/environment} |
+| Trigger | {Exact user action or request} |
+| Observable outcome | {Visible or consumer-visible result} |
+| Critical continuation | {First meaningful action after initial success} |
+| Required topology | {UI, API, workers, stores, assets, auth, external systems} |
+| Failure signals | {Conditions that make the gate fail} |
+| Forbidden substitutes | {Mocks, manual setup, skipped services, one-off patches} |
+| Planned evidence command | {Deterministic E2E test capable of reproducing the failure} |
+| Reference and parity bar | {If applicable: identical scenario and allowed differences} |
+
+### Journey Traceability
+| Step | Required component/data | Observable assertion | Failure diagnostic |
+|------|-------------------------|----------------------|--------------------|
+| {1} | {...} | {...} | {...} |
+
+**Architecture-phase state:** `architected` — runtime verification belongs to implementation and validation.
+
 ## 3. Domain Model
 ### Core Entities
 ```mermaid

product-truth-gate/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: product-truth-gate
+description: >
+  Define and enforce an observable product-outcome contract before declaring a
+  feature, application, integration, migration, or repair usable or complete.
+  Use when success depends on a real user journey or several runtime components,
+  especially for existing repositories, local previews, deployments, imports,
+  integrations, or comparisons with a reference product. Do not invoke for
+  documentation-only work or isolated code changes that make no product claim.
+---
+
+# Product Truth Gate
+
+Prevent plausible architecture, green internal tests, HTTP success, or a visible
+shell from being mistaken for a working product. The gate evaluates the exact
+outcome promised to the user, at the boundary where they experience it.
+
+This skill does not replace architecture, implementation, QA, or security
+review. It decides what evidence is allowed to support a product claim.
+
+## Non-negotiable rule
+
+Never claim `done`, `fixed`, `usable`, `live`, `ready`, or parity with another
+product unless the required Product Truth Contract has passed end to end.
+
+Lower-level evidence is useful but cannot substitute for higher-level evidence:
+
+| Level | Evidence | What it proves |
+|---|---|---|
+| L0 | Architecture, specification, diagrams | The solution is reasoned about |
+| L1 | Static checks and unit tests | Isolated rules behave as expected |
+| L2 | Component and integration tests | Selected boundaries cooperate |
+| L3 | Visible surface or successful response | A screen or endpoint can load |
+| L4 | Critical user journey with its required runtime topology | The promised outcome works |
+| L5 | Same-scenario comparison against a named reference | The stated parity claim is supported |
+
+If the user's claim requires L4, L0-L3 remain `implemented_unverified` or
+`partially_working`. A screenshot, `200`, health check, process PID, `live`
+badge, or green unit suite is never L4 by itself.
+
+## 1. Write the Product Truth Contract first
+
+Before implementation or diagnosis, make the contract explicit. For an
+architecture-only task, include it in the architecture package as a future
+implementation gate; do not pretend to execute it.
+
+Capture:
+
+- **Actor and starting state**: who starts where, with what repository/data/auth.
+- **Trigger**: the exact action the actor performs.
+- **Observable outcome**: what must be visible or possible afterward.
+- **Critical continuation**: the first meaningful action after initial render.
+- **Required topology**: frontend, APIs, workers, databases, object stores,
+  queues, third-party services, assets, auth, configuration, and ports that the
+  journey actually needs.
+- **Failure signals**: messages, blank assets, failed requests, broken reloads,
+  missing data, dead controls, or degraded behavior that make the gate red.
+- **Forbidden substitutes**: mocks, synthetic data, manual database edits,
+  one-off commands, hidden configuration, skipped services, or product-specific
+  patches that the intended workflow would not perform.
+- **Evidence command**: one deterministic, agent-runnable test that can go red
+  on the exact user-visible failure.
+- **Reference scenario**: when parity is claimed, the identical input and
+  journey to run on both products.
+
+Use [references/truth-contract-template.md](references/truth-contract-template.md)
+when producing or auditing a formal contract.
+
+If a material field is unknown, ask or discover it. Do not silently weaken the
+claim to match what is easy to test.
+
+## 2. Reconstruct the real runtime topology
+
+For an existing repository, derive topology from the repository and runtime,
+not from the most convenient package:
+
+1. Inspect root scripts, workspace manifests, compose files, environment
+   schemas, service entry points, asset paths, API base URLs, workers, migrations,
+   and readiness dependencies.
+2. Map each step of the critical journey to the process and data it needs.
+3. Mark services as required, optional, or external, with evidence.
+4. Challenge any plan that starts only one component of a multi-service journey.
+
+Starting the frontend alone is valid only when the contract explicitly asks for
+a frontend-only artifact. Otherwise it is partial evidence, not product success.
+
+## 3. Build a red-capable truth loop
+
+Create the smallest deterministic loop that exercises the real boundary:
+
+- Prefer a browser or API E2E that performs the user's action and asserts both
+  the visible result and the critical continuation.
+- Verify resource loading, API calls, authentication, persistence/reload, and
+  required background work when they are part of the contract.
+- Run it before the fix and record the red symptom.
+- Keep it runnable without human interpretation. A human screenshot review may
+  supplement the loop, but must not be its only assertion.
+
+If the environment prevents the loop from running, report `blocked_unverified`.
+Do not implement around the missing proof and later call the outcome complete.
+
+## 4. Implement against the contract
+
+Use lower-level tests to localize failures, but repeatedly return to the truth
+loop. Every workaround must answer:
+
+- Would a fresh user or fresh checkout receive this automatically?
+- Does it preserve the intended security and architecture boundaries?
+- Does it work after restart and reload?
+- Does it support the next meaningful action, not just the first paint?
+- Is this general behavior or an undeclared product-specific exception?
+
+Manual state mutation may be useful for diagnosis. It is never completion
+evidence unless manual operation is explicitly part of the product contract.
+
+## 5. Run the adversarial completion review
+
+Before reporting success, actively try to falsify it:
+
+- Start from the user's actual initial state or a clean equivalent.
+- Run the exact truth loop again.
+- Inspect failed network requests and missing assets, not only DOM presence.
+- Exercise the first meaningful control after load.
+- Reload or restart when persistence/runtime recovery is part of normal use.
+- For parity, run the same scenario against the reference and record meaningful
+  differences rather than comparing feature lists.
+
+Produce a claim-to-evidence table:
+
+| Claim | Required level | Evidence | Result |
+|---|---:|---|---|
+| ... | L4 | exact command/artifact | pass/fail/blocked |
+
+One failed required claim makes the product gate fail.
+
+## 6. Use honest completion states
+
+Report exactly one state:
+
+- `architected`: specification exists; runtime outcome not implemented.
+- `implemented_unverified`: code exists; truth loop did not run.
+- `partially_working`: some required claims pass and at least one fails.
+- `blocked_unverified`: the required proof cannot run in the current environment.
+- `product_verified`: every required claim passes from the intended starting state.
+- `parity_verified`: L5 same-scenario comparison passes the declared parity bar.
+
+Lead with failed or blocked product claims even when internal checks are green.
+Do not average architecture quality and runtime failure into a positive verdict.
+
+## Pairing with app-architect-brainstorm
+
+The pairing is deliberately asymmetric:
+
+- `app-architect-brainstorm` discovers and writes the Product Truth Contract as
+  part of the architecture package.
+- `product-truth-gate` consumes that contract during implementation, repair,
+  validation, and parity assessment.
+- The architecture phase may declare `architected`, never `product_verified`.
+- If implementation reveals missing topology or an invalid assumption, update
+  the architecture contract rather than weakening the product truth gate.
+
+The Product Truth Contract should influence component boundaries, local
+developer experience, orchestration, observability, acceptance tests, and the
+guardian checklist. It must remain outcome-focused rather than prescribing an
+implementation prematurely.

product-truth-gate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Product Truth Gate"
+  short_description: "Prove real product outcomes before declaring done"
+  default_prompt: "Use $product-truth-gate to define and verify the real user outcome before declaring this work complete."