cabloy 5.1.152 → 5.1.153

package/.cabloy-version

@@ -1 +1 @@
-5.1.152
+5.1.153

package/.claude/skills/cabloy-module-removal/SKILL.md

@@ -129,7 +129,7 @@ Ask or confirm whether the task is:
 - code/runtime removal only
 - code/runtime removal plus docs/examples scrub
 
-If docs cleanup is in scope, update `repo-docs/` separately from the runtime cleanup. When an established `repo-docs-internal/` home exists, keep maintainer rationale there; otherwise do not create or require that path as part of module removal.
+If docs cleanup is in scope, update `repo-docs/` separately from the runtime cleanup. Keep maintainer rationale in `repo-docs-internal/`; do not require a particular internal record as part of module removal.
 
 ## Response pattern
 

package/.claude/skills/cabloy-resource-field-update/SKILL.md

@@ -217,7 +217,7 @@ Use these portable references:
 - `references/custom-renderer-demo-checklist.md`
 - [Existing Resource Field Update](../../../repo-docs/backend/resource-field-update.md)
 
-When an active repository provides `repo-docs-internal/architecture/backend-resource-field-workflow.md`, it may be consulted as optional maintainer rationale. Its absence must not block or alter this shared workflow.
+When relevant and available in the active edition, `repo-docs-internal/architecture/backend-resource-field-workflow.md` may be consulted as optional maintainer rationale. Its absence must not block or alter this shared workflow.
 
 Recommended shape:
 

package/.claude/skills/cabloy-spec-generation/SKILL.md

@@ -173,7 +173,7 @@ Optional records remain subordinate to the PRD/SRS/WBS/test-plan authority appro
 
 While drafting, preserve these principles and tailor them to confirmed scope:
 
-- `repo-specs/` is the product/business planning home; `repo-docs/` is public and agent-facing framework guidance; an established `repo-docs-internal/` home may hold cross-suite maintainer rationale; `.claude/skills/` is workflow behavior; do not assume or create an internal-docs home in an edition that lacks one;
+- `repo-specs/` is the product/business planning home; `repo-docs/` is public and agent-facing framework guidance; `repo-docs-internal/` holds supporting cross-suite maintainer rationale; `.claude/skills/` is workflow behavior; do not assume a particular internal record exists in every edition;
 - use suite-first ownership and distinguish new domain modules from reusable framework modules; do not duplicate an existing persistence or identity owner without a stated decision;
 - treat the active Vona instance as the tenant by default; do not introduce a store, organization, or merchant entity unless the confirmed domain contract requires it;
 - make identity, tenant scope, authorization, and ownership server-authoritative; menus, routes, browser filters, and UI visibility are not API authorization;

package/.claude/skills/cabloy-spec-generation/references/repo-aware-discovery.md

@@ -82,7 +82,7 @@ Hand actual implementation-time synchronization to `cabloy-contract-loop`.
 | --- | --- |
 | Product requirements, SRS contracts, WBS, ATPs, suite ADRs, delivery status | `repo-specs/<suite>/` |
 | Reusable user-facing or agent-facing framework guidance | `repo-docs/` |
-| Cross-suite maintainer architecture, rationale, and engineering ADRs | An established internal-documentation home, when present; do not create one implicitly |
+| Cross-suite maintainer architecture, rationale, and engineering ADRs | `repo-docs-internal/`; individual records may vary by edition |
 | Short durable AI operating rules | `CLAUDE.md` |
 | Reusable Claude procedure | `.claude/skills/` |
 

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cabloy-workflow
-description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as repo-docs, an established internal-docs home when present, CLAUDE.md, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
+description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as repo-docs, repo-docs-internal, CLAUDE.md, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
 ---
 
 # Cabloy Workflow
@@ -31,13 +31,12 @@ Interpretation:
 
 This matters most for frontend work, UI-layer assumptions, flavor names, suite/module availability, SSR site baselines, project assets, and edition-specific AI guidance.
 
-Repository-path availability is independent of edition detection:
+Documentation-root policy is independent of edition detection:
 
-- inspect a documentation path before recommending or reading it
-- use `repo-docs-internal/` only when an established active-repository home exists
-- treat edition-local internal notes as optional maintainer material, never as a prerequisite for shared workflow routing
-- when an optional path is absent, continue from public docs, bundled skill references, active source, and tests
-- do not create a missing documentation home unless the user explicitly asks to establish one
+- `repo-docs-internal/` is the internal documentation home in Cabloy Basic and Cabloy Start
+- inspect a specific internal record before recommending or reading it
+- treat relevant edition-local internal records as supporting maintainer material, never as a prerequisite for shared workflow routing
+- when a specific record is unavailable or irrelevant, continue from public docs, bundled skill references, active source, and tests
 
 ## Step 2: Identify the task layer
 
@@ -79,7 +78,7 @@ Use the frontend path when the task is about:
 Use the docs/AI path when the task is about:
 
 - `repo-docs/`
-- an established `repo-docs-internal/` home when present
+- `repo-docs-internal/`
 - `CLAUDE.md`
 - `.claude/commands/`
 - `.claude/skills/`
@@ -94,7 +93,7 @@ Before inventing a workflow, inspect these shared surfaces:
 - `npm run zova`
 - root `CLAUDE.md` if present
 - `repo-docs/` for public guidance
-- an established `repo-docs-internal/` home for optional maintainer rationale
+- `repo-docs-internal/` for supporting maintainer rationale
 
 If the request spans backend and frontend, classify it as fullstack by default unless the user clearly wants only one side.
 
@@ -167,16 +166,16 @@ Use `repo-docs/` for:
 - reusable AI-facing workflow guidance
 - edition-aware public documentation
 
-### Optional internal engineering docs
+### `repo-docs-internal/`
 
-When an established `repo-docs-internal/` home exists, it may be used for:
+Use `repo-docs-internal/` for:
 
 - ADRs
 - architecture notes
 - maintainer rationale
 - invariants and design boundaries
 
-Its absence must not block routing or implementation, and it must not be assumed to exist in every checkout.
+Relevant internal records support routing and implementation but do not block them: shared public guidance remains complete, and individual records may be unavailable or irrelevant in the active edition.
 
 ### Root rules and commands
 
