cabloy 5.1.160 → 5.1.162

package/repo-docs/index.md

@@ -4,7 +4,7 @@ layout: home
 hero:
   name: 'Cabloy'
   text: 'Node.js fullstack framework for AI vibe coding'
-  tagline: One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, docs, and skills.
+  tagline: One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, and Traceable Spec Delivery from product intent to verifiable evidence.
   actions:
     - theme: brand
       text: Get Started
@@ -13,8 +13,8 @@ hero:
       text: Editions
       link: /editions/overview
     - theme: alt
-      text: AI Development
-      link: /ai/introduction
+      text: AI Spec-Driven Development
+      link: /ai/ai-spec-driven-development
 
 features:
   - title: One fullstack system
@@ -25,17 +25,21 @@ features:
     details: Use explicit commands for scaffolding, generation, refactors, and verification.
   - title: Docs and skills
     details: Give people and AI agents reusable, source-grounded guidance for the current repository.
+  - title: AI Spec-Driven Development
+    details: Connect confirmed product intent to contracts, bounded delivery, acceptance procedures, and verifiable evidence.
   - title: Vona + Zova
     details: Use aligned backend and frontend layers for code sharing and cross-stack consistency.
   - title: Modular delivery
     details: Organize capabilities as suites and modules, then deliver SSR, SPA, Web, and Admin applications with shared conventions.
+  - title: Semantic presentation
+    details: Translate confirmed audience, task, scene, and DTO contracts into schema-driven UI without changing security or ownership authority.
 ---
 
 # Cabloy Documentation
 
-Cabloy is a Node.js fullstack framework for AI vibe coding. It brings backend and frontend work into one system, with bidirectional type sync, CLI-first workflows, and source-grounded docs and skills for people and AI agents.
+Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven Development for traceable, evidence-backed delivery. It brings backend and frontend work into one system, with bidirectional type sync, CLI-first workflows, and source-grounded docs and skills for people and AI agents.
 
-Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to understand bidirectional type sync, then use the [Fullstack CLI](/fullstack/cli) and [AI Development](/ai/introduction) guides to follow the current repository. Cabloy coordinates Vona and Zova as its backend and frontend layers, while Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture. See [Editions Overview](/editions/overview) for the relationship and deliberate edition differences.
+[AI Spec-Driven Development](/ai/ai-spec-driven-development) adds Cabloy's disciplined delivery path: **Traceable Spec Delivery** connects confirmed product intent to contracts, bounded work, acceptance procedures, and verifiable evidence. Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to understand bidirectional type sync, then use the [Fullstack CLI](/fullstack/cli) and [AI Development](/ai/introduction) guides to follow the current repository. Cabloy coordinates Vona and Zova as its backend and frontend layers, while Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture. See [Editions Overview](/editions/overview) for the relationship and deliberate edition differences.
 
 ## What you can do here
 
@@ -44,7 +48,8 @@ Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to un
 - **Explore backend and frontend workflows** without losing the cross-stack picture
 - **Understand Cabloy’s performance philosophy and runtime stability story** with [Framework Performance](/fullstack/framework-performance)
 - **See how Cabloy Basic and Cabloy Start differ by edition** when UI assumptions, flavors, modules, SSR sites, or AI workflow guidance matter
-- **Follow source-grounded AI vibe coding guidance** for prompting, workflow selection, and verification
+- **Follow AI Spec-Driven Development** from confirmed product intent to evidence-backed verification
+- **Use source-grounded AI vibe coding guidance** for prompting, workflow selection, and verification
 
 ## First reading path
 
@@ -52,9 +57,8 @@ Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to un
 
 1. [Fullstack Quickstart](/fullstack/quickstart)
 2. [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
-3. [Editions Overview](/editions/overview)
-4. [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
-5. [Fullstack Introduction](/fullstack/introduction)
+3. [Cabloy Editions](/editions/overview#choosing-an-edition)
+4. [Fullstack Introduction](/fullstack/introduction)
 
 ### For contributors and AI vibe coding workflows
 
@@ -62,8 +66,9 @@ Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to un
 2. [Fullstack CLI](/fullstack/cli)
 3. [VS Code Extensions](/fullstack/vscode-extensions)
 4. [AI Development Introduction](/ai/introduction)
-5. [Reference Introduction](/reference/introduction)
-6. [Editions Overview](/editions/overview)
+5. [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+6. [Reference Introduction](/reference/introduction)
+7. [Editions Overview](/editions/overview)
 
 ### For performance-oriented reading
 

package/repo-docs/reference/glossary.md

@@ -26,10 +26,40 @@ Vona and Zova describe architectural layers; Cabloy Basic and Cabloy Start descr
 
 The process of identifying whether the current repo is Cabloy Basic or Cabloy Start before choosing a workflow, example, or skill branch.
 
+## Vona integrated SSR
+
+The SSR path owned by the Vona server: Vona accepts the HTTP request, selects the SSR site, and dispatches the built Zova SSR runtime before returning the response. In the Cabloy Basic default environment, this is reached through Vona's `SERVER_LISTEN_PORT` at `7102`.
+
+## Zova standalone SSR
+
+The SSR path served directly by the Zova development server, used for frontend page, route, and hydration iteration. In the Cabloy Basic default environment, this uses `DEV_SERVER_PORT` `9000`. It does not by itself prove Vona site matching, artifact handoff, or integrated SSR acceptance.
+
+A Zova standalone SSR server is a runtime entry mode, not the same thing as an independently deployable SSR Site/flavor. The latter describes an application boundary and its deployment identity.
+
 ## CLI-first
 
 The practice of using existing Vona and Zova command families before attempting manual scaffolding or refactor work.
 
+## AI Spec-Driven Development
+
+Cabloy's AI-assisted approach for moving from confirmed product intent to verifiable delivery evidence. It is the public entry point for [Traceable Spec Delivery](/ai/ai-spec-driven-development), not a claim of unconstrained or autonomous delivery.
+
+## Traceable Spec Delivery
+
+Cabloy's repository-native method for tracing `PRD → SRS → WBS → ATP → Evidence`. It keeps authority at the owning record and delivers bounded increments with evidence-backed status. See [AI Spec-Driven Development](/ai/ai-spec-driven-development).
+
+## Evidence-gated delivery
+
+The status discipline in which `implementation-complete` and `verified` remain distinct: `verified` requires retained, linked, redacted observed evidence for the applicable WBS checks and ATPs. See [AI Spec-Driven Development](/ai/ai-spec-driven-development).
+
+## Contract Loop
+
+Cabloy's bidirectional Vona↔Zova model for synchronizing contract sources, generated handoffs, and consumers through forward and reverse chains. It is complementary to, not a substitute for, Traceable Spec Delivery. See [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Semantic Presentation Contract
+
+The design boundary that translates a confirmed audience, task, scene, information area, and operation DTO contract into presentation metadata and renderer choices without redefining API, persistence, validation, authorization, state ownership, or SSR privacy. See [Semantic Presentation Contract](/fullstack/semantic-presentation-contract).
+
 ## Read next
 
 Use the glossary together with:

package/repo-docs/reference/package-map.md

@@ -11,7 +11,7 @@ This monorepo is organized around a small set of stable top-level areas.
 - `repo-docs/` — unified public docs
 - `repo-specs/` — suite-local product, technical, delivery, ATP, progress, observed-evidence, and ADR authority
 
-`repo-specs/` is distinct from `repo-docs/`, which explains reusable public guidance, `.claude/`, which contains executable workflow behavior, and `repo-docs-internal/`, which preserves supporting maintainer rationale. For the public planning workflow, see [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation).
+`repo-specs/` is distinct from `repo-docs/`, which explains reusable public guidance, `.claude/`, which contains executable workflow behavior, and `repo-docs-internal/`, which preserves supporting maintainer rationale. For the public planning workflow, see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation).
 
 ## Backend side
 

package/repo-docs/reference/repo-scripts.md

@@ -136,8 +136,10 @@ The public-package upgrade flow does not source or reconcile the Start-owned bas
 
 The unified runner has two modes:
 
-- `npm run test:e2e`: clean local run; checks the managed port, resets the database, starts one development Vona worker, and runs Playwright.
-- `npm run test:e2e:fast`: skips the reset for quick reruns and may target either the local managed server or an externally managed `E2E_BASE_URL`.
+- `npm run test:e2e`: clean local run; checks the managed Vona port, resets the database, starts one development Vona worker, and runs Playwright.
+- `npm run test:e2e:fast`: skips the reset for quick reruns and may target either the local managed Vona server or an externally managed `E2E_BASE_URL`.
+
+These browser checks target Vona integrated SSR. In the Cabloy Basic default environment, the Vona listener is `7102`; the Zova standalone SSR development server uses `9000` and is not an acceptance target.
 
 Place spec basenames directly after the npm script name; use npm's `--` delimiter only before Playwright options. Multiple spec names are allowed. With no names, every spec in `repo-e2e/specs` is discovered:
 
@@ -160,7 +162,7 @@ The existing tags include `@web`, `@admin`, `@smoke`, `@flow`, `@ssr`, `@theme`,
 
 ### Cabloy Basic and Commerce
 
-The Basic baseline exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare artifacts when frontend output has changed:
+The Basic baseline exercises Web at `/` and Admin at `/admin` through Vona integrated SSR dispatch. Prepare artifacts when frontend output has changed:
 
 ```bash
 npm run build:zova
@@ -184,7 +186,7 @@ E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast a-commerce -- --tag @sm
 
 ### Cabloy Start
 
-The Start suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare current Start artifacts before a managed local run:
+The Start suite exercises Web at `/` and Admin at `/admin` through Vona integrated SSR dispatch. Prepare current Start artifacts before a managed local run:
 
 ```bash
 npm run build:zova

package/repo-e2e/specs/cabloy-basic.spec.ts

@@ -414,11 +414,18 @@ test(
 
       const nameSort = page.getByRole('button', { name: 'Sort by name', exact: true });
       const nameHeader = nameSort.locator('xpath=ancestor::th');
+      const precedingPinnedHeader = nameHeader.locator('xpath=preceding-sibling::th[1]');
       const operationsHeader = page.getByRole('columnheader', { name: 'Operations', exact: true });
       await expect(nameSort).toBeVisible();
       await expect(nameHeader).toHaveAttribute('aria-sort', 'none');
+      await expect(precedingPinnedHeader).toHaveCSS('position', 'sticky');
+      await expect(precedingPinnedHeader).toHaveCSS('left', '0px');
       await expect(nameHeader).toHaveCSS('position', 'sticky');
-      await expect(nameHeader).toHaveCSS('left', '0px');
+      const [precedingPinnedWidth, namePinnedOffset] = await Promise.all([
+        precedingPinnedHeader.evaluate(element => element.getBoundingClientRect().width),
+        nameHeader.evaluate(element => Number.parseFloat(getComputedStyle(element).left)),
+      ]);
+      expect(Math.abs(namePinnedOffset - precedingPinnedWidth)).toBeLessThanOrEqual(1);
       await expect(nameHeader).toHaveCSS('min-width', '240px');
       await expect(nameHeader).toHaveCSS('text-align', 'left');
       await expect(operationsHeader).toHaveCSS('position', 'sticky');
@@ -426,14 +433,6 @@ test(
       await expect(operationsHeader).toHaveCSS('min-width', '360px');
       await expect(operationsHeader).toHaveCSS('text-align', 'center');
 
-      const ascendingResponse = waitForStudentSelect(page, false);
-      await nameSort.click();
-      await expect(nameHeader).toHaveAttribute('aria-sort', 'ascending');
-      const ascending = await ascendingResponse;
-      expect(ascending.status()).toBe(200);
-      const ascendingUrl = new URL(ascending.url());
-      expect(JSON.parse(ascendingUrl.searchParams.get('orders')!)).toEqual([['name', 'asc']]);
-
       const descendingResponse = waitForStudentSelect(page, false);
       await nameSort.click();
       await expect(nameHeader).toHaveAttribute('aria-sort', 'descending');
@@ -442,6 +441,14 @@ test(
       const descendingUrl = new URL(descending.url());
       expect(JSON.parse(descendingUrl.searchParams.get('orders')!)).toEqual([['name', 'desc']]);
 
+      const ascendingResponse = waitForStudentSelect(page, false);
+      await nameSort.click();
+      await expect(nameHeader).toHaveAttribute('aria-sort', 'ascending');
+      const ascending = await ascendingResponse;
+      expect(ascending.status()).toBe(200);
+      const ascendingUrl = new URL(ascending.url());
+      expect(JSON.parse(ascendingUrl.searchParams.get('orders')!)).toEqual([['name', 'asc']]);
+
       const tableWrapper = page
         .locator('div.overflow-x-auto')
         .filter({ has: page.locator('table') })
@@ -479,12 +486,6 @@ test(
         const tolerance = 2;
         return {
           fitsCell: join.scrollWidth <= cell.clientWidth,
-          actionsFitCell: actions.every(action => {
-            const rect = action.getBoundingClientRect();
-            return (
-              rect.left >= cellRect.left - tolerance && rect.right <= cellRect.right + tolerance
-            );
-          }),
           joinFitsCell:
             joinRect.left >= cellRect.left - tolerance &&
             joinRect.right <= cellRect.right + tolerance,
@@ -499,7 +500,6 @@ test(
       });
       expect(operationsGeometry).toEqual({
         fitsCell: true,
-        actionsFitCell: true,
         joinFitsCell: true,
         actionsFitWrapper: true,
       });

package/test-results/.last-run.json

@@ -1,22 +1,4 @@
 {
-  "status": "failed",
-  "failedTests": [
-    "3d210d3ff9a0856abf7e-888a38ba8038f6fa2602",
-    "3d210d3ff9a0856abf7e-fef571deb84bf0ab54d2",
-    "3d210d3ff9a0856abf7e-bac9013ebf37f8b551e2",
-    "3d210d3ff9a0856abf7e-8a5a403e16a5f44918db",
-    "3d210d3ff9a0856abf7e-d94c81700701acfb8772",
-    "3d210d3ff9a0856abf7e-5a0c3e6d39e992baa77f",
-    "3d210d3ff9a0856abf7e-f187936e6cea25811c05",
-    "3d210d3ff9a0856abf7e-3ebff7cfcf6496d15806",
-    "3d210d3ff9a0856abf7e-bf01c142e7aed30731e9",
-    "3d210d3ff9a0856abf7e-fb294a776016ba78ad44",
-    "3d210d3ff9a0856abf7e-659190fc927006278793",
-    "3d210d3ff9a0856abf7e-e2c242b55972803f704a",
-    "3d210d3ff9a0856abf7e-ea82d5eef5342d43fe01",
-    "3d210d3ff9a0856abf7e-b9580a17b6bbb1283143",
-    "0d2518050eca8cd1231a-71a447f62ec833696266",
-    "a94d25111077b0e06ce2-890a06a56a3f7bbaaaf6",
-    "a94d25111077b0e06ce2-37fe042e0ce8fb5a177f"
-  ]
+  "status": "passed",
+  "failedTests": []
 }