Add youaskm3 real shell validation (#194)

Author: enricopiovesan

README.md

@@ -157,6 +157,7 @@ Traverse is spec-driven. Code must align with an approved, immutable spec or it
 - [docs/adapter-boundaries.md](docs/adapter-boundaries.md) — adapter and portability boundaries
 - [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) — youaskm3 integration validation
 - [docs/youaskm3-compatibility-conformance-suite.md](docs/youaskm3-compatibility-conformance-suite.md) — youaskm3 compatibility conformance suite
+- [docs/youaskm3-real-shell-validation.md](docs/youaskm3-real-shell-validation.md) — youaskm3 real shell validation
 - [docs/quality-standards.md](docs/quality-standards.md) — non-negotiable quality rules
 - [docs/compatibility-policy.md](docs/compatibility-policy.md) — versioning and compatibility
 - [docs/multi-thread-workflow.md](docs/multi-thread-workflow.md) — parallel agent workflow

docs/app-consumable-entry-path.md

@@ -13,6 +13,7 @@ This is the canonical documentation path for humans and coding agents working on
    - [docs/app-consumable-requirements-traceability.md](/Users/piovese/Documents/cogolo/docs/app-consumable-requirements-traceability.md)
    - [docs/youaskm3-integration-validation.md](/Users/piovese/Documents/cogolo/docs/youaskm3-integration-validation.md)
    - [docs/youaskm3-compatibility-conformance-suite.md](/Users/piovese/Documents/cogolo/docs/youaskm3-compatibility-conformance-suite.md)
+   - [docs/youaskm3-real-shell-validation.md](/Users/piovese/Documents/cogolo/docs/youaskm3-real-shell-validation.md)
    - [apps/browser-consumer/README.md](/Users/piovese/Documents/cogolo/apps/browser-consumer/README.md)
 
 ## Canonical Rule
@@ -25,6 +26,7 @@ If a new human or agent asks where to begin, point them to the README first and
 - The quickstart is the first executable consumer path.
 - The versioned consumer bundle explains what a downstream app installs and which released surfaces it may rely on.
 - The conformance suite explains how the released Traverse and `youaskm3` surfaces are proven together.
+- The real-shell validation explains how the browser-hosted `youaskm3` shell is checked against the released Traverse consumer artifacts.
 - The deeper docs explain validation, release, and traceability after the first path is understood.
 - Competing entrypoints should be treated as references, not as the first recommended path.
 

docs/app-consumable-release-checklist.md

@@ -20,6 +20,7 @@ Traverse MUST NOT claim `app-consumable v0.1` unless all of the following are sa
 - [ ] The first versioned Traverse consumer bundle is documented in [docs/app-consumable-consumer-bundle.md](/Users/piovese/Documents/cogolo/docs/app-consumable-consumer-bundle.md).
 - [ ] The downstream MCP consumption path exists and passes [scripts/ci/mcp_consumption_validation.sh](/Users/piovese/Documents/cogolo/scripts/ci/mcp_consumption_validation.sh).
 - [ ] The first real `youaskm3` integration path exists and passes [scripts/ci/youaskm3_integration_validation.sh](/Users/piovese/Documents/cogolo/scripts/ci/youaskm3_integration_validation.sh).
+- [ ] The real browser-hosted `youaskm3` shell validation exists and passes [scripts/ci/youaskm3_real_shell_validation.sh](/Users/piovese/Documents/cogolo/scripts/ci/youaskm3_real_shell_validation.sh).
 - [ ] The end-to-end acceptance path exists and passes [scripts/ci/app_consumable_acceptance.sh](/Users/piovese/Documents/cogolo/scripts/ci/app_consumable_acceptance.sh).
 - [ ] The operational constraints for app-facing browser and MCP surfaces are documented in [docs/adapter-boundaries.md](/Users/piovese/Documents/cogolo/docs/adapter-boundaries.md) and [docs/compatibility-policy.md](/Users/piovese/Documents/cogolo/docs/compatibility-policy.md).
 - [ ] The consumer contract and integration-validation model remain aligned with approved governing specs.
@@ -36,6 +37,7 @@ The release decision should be backed by:
 - the browser live-adapter smoke path
 - the MCP consumption validation path
 - the first real `youaskm3` integration validation path
+- the real browser-hosted `youaskm3` shell validation path
 - the end-to-end app-consumable acceptance path
 - reviewable PR checks on the release-related documentation and validation artifacts
 
@@ -62,7 +64,8 @@ A reviewer can answer the release question by checking:
 6. the live browser adapter smoke path
 7. the MCP validation path
 8. the first real `youaskm3` integration validation path
-9. the end-to-end acceptance path
-10. the release artifact and publication bundle definition
+9. the real browser-hosted `youaskm3` shell validation path
+10. the end-to-end acceptance path
+11. the release artifact and publication bundle definition
 
 If those artifacts and checks exist and are passing, the first app-consumable release can be evaluated on evidence rather than interpretation.

docs/app-consumable-requirements-traceability.md

@@ -14,6 +14,7 @@ Project 1 is the canonical task board for this work. Every requirement area belo
 | Versioned consumer bundle and installation steps | [#176](https://github.com/enricopiovesan/Traverse/issues/176) | `Ready` |
 | Live browser-consumer path | [#120](https://github.com/enricopiovesan/Traverse/issues/120), [#121](https://github.com/enricopiovesan/Traverse/issues/121), [#123](https://github.com/enricopiovesan/Traverse/issues/123) | `Done` |
 | Downstream consumer contract and app-facing validation | [#126](https://github.com/enricopiovesan/Traverse/issues/126), [#128](https://github.com/enricopiovesan/Traverse/issues/128), [#129](https://github.com/enricopiovesan/Traverse/issues/129) | `Done` |
+| Real browser-hosted `youaskm3` shell validation | [#179](https://github.com/enricopiovesan/Traverse/issues/179) | `In Progress` |
 | MCP WASM server model and validation | [#146](https://github.com/enricopiovesan/Traverse/issues/146), [#158](https://github.com/enricopiovesan/Traverse/issues/158), [#148](https://github.com/enricopiovesan/Traverse/issues/148) | `Done` / `In Progress` / `Blocked` |
 
 ## Non-Functional Requirements
@@ -32,6 +33,7 @@ Project 1 is the canonical task board for this work. Every requirement area belo
 - [#144](https://github.com/enricopiovesan/Traverse/issues/144) `Establish one canonical documentation entry path for humans and agents` - `Ready`
 - [#145](https://github.com/enricopiovesan/Traverse/issues/145) `Refresh release and requirements traceability docs for current v0.1 state` - `In Progress`
 - [#158](https://github.com/enricopiovesan/Traverse/issues/158) `Implement MCP stdio server package foundation` - `In Progress`
+- [#179](https://github.com/enricopiovesan/Traverse/issues/179) `Validate the real browser-hosted youaskm3 shell against released Traverse consumer artifacts` - `In Progress`
 - [#150](https://github.com/enricopiovesan/Traverse/issues/150) `Prepare and validate the first Traverse v0.1 GitHub release artifact` - `In Progress`
 - [#176](https://github.com/enricopiovesan/Traverse/issues/176) `Publish versioned Traverse consumer bundle for downstream app integration` - `Ready`
 - [#130](https://github.com/enricopiovesan/Traverse/issues/130) `Define first app-consumable performance baseline` - `Blocked`

docs/youaskm3-compatibility-conformance-suite.md

@@ -3,6 +3,7 @@
 This document defines the first deterministic compatibility and conformance suite for Traverse and `youaskm3`.
 
 The suite exists so a reviewer can prove that the released Traverse surfaces remain consumable by `youaskm3` without depending on repo archaeology, ad hoc environment setup, or private Traverse internals.
+The real browser-hosted shell validation is documented separately in [docs/youaskm3-real-shell-validation.md](/Users/piovese/Documents/cogolo/docs/youaskm3-real-shell-validation.md).
 
 This youaskm3 compatibility conformance suite is the release-aligned proof path for the downstream consumer contract.
 
@@ -14,6 +15,7 @@ The suite covers the released downstream path end to end:
 - the live browser-hosted consumer path
 - the app-facing MCP consumption path
 - the first real `youaskm3` integration path
+- the browser-hosted `youaskm3` real shell validation path
 
 It does not define new runtime behavior. It verifies that the supported Traverse surfaces continue to fit together as a released consumer set.
 
@@ -57,6 +59,7 @@ The suite is expected to fail deterministically when:
 - the live browser-hosted adapter path is unavailable
 - the MCP consumer path is unavailable
 - the first real `youaskm3` validation path is unavailable
+- the browser-hosted shell validation path is unavailable
 
 ## Verification
 
@@ -66,3 +69,4 @@ A reviewer can verify the suite by checking:
 2. the live browser-hosted smoke path
 3. the MCP consumption validation path
 4. the first real `youaskm3` integration validation path
+5. the browser-hosted real shell validation path

docs/youaskm3-integration-validation.md

@@ -11,6 +11,8 @@ It stays on governed public Traverse surfaces only:
 - the versioned Traverse consumer bundle
 - [docs/youaskm3-compatibility-conformance-suite.md](/Users/piovese/Documents/cogolo/docs/youaskm3-compatibility-conformance-suite.md)
 - the `youaskm3` compatibility conformance suite
+- [docs/youaskm3-real-shell-validation.md](/Users/piovese/Documents/cogolo/docs/youaskm3-real-shell-validation.md)
+- the `youaskm3` real shell validation
 
 For the shortest Traverse-side start path, begin with [quickstart.md](/Users/piovese/Documents/cogolo/quickstart.md).
 
@@ -51,6 +53,12 @@ For the broader release-aligned compatibility check, also run:
 bash scripts/ci/youaskm3_compatibility_conformance.sh
 ```
 
+For the real browser-hosted shell validation against released Traverse consumer artifacts, also run:
+
+```bash
+bash scripts/ci/youaskm3_real_shell_validation.sh
+```
+
 ## Expected Evidence
 
 The validation path should prove:
@@ -62,6 +70,8 @@ The validation path should prove:
 - `validated_flow_id: youaskm3_mcp_validation`
 - no dependency on private Traverse internals or undocumented setup
 - the same Traverse v0.1 release pairing used by the compatibility conformance suite
+- the browser-hosted shell spec at `openspec/specs/pwa-shell/spec.md`
+- the downstream repo-local smoke validation at `scripts/smoke.sh`
 
 ## Known Failure Modes
 

docs/youaskm3-real-shell-validation.md

@@ -0,0 +1,60 @@
+# youaskm3 Real Shell Validation
+
+This document defines the Traverse-side validation path for the real browser-hosted `youaskm3` shell against released Traverse consumer artifacts.
+
+It is the evidence path for the downstream shell specification at [youaskm3/openspec/specs/pwa-shell/spec.md](https://github.com/enricopiovesan/youaskm3/blob/main/openspec/specs/pwa-shell/spec.md).
+This youaskm3 real shell validation is the Traverse-side proof path for the downstream browser-hosted shell.
+
+## Governing Spec
+
+- `specs/019-downstream-consumer-contract/spec.md`
+- `specs/020-downstream-integration-validation/spec.md`
+- `specs/021-app-facing-operational-constraints/spec.md`
+
+## Purpose
+
+Use one deterministic Traverse-side validation flow to prove that the downstream browser-hosted shell can consume the released Traverse consumer artifacts without relying on private Traverse internals or undocumented setup.
+
+## Prerequisites
+
+- A local Traverse checkout with the released consumer bundle documentation available.
+- A checked-out `youaskm3` repository available at `YOUASKM3_REPO_ROOT`.
+- The downstream repository exposes the browser-hosted shell spec at `openspec/specs/pwa-shell/spec.md`.
+- The downstream repository exposes its own deterministic smoke path in `scripts/smoke.sh`.
+
+## Traverse Validation Path
+
+Run the Traverse-side wrapper:
+
+```bash
+bash scripts/ci/youaskm3_real_shell_validation.sh
+```
+
+That wrapper validates the documented Traverse release artifacts first and then, when `YOUASKM3_REPO_ROOT` is set, verifies that the downstream shell repository is present and can run its own smoke path.
+
+## Expected Evidence
+
+The validation path should prove:
+
+- the released Traverse consumer bundle is documented
+- the downstream browser-hosted shell spec is present
+- the downstream shell repo can be located through `YOUASKM3_REPO_ROOT`
+- the downstream shell can run its repo-local smoke validation
+- the observed path uses only documented public surfaces
+- at least one setup or incompatibility failure mode is detectable
+
+## Known Failure Modes
+
+The validation is expected to fail deterministically when:
+
+- the released Traverse consumer bundle documentation is missing
+- `YOUASKM3_REPO_ROOT` is unset or points at the wrong repository
+- the downstream shell spec is missing
+- the downstream smoke path is unavailable
+- the downstream shell environment is missing its lint toolchain, which is detected when `scripts/smoke.sh` fails at the `eslint` step
+
+## Validation
+
+- `bash scripts/ci/youaskm3_real_shell_validation.sh`
+- `bash scripts/ci/youaskm3_integration_validation.sh`
+- `bash scripts/ci/repository_checks.sh`

scripts/ci/repository_checks.sh

@@ -25,6 +25,7 @@ required_files=(
   "docs/app-consumable-release-artifact.md"
   "docs/youaskm3-integration-validation.md"
   "docs/youaskm3-compatibility-conformance-suite.md"
+  "docs/youaskm3-real-shell-validation.md"
   "apps/browser-consumer/README.md"
   "apps/browser-consumer/package.json"
   "apps/youaskm3-starter-kit/README.md"
@@ -52,6 +53,7 @@ required_files=(
   "scripts/ci/youaskm3_compatibility_conformance.sh"
   "scripts/ci/browser_consumer_package_smoke.sh"
   "scripts/ci/youaskm3_integration_validation.sh"
+  "scripts/ci/youaskm3_real_shell_validation.sh"
   "scripts/ci/app_consumable_release_prep.sh"
   "scripts/ci/mcp_stdio_server_smoke.sh"
   "scripts/ci/mcp_stdio_server_discovery_smoke.sh"
@@ -128,14 +130,21 @@ grep -q "mcp_stdio_server_execution_report_smoke.sh" docs/mcp-stdio-server.md
 grep -q "render_execution_report" docs/mcp-stdio-server.md
 grep -q "docs/youaskm3-integration-validation.md" docs/mcp-consumption-validation.md
 grep -q "docs/youaskm3-compatibility-conformance-suite.md" README.md
+grep -q "docs/youaskm3-real-shell-validation.md" README.md
 grep -q "docs/youaskm3-compatibility-conformance-suite.md" docs/app-consumable-entry-path.md
+grep -q "docs/youaskm3-real-shell-validation.md" docs/app-consumable-entry-path.md
 grep -q "docs/youaskm3-compatibility-conformance-suite.md" docs/mcp-consumption-validation.md
 grep -q "docs/youaskm3-compatibility-conformance-suite.md" docs/youaskm3-integration-validation.md
+grep -q "docs/youaskm3-real-shell-validation.md" docs/youaskm3-integration-validation.md
 grep -q "youaskm3 compatibility conformance suite" docs/youaskm3-compatibility-conformance-suite.md
 grep -q "version pairing" docs/youaskm3-compatibility-conformance-suite.md
 grep -q "bash scripts/ci/youaskm3_compatibility_conformance.sh" docs/youaskm3-compatibility-conformance-suite.md
 grep -q "bash scripts/ci/youaskm3_compatibility_conformance.sh" docs/youaskm3-integration-validation.md
 grep -q "the same Traverse v0.1 release pairing" docs/youaskm3-integration-validation.md
+grep -q "youaskm3 real shell validation" docs/youaskm3-real-shell-validation.md
+grep -q "openspec/specs/pwa-shell/spec.md" docs/youaskm3-real-shell-validation.md
+grep -q "bash scripts/ci/youaskm3_real_shell_validation.sh" docs/youaskm3-real-shell-validation.md
+grep -q "scripts/smoke.sh" docs/youaskm3-real-shell-validation.md
 grep -q "apps/browser-consumer/README.md" docs/mcp-consumption-validation.md
 grep -q "docs/app-consumable-consumer-bundle.md" README.md
 grep -q "docs/app-consumable-consumer-bundle.md" docs/app-consumable-entry-path.md

scripts/ci/youaskm3_real_shell_validation.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+required_files=(
+  "docs/youaskm3-real-shell-validation.md"
+  "docs/youaskm3-integration-validation.md"
+  "docs/youaskm3-compatibility-conformance-suite.md"
+  "docs/app-consumable-consumer-bundle.md"
+)
+
+for file in "${required_files[@]}"; do
+  test -f "$file"
+  test -s "$file"
+done
+
+grep -q "youaskm3 real shell validation" docs/youaskm3-real-shell-validation.md
+grep -q "bash scripts/ci/youaskm3_real_shell_validation.sh" docs/youaskm3-real-shell-validation.md
+grep -q "YOUASKM3_REPO_ROOT" docs/youaskm3-real-shell-validation.md
+grep -q "openspec/specs/pwa-shell/spec.md" docs/youaskm3-real-shell-validation.md
+grep -q "scripts/smoke.sh" docs/youaskm3-real-shell-validation.md
+grep -q "released Traverse consumer artifacts" docs/youaskm3-real-shell-validation.md
+
+if [[ -n "${YOUASKM3_REPO_ROOT:-}" ]]; then
+  test -d "${YOUASKM3_REPO_ROOT}"
+  test -f "${YOUASKM3_REPO_ROOT}/README.md"
+  test -f "${YOUASKM3_REPO_ROOT}/openspec/specs/pwa-shell/spec.md"
+  test -f "${YOUASKM3_REPO_ROOT}/scripts/smoke.sh"
+  bash "${YOUASKM3_REPO_ROOT}/scripts/smoke.sh"
+fi
+
+echo "youaskm3 real shell validation passed."