@@ -208,7 +207,7 @@ When the request is about whether a backend base class belongs in `src/lib`, `sr
 For these requests:
 
 - put the durable operational explanation in `repo-docs/`
-- when an established internal-docs home exists, put rationale and invariants there; otherwise preserve the public operational explanation and ask before establishing a new maintainer-rationale home
+- put supporting rationale and invariants in `repo-docs-internal/`; preserve the public operational explanation when a particular internal record is unavailable or irrelevant
 - keep `CLAUDE.md` short and behavioral
 - do not treat `@Service()` as a business-layer naming decision only; for B2 it is a runtime-anchor placement choice
 
@@ -287,7 +286,7 @@ Verify:
 
 - referenced paths exist
 - command names still exist
-- public docs, optional internal rationale, and rules tell a consistent story
+- public docs, `repo-docs-internal/` rationale, and rules tell a consistent story
 - edition-specific notes point to the right repo assumptions
 
 ### For backend/frontend workflow changes

package/.claude/skills/cabloy-workflow/evals/evals.json

@@ -15,8 +15,8 @@
     },
     {
       "id": 3,
-      "prompt": "Please help me decide whether this new AI guidance belongs in public docs, an internal-docs home when present, CLAUDE.md, or a skill. The guidance is about when to use npm run zova instead of hand-written scaffolding.",
-      "expected_output": "Routes shared operational guidance to public docs and Claude rules/skills as appropriate, treats an internal-docs home as optional maintainer material rather than an assumed requirement, and reinforces the CLI-first principle.",
+      "prompt": "Please help me decide whether this new AI guidance belongs in public docs, repo-docs-internal, CLAUDE.md, or a skill. The guidance is about when to use npm run zova instead of hand-written scaffolding.",
+      "expected_output": "Routes shared operational guidance to public docs and Claude rules/skills as appropriate, routes supporting maintainer rationale to repo-docs-internal, and reinforces the CLI-first principle without making an individual internal record a requirement.",
       "files": []
     },
     {
@@ -51,8 +51,8 @@
     },
     {
       "id": 9,
-      "prompt": "I am in a Cabloy checkout whose active repository currently has no repo-docs-internal directory. I need shared agent guidance and some maintainer rationale. Where should each part go?",
-      "expected_output": "Inspects the active repository path rather than making an edition-wide assumption, routes shared operational guidance to existing public docs and Claude rules or skills, and asks which established maintainer-rationale home to use rather than putting rationale into public docs automatically.",
+      "prompt": "I am in a Cabloy checkout where repo-docs-internal exists, but the named architecture record I expected is not available in this edition. I need shared agent guidance and some maintainer rationale. Where should each part go?",
+      "expected_output": "Recognizes repo-docs-internal as the internal documentation home, routes shared operational guidance to public docs and Claude rules or skills, and treats the missing named record as non-blocking rather than inventing a replacement or moving rationale into public docs automatically.",
       "files": []
     }
   ]

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.1.153
+
+### Features
+
+- Add an option to disable Suspense during initialization.
+- Add support for bypassing the persister.
+
+### Improvements
+
+- Update table cell action summary handling.
+- Improve query summary Suspense documentation.
+- Update state data best-practices documentation.
+- Enhance internal repository documentation and specification-generation guidance.
+
 ## 5.1.152
 
 ### Improvements

package/CLAUDE.md

@@ -17,7 +17,7 @@ Always perform this detection before making UI-sensitive assumptions, choosing f
 - `vona/` contains the backend framework, backend modules, and the Vona CLI.
 - `zova/` contains the frontend framework, frontend modules, and the Zova CLI.
 - `repo-docs/` contains the unified public documentation.
-- `repo-docs-internal/`, when present, contains edition-local maintainer notes and ADRs; treat it as optional supporting material, not as a shared-edition requirement.
+- `repo-docs-internal/` contains edition-local maintainer notes and ADRs; treat relevant records as supporting material, not as a shared-edition requirement.
 - `repo-specs/` contains product and business specifications, delivery plans, and suite-local ADRs.
 - `repo-e2e/` contains the end-to-end test project.
 - `repo-observability/` contains local observability infrastructure.
@@ -38,8 +38,7 @@ Before inventing a custom implementation path:
 ## Documentation boundary
 
 - Put user-facing and agent-facing guidance in `repo-docs/`.
-- When an established `repo-docs-internal/` home exists, use it for maintainer rationale, architecture notes, and engineering ADRs. Do not infer or create that path from edition identity alone.
-- If the active repository has no established internal-documentation home, do not block the workflow or move internal rationale into public docs automatically; use existing documentation homes or ask before establishing one.
+- Put maintainer rationale, architecture notes, and engineering ADRs in `repo-docs-internal/`. Treat relevant records as supporting material: shared workflows remain complete without any particular internal record, which may vary by edition.
 - Put product and business specifications, delivery plans, acceptance records, and suite-local ADRs in `repo-specs/` when that repository surface exists.
 - Do not mix internal rationale into public how-to pages unless a trimmed user-facing explanation is genuinely needed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.152",
+  "version": "5.1.153",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/.vitepress/config.mjs

@@ -23,6 +23,11 @@ const aiItems = [
   { text: 'Playbook: Backend Module', link: '/ai/playbook-backend-module' },
   { text: 'Playbook: Frontend Page', link: '/ai/playbook-frontend-page' },
   { text: 'Playbook: Contract Regeneration', link: '/ai/playbook-contract-regeneration' },
+  { text: 'Playbook: Plan a Suite Specification', link: '/ai/playbook-spec-generation' },
+  {
+    text: 'Playbook: Execute an Approved Specification Increment',
+    link: '/ai/playbook-spec-execution',
+  },
   { text: 'Playbook: Module Removal', link: '/ai/playbook-module-removal' },
   { text: 'Playbook: Metadata Refresh', link: '/ai/playbook-metadata-refresh' },
   { text: 'Playbook: Technical Blog Authoring', link: '/ai/playbook-technical-blog-authoring' },

package/repo-docs/ai/cli-to-skill-map.md

@@ -122,6 +122,25 @@ Typical skill role:
 
 - notice when route/component/icon changes require metadata regeneration
 
+## Repository planning and derived-chart scripts
+
+Not every skill maps to a Vona or Zova generator. Repository-native suite specifications are authored under `repo-specs/`; no CLI generates the complete planning authority set.
+
+In the current Cabloy Basic repository, these root scripts refresh and check derived planning views:
+
+```bash
+npm run spec:charts -- <suite>
+npm run spec:charts:check -- <suite>
+```
+
+They generate or validate the Gantt and burndown SVGs from authoritative planning records. They do not replace PRD/SRS/WBS/ATP updates, implement a WBS task, execute an ATP, or create evidence. Confirm scripts in the active repository before using them for another edition.
+
+Typical skill roles:
+
+- `cabloy-spec-generation` creates or updates planning authority only after confirmation, then refreshes derived charts after relevant record changes
+- `cabloy-spec-execution` coordinates one approved increment, records evidence before derived progress, then refreshes and checks charts
+- source implementation remains routed to Vona, Zova, contract-loop, or other specialist workflows
+
 ## Example mappings
 
 ### Example: “Create a student CRUD backend thread”

package/repo-docs/ai/docs-skills-rules-mapping.md

@@ -38,11 +38,11 @@ Public docs answer questions like:
 - how does Zova page or model architecture work?
 - what is different between Cabloy Basic and Cabloy Start?
 
-### 2. Optional internal engineering docs
+### 2. Internal engineering docs
 
 Location:
 
-- an established internal-documentation home, when the active repository provides one
+- `repo-docs-internal/`
 
 Use internal docs for:
 
@@ -51,7 +51,7 @@ Use internal docs for:
 - maintenance boundaries
 - “why this design exists” notes that do not belong in public user docs
 
-When available, internal docs answer questions like:
+Relevant internal records answer questions like:
 
 - why were docs and internal notes separated?
 - why is AI enablement structured this way?
@@ -105,7 +105,7 @@ Skills answer questions like:
 Use this quick rule:
 
 - if people and agents both need to read and understand it, put it in **public docs**
-- if it is maintainer rationale or long-lived design history, use an established internal-documentation home when one exists; otherwise ask before establishing one
+- if it is maintainer rationale or long-lived design history, use `repo-docs-internal/`; shared guidance remains complete without any particular internal record
 - if it is short repo-wide behavioral guidance, put it in **CLAUDE.md**
 - if it is a named repeatable operator action, put it in a **command**
 - if it is a reusable procedural workflow with branching, put it in a **skill**
@@ -128,7 +128,7 @@ Use this quick rule:
 ### Example: “How should a backend base class be placed?”
 
 - public operational explanation → [Class Placement Rule](/ai/class-placement-rule)
-- maintainer rationale and invariants → an established internal-documentation home, when available
+- maintainer rationale and invariants → `repo-docs-internal/`
 - default repo-wide behavior → `CLAUDE.md`
 - procedural decision workflow → `cabloy-workflow` skill
 
@@ -153,7 +153,7 @@ Use this quick rule:
 ### Example: “How should AI remove an existing module cleanly?”
 
 - public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)
-- maintainer rationale and pitfalls → an established internal-documentation home, when available
+- maintainer rationale and pitfalls → `repo-docs-internal/`
 - avoid putting the full workflow in `CLAUDE.md` because the task needs branching, cleanup order, generated-runtime recovery, and verification
 - procedural decision workflow → `cabloy-module-removal` skill
 
@@ -165,6 +165,21 @@ Use this quick rule:
 - avoid putting the full branching workflow in `CLAUDE.md` because the task needs proposal, validation, confirmation, and CLI handoff
 - procedural decision workflow → `cabloy-domain-planning` skill
 
+### Example: “How should AI create or maintain a repository-native suite specification?”
+
+- public workflow explanation → [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- procedural planning, confirmation, traceability, and chart-refresh behavior → `cabloy-spec-generation`
+- suite-specific PRD, SRS, WBS, ATP, ADR, progress, and observed evidence authority → `repo-specs/<suite>/`
+- maintainer rationale → `repo-docs-internal/`
+- implementation is not implied by creating planning records
+
+### Example: “How should AI deliver an approved suite task?”
+
+- public workflow explanation → [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- bounded-WBS coordination, readiness gates, evidence, and derived-status behavior → `cabloy-spec-execution`
+- source implementation → the relevant backend, frontend, contract-loop, or shape-specific skill
+- product, contract, dependency, scope, or durable-decision changes → return to specification or domain planning
+
 ### Example: “What `@Api.field(...)` ordering rule should AI preserve when mixing helpers and zod?”
 
 - full explanation → [Entity Guide](/backend/entity-guide) and [DTO Guide](/backend/dto-guide)

package/repo-docs/ai/future-skill-roadmap.md

@@ -14,94 +14,39 @@ Current root skills include:
 
 - `cabloy-workflow`
 - `cabloy-domain-planning`
+- `cabloy-spec-generation`
+- `cabloy-spec-execution`
+- `cabloy-backend-scaffold`
+- `cabloy-frontend-scaffold`
 - `cabloy-contract-loop`
 - `cabloy-resource-field-update`
 - `cabloy-module-removal`
+- `cabloy-master-detail`
+- `cabloy-worktree-environment`
+- `cabloy-zova-source-reading`
 
 Their current roles are:
 
 - `cabloy-workflow` → broad workflow selection, edition detection, CLI-first routing, and verification framing
 - `cabloy-domain-planning` → suite-first naming proposals, providerId confirmation, module-boundary suggestions, and scaffold handoff for new business domains
+- `cabloy-spec-generation` → repository-native suite planning authority, traceability, confirmation, and derived planning views
+- `cabloy-spec-execution` → one approved WBS increment through readiness gates, specialist routing, evidence, and derived status
+- `cabloy-backend-scaffold` → Vona implementation routing and CLI-backed backend scaffolding
+- `cabloy-frontend-scaffold` → Zova implementation routing and CLI-backed frontend scaffolding
 - `cabloy-contract-loop` → backend/frontend contract regeneration, reverse-chain handling, and drift diagnosis
 - `cabloy-resource-field-update` → existing backend resource-field changes with `fileVersion` and renderer-aware follow-up
 - `cabloy-module-removal` → backend/frontend/fullstack module deletion order, generated-runtime cleanup, and verification
+- `cabloy-master-detail` → coordinated master-detail resource workflow
+- `cabloy-worktree-environment` → confirmed worktree-local environment tuple setup for intentional parallel work
+- `cabloy-zova-source-reading` → Zova-first source reading and Vue comparison workflow
 
 This is now a stronger foundation skill set, but it still leaves several useful workflow families for future specialization.
 
 ## Recommended next skill families
 
-### 1. Backend scaffold skill
+The backend scaffold, frontend scaffold, contract-loop, resource-field-update, and metadata-refresh workflow families already have implemented specialist coverage. Future work should refine those skills only when a new repository-wide branch or stable verification need emerges.
 
-Purpose:
-
-- scaffold Vona controller/service/model/entity/dto/CRUD threads
-- choose between bean creation and CRUD generation
-- verify migration/test implications
-
-Primary dependencies:
-
-- Vona `create:*`
-- Vona `tools:*`
-- backend docs in `repo-docs/backend/`
-
-### 2. Frontend scaffold skill
-
-Purpose:
-
-- scaffold Zova pages/components/API/models
-- branch correctly between Basic and Start
-- use create/refactor commands before manual edits
-
-Primary dependencies:
-
-- Zova `create:*`
-- Zova `refactor:*`
-- frontend docs in `repo-docs/frontend/`
-
-### 3. Fullstack contract loop skill
-
-Purpose:
-
-- detect backend contract changes
-- regenerate OpenAPI/SDK-related output
-- verify backend/frontend contract alignment
-
-Primary dependencies:
-
-- Vona OpenAPI and validation docs
-- Zova OpenAPI SDK and server-data docs
-- fullstack collaboration docs
-
-### 4. Resource field update skill
-
-Purpose:
-
-- handle updates to fields on existing backend resources
-- force the right `fileVersion` decision for new persisted fields
-- branch correctly between shared renderer reuse and custom renderer demo follow-up
-- verify entity, locale, migration, test, metadata, build, and dependency-sync implications
-
-Primary dependencies:
-
-- Vona entity / migration / DTO workflow knowledge
-- Zova metadata/build flows when renderer follow-up is involved
-- [Existing Resource Field Update](/backend/resource-field-update)
-
-### 5. Metadata refresh skill
-
-Purpose:
-
-- detect when route/component/icon or related changes require metadata regeneration
-- run the right metadata flow
-- verify generated artifacts belong to the active edition
-
-Primary dependencies:
-
-- Zova `tools:*`
-- CLI-to-skill mapping
-- edition detection docs
-
-### 6. Distributed backend workflow skill
+### 1. Distributed backend workflow skill
 
 Purpose:
 
@@ -148,7 +93,7 @@ The purpose is to create a small number of high-leverage skills that directly re
 
 - `repo-docs/`
 - `CLAUDE.md`
-- an established internal-documentation home, when present
+- `repo-docs-internal/`
 - `.claude/skills/`
 - the Vona and Zova CLIs
 

package/repo-docs/ai/introduction.md

@@ -8,7 +8,7 @@ The Cabloy monorepo is a good fit for AI vibe coding because the source tree alr
 - Vona CLI source and command groups
 - Zova CLI source and command groups
 - archived docs that still capture valuable concepts
-- optional internal engineering docs for maintainers when the active repository provides them
+- `repo-docs-internal/` engineering docs for maintainers
 - Claude commands and skills
 
 ## The main design goal
@@ -20,7 +20,7 @@ The goal is to make AI **reuse the repo’s existing conventions directly**, esp
 - CLI commands
 - root scripts
 - repo markers
-- optional internal architecture notes when the active repository provides them
+- relevant `repo-docs-internal/` architecture notes
 - shared public documentation
 
 ## How to approach AI work
@@ -29,7 +29,7 @@ For contributor and automation workflows in this repository, prefer this order:
 
 1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
 2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
-3. use public docs for durable user-facing and agent-facing guidance; consult an established internal-documentation home only when the active repository provides one for maintainer rationale
+3. use public docs for durable user-facing and agent-facing guidance; consult relevant `repo-docs-internal/` records for supporting maintainer rationale
 4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
 
 ## The knowledge layers
@@ -40,9 +40,9 @@ Use `repo-docs/` for user-facing and agent-facing guidance that should remain du
 
 For normal project usage, prefer the user-facing entry docs such as [Fullstack Quickstart](/fullstack/quickstart). This AI section focuses on repository workflows and AI vibe coding.
 
-### Optional internal engineering docs
+### `repo-docs-internal/` engineering docs
 
-When an established internal-documentation home exists, use it for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Its absence must not block a shared workflow or cause internal rationale to be moved into public how-to documentation automatically.
+Use `repo-docs-internal/` for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Relevant records support a shared workflow without being prerequisites; an unavailable or irrelevant individual record must not cause its rationale to be moved into public how-to documentation automatically.
 
 ### Claude rules and commands
 
@@ -66,6 +66,16 @@ Start here when the task is about choosing the right repo surface, docs location
 - [Skills](/ai/skills)
 - [Rules and Config](/ai/rules-and-config)
 
+### Specification planning and delivery path
+
+Use this path to establish suite authority before implementation, then deliver one approved, bounded WBS increment with evidence-backed status:
+
+- [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- [Skills](/ai/skills)
+- [Repo Scripts](/reference/repo-scripts)
+- [Verification](/ai/verification)
+
 ### Framework implementation path
 
 Use this path when the task is about implementing or reviewing Cabloy code with repo-aware rules:

package/repo-docs/ai/playbook-spec-execution.md

@@ -0,0 +1,144 @@
+# Playbook: Execute an Approved Cabloy Specification Increment
+
+Use this playbook to deliver one approved Cabloy specification increment from a bounded WBS item through implementation, scoped verification, retained evidence, and an accurate progress handoff.
+
+The `cabloy-spec-execution` skill is a control plane. It coordinates an approved increment and its specialist workflow; it is not a second product authority, architecture authority, or code generator.
+
+## When to use this playbook
+
+Use `cabloy-spec-execution` when you need to:
+
+- implement one named `WBS-*` item
+- execute an explicitly named, finite, approved phase with a defined closure boundary
+- verify or close a named ATP or release-gate task
+- turn one existing suite-plan increment into implementation and observed proof
+
+Requests such as “implement the suite,” “finish all specs,” or “do the next phase” are not bounded enough. Select one WBS task, or explicitly approve a finite task list and its closure boundary, before implementation begins.
+
+Use [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) instead when the task changes a requirement, contract, dependency, scope boundary, or durable decision.
+
+## Establish the execution boundary first
+
+Start by inspecting the active repository, edition marker, current revision, and working-tree state. Then build an execution dossier for the selected increment.
+
+The dossier identifies:
+
+- suite, edition, target WBS ID or approved finite task list, and closure boundary
+- linked PRD, SRS, ADR, ATP, progress, and evidence records
+- predecessor tasks and their required proof
+- source ownership, affected areas, and explicit exclusions
+- applicable tenant, authorization, privacy, lifecycle, transaction, concurrency, idempotency, audit, migration, SSR, and contract-loop constraints
+- the specialist workflow that owns implementation
+- approved verification procedures, expected redacted evidence, and allowed record updates
+- blockers, unresolved `TODO(confirm)` items, excluded unsafe operations, and one next action
+
+Require explicit approval of the dossier before source changes, meaningful verification, evidence/status updates, or specialist execution. Do not reserve a task by marking it `in-progress` before approved work actually starts.
+
+## Read authority before implementation
+
+Read the suite records in this order:
+
+1. `README.md` for identity, topology, reading order, and authority map
+2. `prd.md`, `srs.md`, and applicable ADRs for product and technical authority
+3. the complete WBS task and its dependencies in `pdp-wbs.md`
+4. linked ATP procedures and release gates in `test-plan.md`
+5. `progress.md` for derived status, blockers, waivers, evidence pointers, and next proof
+6. linked evidence, runbooks, presentation records, or rollout records when they apply
+7. `implementation-gantt.svg` and `implementation-burndown.svg` as derived views to check for freshness, not authority
+
+When records conflict, return to [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) before implementation. Do not resolve an authority contradiction through an execution note, a chart edit, or a source workaround.
+
+## Stop at readiness gates
+
+Do not begin the increment when any of these conditions applies:
+
+- the WBS target, suite identity, ownership boundary, or required source fact is unresolved
+- PRD, SRS, ADR, WBS, or ATP records conflict
+- a controlling `TODO(confirm)` or unaccepted ADR remains
+- a predecessor lacks its required completion state or evidence
+- the selected task is already `verified`, `blocked`, or `deferred`
+- overlapping working-tree changes cannot be classified for attribution
+- material tenant, authorization, privacy, lifecycle, transaction, concurrency, idempotency, audit, migration, SSR, or ownership behavior is unspecified
+- the proposed work expands scope or introduces a competing persistence, identity, or API authority
+
+When adding a persisted field to an existing backend resource, stop and ask the user whether `vonaModule.fileVersion` should increment before changing `meta.version.ts` or the module schema path. A specification can provide context, but it does not replace this direct confirmation. Do not invent a migration strategy during execution.
+
+## Route the smallest approved increment
+
+After approval, hand the smallest coherent unit to the specialist that owns its implementation.
+
+| Work shape                                                           | Route                                                |
+| -------------------------------------------------------------------- | ---------------------------------------------------- |
+| Vona module, entity, DTO, service, migration, or backend test        | `cabloy-backend-scaffold`                            |
+| Zova page, route, component, model, metadata, SSR, or frontend test  | `cabloy-frontend-scaffold`                           |
+| OpenAPI, generated consumers, reverse metadata, or consumer drift    | `cabloy-contract-loop`                               |
+| Master-detail, resource-field update, or module removal              | The corresponding specialist skill                   |
+| Requirement, scope, contract, dependency, or durable-decision change | `cabloy-spec-generation` or `cabloy-domain-planning` |
+
+The execution workflow supplies the approved dossier and preserves the boundary; it does not replace a specialist's CLI-first procedure. Never hand-edit generated consumers, infer an unconfirmed site or flavor, or expand automatically into an adjacent WBS item.
+
+## Verify narrowly and retain evidence
+
+Use the narrowest approved check first, then follow the linked ATP procedures and applicable release gates.
+
+1. run the scoped verification specified by the increment
+2. retain observed evidence using the suite's existing convention
+3. redact secrets, credentials, raw tokens, customer data, and provider identifiers
+4. record failures, waivers, invalidation, and supersession rather than erasing history
+5. update evidence before updating derived progress
+
+Use status precisely:
+
+- `in-progress` — approved implementation or verification has actually begun
+- `implementation-complete` — source work is complete, but required ATP or release proof remains
+- `verified` — all applicable WBS checks and ATPs have durable, linked, redacted observed evidence
+
+A successful build, generation command, hook, manual walkthrough, screenshot, or unrelated test run is not by itself `verified` unless the authoritative test plan defines it as sufficient retained proof. Evidence is revision- and authority-scoped; mark old proof superseded or requiring rerun when relevant source or authority changes.
+
+## Refresh derived charts last
+
+After evidence and progress are accurate, refresh the two derived views when the suite's authoritative Markdown follows the [chart input contract](/reference/repo-scripts#chart-input-contract). Refresh again when the suite README title or language changes:
+
+```bash
+npm run spec:charts -- <suite>
+# Use this non-mutating check when verifying an existing chart state:
+npm run spec:charts:check -- <suite>
+```
+
+The correct update order is:
+
+```text
+evidence → progress → derived charts
+```
+
+Use the check as a separate non-mutating freshness verification, such as CI or a review of an existing chart state. A passing chart check confirms only the supported chart input contract and generated-view freshness. It is not ATP proof, implementation proof, release approval, or a replacement for reviewing traceability and status semantics. Do not hand-edit an SVG to mask an authority conflict; correct the authoritative Markdown records and regenerate instead. Chart language follows the suite README.
+
+Confirm the available root scripts and their input expectations in the active repository, especially when the work concerns a Cabloy Start checkout or a legacy suite.
+
+## Keep unsafe operations outside the increment
+
+Without a separate explicit workflow and approval, do not:
+
+- infer Cabloy Start runtime facts from Cabloy Basic
+- run `npm run init`, reset or recreate a database, or reinstall dependencies as a first response to drift
+- clean, reset, stash, check out, or discard the working tree
+- deploy, publish, cut over, operate a provider or webhook, change credentials, or retain secrets
+- commit or push
+- fabricate evidence or promote status based only on planning artifacts, hooks, builds, or generated outputs
+- continue to adjacent WBS work automatically
+
+## Leave a resumable handoff
+
+Finish the increment with a concise record of:
+
+1. target WBS/phase, edition, revision, and working-tree classification
+2. implemented scope and explicit exclusions
+3. commands and procedures actually run
+4. observed evidence and its redacted location
+5. resulting status and its precise reason
+6. remaining blocker or evidence gap
+7. exactly one next action
+
+A next action is a handoff, not authorization to execute another task. If it requires an authority change, return to [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation).
+
+For the public boundaries between docs, skills, suite authority, and CLI workflows, read [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping) and [CLI to Skill Map](/ai/cli-to-skill-map).