cabloy 5.1.151 → 5.1.153

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).

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

@@ -0,0 +1,155 @@
+# Playbook: Plan a Cabloy Suite Specification
+
+Use this playbook to create or maintain the repository-native planning record for a long-lived Cabloy business suite. It explains the public workflow behind the `cabloy-spec-generation` skill without replacing the skill's detailed decision tree.
+
+A specification establishes product intent, technical contracts, delivery structure, acceptance procedures, and decision history. It does **not** prove that implementation, generated artifacts, tests, or acceptance evidence already exist.
+
+## When to use this playbook
+
+Use `cabloy-spec-generation` when you need to:
+
+- establish a new suite's PRD, SRS, WBS, test plan, progress register, and initial ADR
+- extend an existing suite's authoritative planning records
+- turn product intent into traceable delivery and acceptance records
+- prepare an approved handoff for implementation
+
+Use a different workflow when:
+
+- provider, suite, or module identity is unresolved — use `cabloy-domain-planning`
+- the task is approved backend or frontend scaffolding — use `cabloy-backend-scaffold` or `cabloy-frontend-scaffold`
+- the task is Vona/Zova contract synchronization or generated-consumer drift — use `cabloy-contract-loop`
+- the task is one already approved, bounded WBS increment — use [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+
+## Start with repository and edition discovery
+
+Before naming a suite, describing source topology, or recommending a site, flavor, UI, SSR, or command path:
+
+1. inspect the active repository root and edition marker
+2. inspect the root `package.json`, `CLAUDE.md`, relevant CLI entrypoints, and existing suite records
+3. separate observed source facts from confirmed user inputs, proposed targets, and `TODO(confirm from active source)` items
+
+Cabloy Basic and Cabloy Start share the planning model, but their runtime details can differ. Do not carry a Basic command, site identifier, flavor, UI assumption, or generated-output path into Start without confirming it in the active Start source.
+
+Read [Edition Detection for AI Workflows](/ai/edition-detection), [Repo Guidance](/ai/repo-guidance), [Repo Scripts](/reference/repo-scripts), and [Package Map](/reference/package-map) before making repository-specific claims.
+
+## Classify the planning request
+
+### New suite baseline
+
+A long-lived business domain normally receives the complete planning baseline under `repo-specs/<suite>/`. The specification should be suite-first, name capability modules by business responsibility, and avoid inventing a competing persistence, identity, or authorization owner.
+
+### Existing suite extension
+
+Read the existing README and authority map first. Update the owning PRD, SRS, or ADR before downstream WBS, test-plan, progress, or evidence references. Preserve existing identifiers, accepted decisions, history, and evidence conventions rather than replacing them with a fresh parallel record.
+
+### Proportionate planning
+
+A disposable demo, tutorial, or isolated utility can use a smaller record only when the requester explicitly selects that scope. Do not reduce the planning baseline for a domain expected to grow merely because its first increment is small.
+
+### Unresolved identity
+
+Stop before creating a planning directory when the provider, suite, or capability boundary is unclear. Route the identity decision to `cabloy-domain-planning` rather than creating a competing suite hierarchy.
+
+## Keep the authority chain explicit
+
+Repository-native traceability flows in one direction:
+
+```text
+PRD requirement → SRS contract → PDP/WBS task → ATP scenario → observed evidence
+```
+
+Each record has a distinct role:
+
+| Record                 | Authority                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `README.md`            | Index, reading order, topology summary, and authority map                                                 |
+| `prd.md`               | Product outcomes, personas, scope, journeys, business rules, and launch criteria                          |
+| `srs.md`               | Technical contracts, ownership, data, tenant, authorization, lifecycle, API, and nonfunctional boundaries |
+| `pdp-wbs.md`           | Dependency order, bounded delivery tasks, completion checks, and contract-loop checkpoints                |
+| `test-plan.md`         | Formal ATP scenarios, procedures, fixtures, expected proof, and release gates                             |
+| `decisions/*.md`       | Durable suite decisions and their alternatives, consequences, and gates                                   |
+| Evidence records       | Observed, redacted proof only                                                                             |
+| `progress.md`          | Derived execution status, blockers, evidence links, and next proof                                        |
+| `implementation-*.svg` | Deterministic derived views of planning and progress records                                              |
+
+Update the upstream owner before downstream records. For example, a product or technical change belongs in the PRD, SRS, or ADR first; it is then traced into WBS tasks, ATP procedures, progress implications, and derived charts.
+
+A proposed ADR is not an accepted decision. Progress cannot introduce a new requirement, contract, or durable boundary, and a chart cannot repair an authority conflict.
+
+## Build the planning baseline after confirmation
+
+For a new long-lived suite, the normal core set is:
+
+```text
+repo-specs/<suite>/
+├── README.md
+├── prd.md
+├── srs.md
+├── pdp-wbs.md
+├── test-plan.md
+├── progress.md
+├── implementation-gantt.svg
+├── implementation-burndown.svg
+└── decisions/
+    └── 0001-*.md
+```
+
+Add presentation contracts, staged rollout records, runbooks, additional ADRs, or an `evidence/` directory only when their scope is justified. Do not create empty evidence records to imply that testing or delivery has begun.
+
+Before creating or replacing records, explicitly confirm at least:
+
+- repository, edition, suite identity, and target directory
+- intended product outcome, audiences, in-scope capabilities, and deferred scope
+- confirmed and unresolved tenant, authorization, privacy, ownership, lifecycle, migration, and integration constraints
+- site strategy at the level actually supported by current source and confirmed inputs
+- required core documents and justified optional records
+- unresolved decision gates and which WBS branches they block
+- the initial delivery-status policy
+
+Silence is not approval. Confirmation to generate records does not accept a durable ADR; retain an unaccepted decision as proposed. Initial delivery rows are normally `not-started`, `deferred`, or explicitly `blocked` unless actual prior evidence was intentionally carried forward.
+
+## Preserve traceability and status integrity
+
+Use stable identifiers such as `PRD-*`, `SRS-*`, `WBS-*`, and `ATP-*`. Every referenced exact identifier must resolve to a formal definition in its owning document; a range, wildcard, or prose summary is not a substitute.
+
+The status vocabulary is:
+
+- `not-started`
+- `in-progress`
+- `implementation-complete`
+- `verified`
+- `blocked`
+- `waived`
+- `deferred`
+
+`verified` requires retained, redacted, traceable observed proof. A planning record, a planned command, a generated scaffold, a screenshot, or an unrelated broad check does not automatically provide that proof.
+
+## Generate and check derived charts
+
+For a new or substantially revised long-lived specification set whose authoritative Markdown follows the [chart input contract](/reference/repo-scripts#chart-input-contract), refresh the two derived views after changing the README title or language, WBS, test plan, or progress register:
+
+```bash
+npm run spec:charts -- <suite>
+# Use this non-mutating check when verifying an existing chart state:
+npm run spec:charts:check -- <suite>
+```
+
+The generator consumes the suite README, WBS, test plan, and progress register. It emits `implementation-gantt.svg` and `implementation-burndown.svg`; visible chart language follows the suite README. After refreshing charts, use the check when a separate freshness verification is needed, such as CI or a non-mutating review.
+
+The check validates the supported chart input contract and generated-view freshness. It does **not** implement a WBS task, run an ATP, establish evidence, prove acceptance, or replace a review of traceability and status semantics. The charts are scope/order views, not schedule forecasts or a new status authority.
+
+This current baseline does not require unchanged legacy suite records to be migrated solely to add charts. A legacy record that does not follow the chart input contract must not be treated as chart-compatible until a deliberate record-format normalization aligns its authoritative Markdown. That normalization preserves existing planning authority and does not require an unrelated product or delivery change. Always confirm exact scripts and input expectations in the active repository before running or documenting them for another edition.
+
+## Hand off work without implying implementation
+
+Once the planning authority is coherent and implementation is approved, route the next task deliberately:
+
+- unresolved domain identity or boundary → `cabloy-domain-planning`
+- approved backend increment → `cabloy-backend-scaffold`
+- approved frontend increment → `cabloy-frontend-scaffold`
+- contract synchronization or generated-consumer drift → `cabloy-contract-loop`
+- an approved bounded WBS increment → [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+
+Do not make code changes, run initialization or database-reset workflows, deploy, operate a provider, or claim implementation or verification merely because planning records now exist.
+
+For the division of responsibility between public docs, skills, repository specs, and internal rationale, read [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping).

package/repo-docs/ai/repo-guidance.md

@@ -8,10 +8,11 @@ Check the root repository signals first:
 
 - `package.json`
 - edition marker files such as `__CABLOY_BASIC__` or `__CABLOY_START__`
-- an established internal-documentation home, when present
+- `repo-docs-internal/`
+- `repo-specs/` when the task concerns a suite plan, WBS increment, acceptance record, or evidence
 - root `.claude/` assets
 
-These surfaces tell the agent which repo it is in and which scripts are canonical. Inspect an internal-documentation home only when the active repository actually provides one.
+These surfaces tell the agent which repo it is in and which scripts are canonical. Inspect relevant `repo-docs-internal/` records as supporting context rather than as a gate to workflow guidance.
 
 ## 2. Prefer framework entrypoints over scattered examples
 
@@ -27,11 +28,14 @@ For frontend workflows:
 
 This is more reliable than copying old file structures from examples without understanding the command surface that created them.
 
-## 3. Use public docs and optional internal notes for different purposes
+## 3. Use public docs, suite records, and internal notes for different purposes
 
 - use `repo-docs/` to explain how people and agents should work
-- when an established internal-documentation home exists, use it for maintainer rationale
-- when it does not exist, continue from public docs, rules, skills, source, and tests; do not create a new documentation home implicitly
+- use `repo-specs/<suite>/` for suite-local product, technical, delivery, ATP, progress, ADR, and observed-evidence authority
+- use `repo-docs-internal/` for supporting maintainer rationale
+- continue from public docs, rules, skills, source, and tests when a specific internal record is unavailable or irrelevant; do not create a replacement document implicitly
+
+For planning work, read the suite README, PRD, SRS, WBS, test plan, and progress records in the order appropriate to the task. `cabloy-spec-generation` maintains planning authority; `cabloy-spec-execution` acts only on a confirmed, bounded WBS increment. Both require active-source and edition discovery before topology or command claims.
 
 ## 4. Treat edition detection as mandatory for UI-sensitive work
 

package/repo-docs/ai/rules-and-config.md

@@ -8,7 +8,7 @@ Use the root `CLAUDE.md` for concise, durable operational guidance such as:
 
 - how the monorepo is organized
 - where public docs live
-- whether an established internal-documentation home is available
+- where `repo-docs-internal/` holds supporting maintainer rationale
 - which command entrypoints are preferred
 - why edition detection is mandatory before UI-sensitive guidance or project-creation assumptions
 
@@ -26,4 +26,4 @@ Use Claude settings for permissions and execution environment, not as the primar
 
 ## Documentation boundary
 
-If a rule is important for people and agents to understand, it probably belongs in public docs too. When an established internal-documentation home exists, it may hold maintainer rationale rather than user-facing workflow. Do not infer or create such a home from edition identity alone.
+If a rule is important for people and agents to understand, it probably belongs in public docs too. `repo-docs-internal/` holds supporting maintainer rationale rather than user-facing workflow; individual records may vary by edition.

package/repo-docs/ai/skills.md

@@ -42,8 +42,12 @@ Current examples include:
 
 - `cabloy-workflow` for choosing the correct Cabloy work path before implementation
 - `cabloy-domain-planning` for proposing and confirming providerId, suite, and initial module names before scaffolding a new business domain
+- `cabloy-spec-generation` for creating or maintaining suite-local planning authority, traceability, and derived planning views before implementation
+- `cabloy-spec-execution` for coordinating one confirmed WBS increment through specialist implementation, evidence, and derived progress updates
 - `cabloy-contract-loop` for backend/frontend contract regeneration and drift diagnosis
 - `cabloy-resource-field-update` for updating an existing backend resource field thread
 - `cabloy-module-removal` for removing a backend, frontend, or fullstack module cleanly, including generated-runtime cleanup, stale-residue recovery, and verification
 
+The specification workflows show the same boundary: [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) and [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) explain the durable public workflow, while the skills retain the branching, confirmation gates, specialist routing, and evidence protocol.
+
 The module-removal workflow is a good example of why skills belong in `.claude/skills/` instead of `CLAUDE.md`: the task needs branching, cleanup order, recovery guidance for generated runtime directories such as `vona/.vona` and `zova/.zova`, and a verification checklist that would be too large for a short repo-wide rule.

package/repo-docs/ai/virtual-decorator-guidance.md

@@ -201,4 +201,4 @@ Read these pages together:
 - [Global Bean Lookup](/ai/global-bean-lookup)
 - [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
 
-For maintainer-level rationale, consult an established internal-documentation home when the active repository provides one. The public guidance above is the complete shared operational rule.
+For maintainer-level rationale, consult relevant records in `repo-docs-internal/`. The public guidance above is the complete shared operational rule.

package/repo-docs/backend/introduction.md

@@ -19,7 +19,7 @@ For contributor and automation workflows in this repository, prefer this order:
 1. inspect the root `package.json` and `npm run vona` entrypoint
 2. inspect Vona CLI command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
 3. inspect the current module or suite layout before creating new files manually
-4. use public docs for user-facing and agent-facing guidance; consult an established internal-documentation home only when the active repository provides one for maintainer rationale
+4. use public docs for user-facing and agent-facing guidance; consult relevant `repo-docs-internal/` records for supporting maintainer rationale
 
 ## Backend reading paths
 

package/repo-docs/frontend/model-resource-cookbook.md

@@ -87,7 +87,8 @@ export class ModelStudent extends BeanModelBase {
         return res ?? null;
       },
       meta: {
-        disableSuspenseOnInit: true,
+        // The Summary dialog renders query errors itself.
+        disableErrorEffect: true,
       },
     });
   }
@@ -121,14 +122,40 @@ const modelStudent = (await ctx.bean._getBean(
   true,
 )) as ModelStudent;
 const querySummary = modelStudent.summary(id);
+await querySummary.suspense();
 
-await querySummary.refetch({ bypassPersister: true });
 $host.$appModal.dialog({
-  slotDefault: () => <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />,
+  slotDefault: () => {
+    const hasData = querySummary.data !== undefined;
+    const isLoading = !hasData && (querySummary.isPending || querySummary.isFetching);
+    const error = querySummary.error;
+
+    return (
+      <>
+        {hasData && error && (
+          <div class="alert alert-warning" role="alert">
+            <span>{this.scope.locale.SummaryRefreshFailed()}</span>
+          </div>
+        )}
+        {error && (
+          <div class="alert alert-error" role="alert">
+            <span>{error.message}</span>
+          </div>
+        )}
+        {hasData ? (
+          <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />
+        ) : isLoading ? (
+          <div role="status">Loading...</div>
+        ) : undefined}
+      </>
+    );
+  },
 });
 ```
 
-`refetch({ bypassPersister: true })` is useful when this interaction needs an API-fresh result without restoring or scheduling a persistence save through the persister for that fetch. The successful result still updates the model-owned in-memory query, and the dialog remains bound to `querySummary.data`, so the query remains the source of its ongoing render state rather than transferring ownership to an awaited-result snapshot. The option affects only this fetch; normal query cancellation and in-flight deduplication rules still apply. It is not a force-new-request option: when an existing fetch is reused by TanStack Query, that fetch's semantics remain in effect. The bypassed fetch itself does not intentionally replace an existing persisted value; an already queued ordinary persistence callback is a separate operation and is not automatically cancelled. Use static `meta.persister: false` only when persistence should be disabled for the query generally.
+Opening this Summary dialog is an interaction readiness boundary, so the handler awaits the existing model-owned query with `await querySummary.suspense()` before creating the dialog. That wait follows normal query cache, staleness, error, persistence, and deduplication semantics; it is not an unconditional API-fresh request. After opening, the dialog remains bound to reactive query state rather than an awaited one-shot result, so later query updates remain visible.
+
+Use `data !== undefined` as the availability boundary. Retained data plus `error` renders two distinct messages while preserving the content: a non-blocking localized refresh-failure warning explains that the content may be outdated, and `error.message` explains the concrete failed fetch. No data plus `error` renders only the concrete fetch error. This is persisted-cache-first stale-while-revalidate UI, not an API-fresh orchestration decision. Whether restore and follow-up revalidation occur depends on data availability, persister configuration, and staleness.
 
 ### Avoid
 
@@ -161,7 +188,8 @@ summary(id: TableIdentity) {
       return res ?? null;
     },
     meta: {
-      disableSuspenseOnInit: true,
+      // The Summary dialog renders query errors itself.
+      disableErrorEffect: true,
     },
   });
 }
@@ -242,6 +270,8 @@ deleteForce(id: TableIdentity) {
 - item/list invalidation remains centralized
 - the business-facing model exposes semantic actions without competing for cache ownership
 
+`mutationItem(...)` awaits its standard consistency work before mutation completion: it invalidates matching active `select` queries unless `invalidateSelect: false`, then invalidates matching active queries under the row's item root, and only then invokes and awaits the optional custom `onSuccess`. This keeps `mutateAsync()` aligned with active resource refreshes. `invalidateSelect: false` skips only the default select invalidation; item-root invalidation remains automatic.
+
 ## Recipe 5: customize invalidation for a special mutation
 
 ### Use this when
@@ -261,7 +291,6 @@ publish(id: TableIdentity) {
     },
     onSuccess: async () => {
       await this.$$modelResource.$invalidateQueries({ queryKey: ['select'] });
-      await this.$$modelResource.$invalidateQueries({ queryKey: ['item', id] });
       await this.$$modelResource.$invalidateQueries({ queryKey: ['select', 'dashboard'] });
     },
   });
@@ -271,7 +300,7 @@ publish(id: TableIdentity) {
 ### Why this works well
 
 - the existing resource-owner remains the source of truth for consistency rules
-- special cache dependencies stay explicit
+- the automatic item-root invalidation completes before this callback adds the special list dependencies
 - pages do not need to remember hidden follow-up refetch rules
 
 ### Avoid
@@ -412,6 +441,8 @@ batchArchive(ids: TableIdentity[]) {
 - list invalidation policy remains visible
 - cache ownership still stays with the existing resource-owner even when row-level helpers are not the right fit
 
+This uses raw `$useMutationData(...)` because a batch action affects multiple rows rather than the one `id` accepted by `mutationItem(...)`. It does not inherit `mutationItem(...)`'s automatic item-root invalidation or sequencing, so define and await the necessary list and per-item invalidations explicitly.
+
 ## Recipe 10: keep generic blocks working while adding resource semantics
 
 ### Use this when

package/repo-docs/frontend/model-resource-usage-guide.md

@@ -129,7 +129,8 @@ export class ModelStudent extends BeanModelBase {
         return res ?? null;
       },
       meta: {
-        disableSuspenseOnInit: true,
+        // The Summary dialog renders query errors itself.
+        disableErrorEffect: true,
       },
     });
   }

package/repo-docs/frontend/router-tabs-introduction.md

@@ -116,7 +116,7 @@ Recommended order:
 
 The public router-tabs docs explain the shared frontend mechanism and how to use it.
 
-For maintainer-only design boundaries, maintenance invariants, and refactor safety rules, consult an established internal-documentation home when the active repository provides one. The public mechanism, layout, route-meta, and Admin/Web comparison guides remain the shared implementation baseline.
+For maintainer-only design boundaries, maintenance invariants, and refactor safety rules, consult relevant `repo-docs-internal/` records. The public mechanism, layout, route-meta, and Admin/Web comparison guides remain the shared implementation baseline.
 
 ## See also
 

package/repo-docs/frontend/use-state-data-best-practices.md

@@ -284,6 +284,8 @@ A query established during render remains the owner of its ongoing state. Render
 
 An interaction or orchestration boundary may still await `query.refetch()` when it needs one result to decide whether to continue a command, navigate, show a notification, or open a dialog. That result is local to the current sequence; it does not transfer query ownership to the controller or render path.
 
+When a query-backed dialog needs readiness before it opens, await the existing query's `suspense()` instead. This follows normal query cache, staleness, error, and deduplication semantics; it does not necessarily force an API-fresh request. After the dialog opens, continue to render from the query wrapper rather than the awaited result.
+
 Do not copy an awaited `refetch()` result into a second long-lived controller/render state that drives an open dialog or persistent component. If the UI remains mounted and displays query-backed data, bind it to `query.data` or a model-derived reactive surface so later refetches and model updates remain visible.
 
 ### Per-fetch persistence bypass
@@ -305,22 +307,53 @@ await query.refetch({ bypassPersister: true });
 
 This option is not a force-new-request flag. Cancellation, `cancelRefetch`, and in-flight deduplication continue to follow TanStack Query semantics. If an existing fetch is reused, its already-established fetch semantics remain in effect. The bypassed fetch itself does not intentionally replace an existing persisted value; an already queued ordinary persistence callback is a separate operation and is not automatically cancelled.
 
+When the current interaction or polling iteration must make an immediate decision from its API-oriented fetch, consume the awaited result rather than rereading `query.data`:
+
+```ts
+const result = await queryPaymentSession.refetch({
+  bypassPersister: true,
+});
+const session = result.data;
+
+if (session?.state === 'succeeded') {
+  // Decide this iteration from this fetch result.
+}
+```
+
+`query.data` remains the reactive, long-lived surface for rendering and subsequent updates. `result.data` is the result for this one awaited sequence. Keeping those roles separate prevents a controller from treating ongoing render state as the local result variable for a command. The result represents this fetch's response; it does not guarantee that no later server-side state transition occurs, and normal TanStack Query reuse semantics still apply.
+
 This is different from static `meta.persister: false`: the static option disables persistence for the query generally, while `bypassPersister: true` opts out only for one fetch.
 
-For example, an interaction can request a fresh summary and then open a dialog while the dialog remains bound to the query-owned state:
+By contrast, a summary dialog can deliberately use persisted-cache-first behavior while remaining bound to query-owned state:
 
 ```ts
 const querySummary = modelStudent.summary(id);
-await querySummary.refetch({ bypassPersister: true });
+await querySummary.suspense();
 
 $host.$appModal.dialog({
-  slotDefault: () => (
-    <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />
-  ),
+  slotDefault: () => {
+    const hasData = querySummary.data !== undefined;
+    const isLoading = !hasData && (querySummary.isPending || querySummary.isFetching);
+    const error = querySummary.error;
+
+    return (
+      <>
+        {hasData && error && <SummaryRefreshWarning />}
+        {error && <SummaryFetchError error={error} />}
+        {hasData ? (
+          <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />
+        ) : isLoading ? (
+          <SummaryLoading />
+        ) : undefined}
+      </>
+    );
+  },
 });
 ```
 
-The awaited result may coordinate the current interaction, but ongoing rendering should continue to read `querySummary.data`.
+This Summary interaction deliberately awaits `querySummary.suspense()` before opening the dialog. It therefore has a query-readiness boundary, but does not force an API-fresh request: the wait still follows normal query cache, staleness, error, persistence, and deduplication semantics. The open dialog reads every later transition through `querySummary.data` and its query status rather than taking ownership of an awaited one-shot result.
+
+Treat `data !== undefined` as the availability boundary. Retained data plus `error` has two separate user-facing meanings: render a non-blocking refresh-failure warning to explain that the retained content may be outdated, render the concrete `error.message` through `SummaryFetchError`, and keep the content visible. With no data plus `error`, render only the concrete fetch error. This is persisted-cache-first stale-while-revalidate UI, not an API-fresh orchestration request. Restore and follow-up revalidation depend on data availability, persister configuration, and staleness.
 
 ## Practical rule 7: derive render-time state once per render when possible
 

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

@@ -6,9 +6,12 @@ This monorepo is organized around a small set of stable top-level areas.
 
 - `package.json` — shared scripts and release entrypoints
 - `lerna.json` — package topology
-- an established internal-documentation home, when present — edition-local maintainer notes and ADRs
+- `repo-docs-internal/` — edition-local maintainer notes and ADRs
 - `.claude/` — Claude commands, skills, and local settings
 - `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).
 
 ## Backend side
 

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

@@ -42,6 +42,31 @@ Cabloy Basic exposes these shared root scripts:
 
 `npm run init` prepares all Cabloy Basic SSR and REST artifacts with `npm run build:zova:all`, which sequentially builds the Basic and Commerce flavor batches before Vona initialization. Use `build:zova` or `build:zova:commerce` for focused artifact refreshes; use `build:zova:all` only when every shipped Basic flavor must be prepared.
 
+## Specification planning and derived charts
+
+The current Cabloy Basic root scripts also expose:
+
+```bash
+npm run test:spec-charts
+npm run spec:charts -- <suite>
+npm run spec:charts:check -- <suite>
+```
+
+`spec:charts` refreshes the generated Gantt and burndown SVG views for a chart-compatible `repo-specs/<suite>/` record. `spec:charts:check` validates the supported input contract and detects stale generated views; `test:spec-charts` runs the chart-tool test suite.
+
+### Chart input contract
+
+The generator consumes `README.md`, `pdp-wbs.md`, `test-plan.md`, and `progress.md`. The supported Markdown format includes:
+
+- formal `### Phase <number>:` and `#### WBS-...:` headings in the WBS, with supported dependency labels
+- formally defined `ATP-*` scenarios in the test plan for every ATP reference used by a WBS task
+- one progress row for each WBS item, with the WBS ID in the first cell and its supported status in the second cell
+- a README whose current title and language should be reflected by regenerated chart output
+
+A legacy suite with a different WBS or progress-table layout is not chart-compatible until a deliberate record-format normalization aligns its authoritative Markdown with this input contract. Format normalization must preserve the existing planning authority; it does not require an unrelated product or delivery change.
+
+These commands do not create planning authority, implement a WBS task, execute an ATP, produce acceptance evidence, or replace traceability/status review. Confirm the active root `package.json` and script input expectations before assuming equivalent behavior in Cabloy Start or another repository.
+
 ## Cabloy Start entrypoints
 
 Cabloy Start exposes the equivalent Start repository surface: