cabloy 5.1.149 → 5.1.151

package/.claude/skills/cabloy-spec-execution/references/execution-protocol.md

@@ -0,0 +1,137 @@
+# Spec Execution Protocol
+
+This reference defines the preflight and handoff protocol for `cabloy-spec-execution`. It coordinates an approved delivery increment; it does not become a parallel product, architecture, or implementation authority.
+
+## 1. Discovery dossier
+
+Before selecting work, inspect the active repository root and record only observed facts:
+
+```bash
+git rev-parse --show-toplevel
+git status --short
+git rev-parse HEAD
+find . -maxdepth 1 \( -name '__CABLOY_BASIC__' -o -name '__CABLOY_START__' \) -print
+```
+
+Then inspect the root `package.json`, `CLAUDE.md`, the suite spec directory, and actual affected source paths. Classify the worktree as clean, dirty with unrelated changes, dirty with overlapping changes, or otherwise unknown. Do not clean or reset it to make execution easier.
+
+For Basic, resolve current scripts, sites, flavors, UI, and generated paths from the active repository. For Start, inspect the active Start repository and use its own commands and flavor/site names. The shared execution model does not make edition-specific runtime facts interchangeable.
+
+## 2. Target selection
+
+The normal unit of work is one WBS item. A phase may be selected only when the phase is a finite, explicitly approved batch and the WBS defines its task set and closure boundary.
+
+A valid target dossier names:
+
+- suite planning directory and edition;
+- one `WBS-*` ID, or finite phase/task list;
+- linked `PRD-*`, `SRS-*`, and `ATP-*` IDs;
+- dependencies and predecessor WBS rows;
+- source areas and ownership;
+- explicit exclusions and neighboring work that will not be touched.
+
+Vague targets such as “implement the suite”, “finish all specs”, or “do the next phase” are not executable. Ask the user to select a task or approve a finite task list.
+
+## 3. Authority and readiness gates
+
+Read in this order:
+
+1. README and authority map;
+2. PRD, SRS, and applicable ADRs;
+3. complete WBS task and dependency rows;
+4. linked ATP definitions and test-plan release gates;
+5. progress, blockers, waivers, and next proof;
+6. linked evidence, phase indexes, runbooks, presentation contracts, rollout records, and the two derived implementation charts; verify their freshness with `npm run spec:charts:check -- <suite>`.
+
+Before implementation, verify:
+
+- the WBS target exists and is bounded;
+- every material linked requirement has a technical contract and ATP;
+- predecessor status satisfies the WBS dependency rule and required evidence exists;
+- no controlling `TODO(confirm)`, unaccepted ADR, waiver, or failed gate remains unresolved;
+- the selected task is not already `verified`, `deferred`, or `blocked`;
+- source ownership and the target API/state/page boundary are unambiguous;
+- current evidence is still valid for the current source revision and authority set;
+- both implementation charts are present and current, or their regeneration is included in the approved record-update scope;
+- dirty-worktree changes can be attributed without overwriting unrelated work;
+- tenant, identity, authorization, ownership, privacy, lifecycle, transaction, concurrency, idempotency, audit, and recovery constraints are defined for the task’s risk;
+- the requested change does not broaden scope or create a competing persistence, identity, or API authority.
+
+When authority records conflict, stop. Update the authoritative PRD, SRS, or ADR through `cabloy-spec-generation`, then propagate the change through WBS, ATP, evidence assumptions, and progress. Do not reconcile a conflict by silently editing a downstream status or implementation plan.
+
+## 4. Special gates
+
+### Persisted schema and file version
+
+If implementation may add or alter a persisted field, table, relation, index, or `meta.version.ts` path, ask before editing whether `vonaModule.fileVersion` should increment. Do not infer the answer from neighboring modules. If `meta.version.ts` changes, the repository rule requires `npm run test` after the change; include this in the dossier and evidence plan.
+
+### Contract loop
+
+Classify the handoff before choosing commands:
+
+- **forward**: Vona DTO/controller/entity/validation/OpenAPI truth -> inspect output -> regenerate Zova consumers -> thin frontend follow-up;
+- **reverse**: Zova-owned route/resource/metadata -> build the affected flavor’s SSR and REST outputs -> run `npm run deps:vona`;
+- **consumer drift**: identify the generated or hand-authored stale surface before changing source;
+- **local dependency drift**: enter only after source, generated output, flavor build, and dependency sync are known correct.
+
+Generated consumers are disposable outputs and must not be hand-edited. The contract-loop hook may assist, but it is not proof of completion.
+
+### SSR and flavor
+
+For SSR or route work, identify the actual site/flavor, route admission, auth requirement, SSR profile, private data boundary, and hydration-time initial render contract. Verify the relevant SSR and REST artifacts together when the change crosses the reverse handoff. Do not use the absence of a locale parameter as a reason to choose a session/public profile, and do not copy Basic SSR assumptions into Start.
+
+### External and destructive operations
+
+Provider calls, real webhooks, deployment, release, cutover, credential changes, database reset/recreation, `npm run init`, broad generation, cleanup/reset/stash/checkout, and dependency reinstall are separate operations. Keep them out of ordinary spec execution unless their own explicit workflow and confirmation authorizes them. Use synthetic or sandbox data and redact retained proof.
+
+## 5. Confirmation dossier template
+
+Present this before implementation:
+
+```text
+Execution target: <WBS ID or finite phase>
+Edition/repository: <observed edition and root>
+Revision/worktree: <HEAD>; <clean or dirty classification>
+Scope: <bounded tasks and exclusions>
+Authority: <PRD/SRS/ADR/WBS/ATP links>
+Dependencies: <predecessors and proof>
+Source ownership: <observed paths and proposed paths>
+Specialist route: <backend/frontend/contract-loop/specialist>
+Safety/contract constraints: <tenant, auth, lifecycle, transaction, SSR, migration, privacy>
+Verification: <exact approved ATP procedures and commands>
+Evidence: <required revision/environment/procedure/result/redacted artifact>
+Derived charts: regenerate `implementation-gantt.svg` and `implementation-burndown.svg` after `progress.md`, then run `npm run spec:charts:check -- <suite>`; their language follows `README.md` and they remain non-authoritative.
+Allowed record updates: <evidence/phase index/progress/derived charts, or explicitly named authority change>
+Blocked or unresolved: <TODOs, waivers, conflicts>
+Excluded operations: <init/reset/deploy/provider/etc.>
+Next action: <one action after confirmation>
+```
+
+Require explicit confirmation. If the user changes scope, rebuild the dossier and re-check dependencies and authority. A prior confirmation does not authorize a new task, phase, provider operation, or destructive command.
+
+## 6. Specialist routing
+
+| Task shape | Primary route | Coordinator must preserve |
+| --- | --- | --- |
+| Vona module/bean/service/model/entity/DTO/validation/migration/test | `cabloy-backend-scaffold` | CLI-first generation, tenant/security review, migration/index/version gate, tests, OpenAPI impact |
+| Zova page/component/route/model/metadata/SSR/test | `cabloy-frontend-scaffold` | route metadata, state ownership, hydration equivalence, emitted import suffixes, flavor/site proof |
+| OpenAPI, SDK/schema, generated consumer, reverse metadata, stale consumer | `cabloy-contract-loop` | source-first direction, paired SSR/REST reverse build, `deps:vona`, no hand edits |
+| master-detail, resource-field, module removal | corresponding specialist skill | specialized ownership and cleanup order |
+| requirement, architecture, scope, identity, or authority change | `cabloy-spec-generation` / `cabloy-domain-planning` | no implementation around unresolved authority |
+
+The coordinator may pass the dossier to the specialist; it should not duplicate the specialist’s detailed command tree.
+
+## 7. Verification and stopping
+
+Start with the narrowest meaningful check, then execute linked ATP procedures and only the required release gates. Explicitly preserve test-owned fixture cleanup, separate `mockCtx(...)` boundaries for competing Vona operations, synthetic/redacted data, and the test plan’s database/flavor requirements.
+
+Stop and report rather than guessing when:
+
+- a command or path is not observed in the active repository;
+- a test fails or a required artifact is missing;
+- the working tree becomes attribution-ambiguous;
+- a specialist discovers a requirement or contract change;
+- a planned external/destructive operation is needed;
+- a prior evidence record is invalidated by source or authority changes.
+
+A failed verification creates an accurate blocker only when the observed result is recorded; otherwise the task remains unexecuted or in-progress according to actual activity. Do not claim a phase or release is closed because one feature ATP passed.

package/.claude/skills/cabloy-spec-execution/references/status-and-evidence.md

@@ -0,0 +1,117 @@
+# Status and Evidence Update Rules
+
+This reference defines how `cabloy-spec-execution` closes observed work without turning derived records into a second authority.
+
+## Authority and update order
+
+The suite’s `test-plan.md` owns ATP definitions, procedures, expected outcomes, evidence format, and release gates. The PRD, SRS, ADRs, and WBS remain authoritative for product scope, technical contracts, durable decisions, dependencies, and completion checks.
+
+For ordinary execution that does not change authority:
+
+1. retain actual evidence;
+2. update a dedicated phase/ATP evidence record when the suite convention supports it;
+3. update a rollout or operational handoff record when it is part of the established suite flow;
+4. update `progress.md` with derived status, evidence pointers, blockers, and next proof;
+5. regenerate `implementation-gantt.svg` and `implementation-burndown.svg` last, then run `npm run spec:charts:check -- <suite>`.
+
+The charts are derived views only. Refresh them after status, review-date, evidence-pointer, or evidence-supersession changes that affect their display; do not edit them to conceal an authority conflict. Their labels, accessibility text, and metadata follow the suite `README.md` language.
+
+Some Basic suites retain observed evidence inline in `test-plan.md`. Preserve the existing convention rather than introducing duplicate evidence stores. If the procedure, expected result, evidence requirement, release gate, or delivery scope changes, update the owning authority first and then reassess existing evidence before updating progress.
+
+Do not use `progress.md` to add requirements, technical contracts, acceptance procedures, dependencies, or architecture decisions. Do not modify unrelated WBS rows or rewrite historical evidence for presentation.
+
+## Evidence layout
+
+Prefer the scalable phase/ATP layout for newly observed proof when the suite permits extensions:
+
+```text
+evidence/
+└── phase-<NN>/
+    ├── index.md
+    ├── ATP-<DOMAIN>-<CAPABILITY>-<NN>.md
+    └── artifacts/
+        └── <date>-<revision>-<scope>.md|log
+```
+
+A dedicated ATP evidence record should include:
+
+- linked PRD, SRS, WBS, and ATP IDs;
+- source revision or commit;
+- clean/dirty worktree classification; for dirty proof, a patch or diff digest and clear changed-file scope;
+- database, environment, flavor/site, and configuration class when relevant;
+- exact command, API procedure, browser procedure, or CI job;
+- synthetic fixtures and explicit concurrency interleaving where relevant;
+- expected and observed result, including failures;
+- durable redacted log, response, screenshot, CI job, or artifact location;
+- superseded evidence and reconciliation note when newer proof replaces an older record;
+- waiver owner, reason, affected IDs, expiry, and compensating control when applicable.
+
+Do not retain credentials, raw tokens, signed callback state, secrets, live provider identifiers, or real customer/payment data. Redaction is part of the evidence record, not an informal afterthought.
+
+Do not create an empty `evidence/` directory, placeholder `EVD-*` record, or fabricated artifact merely to satisfy a traceability table. A command written in a test plan or dossier is prospective until it is actually executed and retained.
+
+## Status vocabulary
+
+Use the suite’s canonical status meanings:
+
+| Status | Meaning |
+| --- | --- |
+| `not-started` | Defined, but implementation or acceptance evidence has not started. |
+| `in-progress` | Work or verification has started, but closure checks remain. |
+| `implementation-complete` | Source work is reported complete, but required ATP or release evidence is incomplete. |
+| `verified` | Applicable WBS checks and ATPs passed, with durable traceable evidence containing revision, environment, exact procedure, result, and redacted artifact location. |
+| `blocked` | A dependency, unresolved decision, failed gate, attribution problem, or missing required proof prevents closure. |
+| `waived` | A temporary exception has an owner, reason, affected scope, and expiry; expiry becomes a release blocker. |
+| `deferred` | Explicitly postponed scope; it is not complete or verified. |
+
+The normal path is:
+
+```text
+not-started -> in-progress -> implementation-complete -> verified
+```
+
+`blocked`, `waived`, and `deferred` are explicit states, not shortcuts to completion. Mark a task `in-progress` only after approved implementation or verification actually begins. A generated file, successful scaffold, passing typecheck, code review, manual walkthrough, screenshot, or unrelated broad test pass cannot by itself produce `verified`.
+
+A task may be `implementation-complete` when source work is complete but an ATP, browser check, paired build, release gate, redaction decision, or durable artifact remains. A phase can be verified without implying that a separately defined integration or release phase is verified.
+
+## Historical evidence and supersession
+
+Evidence is revision- and authority-scoped. When source paths, generated artifacts, contracts, scope, or security assumptions change:
+
+1. identify affected prior evidence;
+2. retain it for history;
+3. mark it superseded, invalidated, or requiring rerun with the reason and replacement condition;
+4. run the applicable ATP again;
+5. update the phase index and progress only after the new result is observed.
+
+Do not trust a later progress summary over a contradictory, more recent ATP/artifact record without reconciling chronology and authority. Do not erase failures, expired waivers, or evidence gaps.
+
+## Progress update contract
+
+Update only the selected task/phase’s derived fields unless an authority change was explicitly approved:
+
+- current status;
+- last reviewed revision/date;
+- concise evidence pointer;
+- blocker or waiver details;
+- exact next proof/action;
+- supersession note when prior proof no longer applies.
+
+When the worktree is dirty, record that the result is not reproducible from the base SHA alone and retain an appropriate patch/diff digest. Do not attribute unrelated local changes to the selected task.
+
+A resumable handoff should state:
+
+```text
+WBS / phase:
+Status:
+Revision and worktree:
+Scope and exclusions:
+Authority and ownership:
+Completed gates/evidence:
+Commands/procedures actually run:
+Commands/procedures still required:
+Blocker or decision needed:
+Next single action:
+```
+
+The “next single action” is a handoff, not authorization to execute the next WBS item automatically.

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

@@ -0,0 +1,227 @@
+---
+name: cabloy-spec-generation
+description: This skill should be used for requests to create or maintain a Cabloy `repo-specs/<suite>/` set, including a PRD, SRS, PDP/WBS, test plan, progress register, suite ADR, or “write the specs”/“plan the suite.” It links product, technical, delivery, acceptance, and decision records after the domain boundary is confirmed. Route unresolved naming to `cabloy-domain-planning`, implementation to scaffold skills, and concrete synchronization to `cabloy-contract-loop`.
+---
+
+# Cabloy Repository Specs
+
+Use this skill to create or maintain a coherent, repository-native planning record for a long-lived Cabloy business suite. The output is internal planning material under `repo-specs/`; it is not source code, generated consumer output, or proof that implementation has happened.
+
+## Goals
+
+1. detect the active repository edition before making site, flavor, UI, or topology assumptions;
+2. distinguish a new suite baseline from an extension of an existing spec set;
+3. preserve the authority boundaries demonstrated by the Cabloy spec examples;
+4. generate stable cross-document traceability from product intent to observed evidence;
+5. keep unresolved decisions and unverified work explicit rather than filling gaps with plausible fiction;
+6. hand implementation and contract-loop work to the appropriate existing skill instead of starting it implicitly.
+
+Read these references before generating or substantially revising records:
+
+- `references/repo-specs-document-set.md` for the document architecture and section contracts;
+- `references/repo-aware-discovery.md` for edition detection, repository discovery, and command rules;
+- `references/traceability-and-status-rules.md` for identifiers, evidence, status, and update-order gates.
+
+## Step 1: Detect the repository and edition
+
+From the repository root, inspect:
+
+1. `git rev-parse --show-toplevel` and `git status --short`;
+2. `__CABLOY_BASIC__` and `__CABLOY_START__`;
+3. the root `package.json` and `CLAUDE.md`;
+4. existing `repo-specs/` indexes and related suite/module topology;
+5. `npm run vona` and `npm run zova` when the records will cite implementation commands.
+
+Interpret the markers as follows:
+
+- `__CABLOY_BASIC__` present: use Cabloy Basic source and public-doc assumptions;
+- `__CABLOY_START__` present: use Cabloy Start source and resolve its own licensed-site, UI, flavor, and command details;
+- neither present: do not make strong edition-specific assumptions; inspect the nearby project shape and ask the user to confirm the edition.
+
+Never copy Basic flavor names, SSR assumptions, UI-library assumptions, or exact command lines into a Start record without verifying them in the active Start repository. The document architecture is shared; edition-specific runtime facts are not.
+
+## Step 2: Classify the request
+
+Choose one mode:
+
+### New suite baseline
+
+Use this when the user wants planning records for a new, long-lived business domain. The default output is a complete core set under `repo-specs/<suite-short-name>/`.
+
+### Existing suite extension
+
+Use this when a suite already has a planning directory. Read its README and authority map first. Update the authoritative PRD, SRS, or ADR before downstream WBS, test-plan, progress, or evidence references. Do not silently overwrite existing requirements, decisions, evidence, or status.
+
+### Proportionate planning
+
+A disposable demo, isolated tutorial, or small utility may not warrant the complete seven-document set. Explain the trade-off and offer a smaller record only when the user explicitly wants that scope. A real business domain that is expected to grow defaults to suite-first and the complete baseline.
+
+### Routing to another skill
+
+If the provider, suite, or module identity is unresolved, route to `cabloy-domain-planning` first. If the user wants code generation, route after planning to `cabloy-backend-scaffold` and/or `cabloy-frontend-scaffold`. If the user asks to synchronize a concrete Vona/Zova contract, route that implementation task to `cabloy-contract-loop`. This skill may record those handoff points but does not perform them automatically.
+
+## Step 3: Resolve site strategy when applicable
+
+When the scope includes a Web, Admin, or another user-facing site audience, resolve the high-level site strategy before collecting detailed topology or runtime facts. First use active-repository discovery to identify observed shared-site composition and independent-site conventions for the detected edition. Do not infer that a capability module, Web/Admin audience, or example suite requires a matching independent site.
+
+Evaluate Web and Admin independently. Give a contextual recommendation based on the product audience, authority/experience differences, and source facts actually observed, then present these normal combinations as one single-select decision:
+
+1. shared Web + shared Admin;
+2. independent Web + shared Admin;
+3. shared Web + independent Admin;
+4. independent Web + independent Admin.
+
+Keep the ordinary Other response path available for a custom combination, an audience with no site, or a deferred decision. State that choosing one combination accepts only this site-strategy input; it neither accepts an unrelated durable ADR nor confirms implementation facts.
+
+At this stage, record each audience as a shared existing site, an intended independent suite-owned site, no site, or `TODO(confirm)`. A shared target is valid only when its owning site/composition boundary is observed and cited. An independent strategy is not permission to invent a site ID, public path, bundle, flavor, environment/configuration file, `SsrSite` registration, generated-output location, or development/build/REST command. Keep every unobserved identifier as `TODO(confirm from active source)` for a later frontend WBS/discovery scope.
+
+If the user defers the strategy or needed identifiers, record the unresolved gate in ADR/SRS and mark only frontend/site implementation WBS work that depends on it as `blocked`. Keep runnable source-discovery, backend, known shared-site, and unrelated-audience work accurately `not-started` or at its current status.
+
+## Step 4: Confirm the remaining planning inputs
+
+Ask only for missing information, grouped into a compact clarification pass. Do not treat “make it comprehensive” as permission to invent business or security decisions.
+
+Collect or confirm:
+
+- **Identity:** business domain, `providerId`, `suiteName`, suite short name, stable planning slug, and whether the directory already exists;
+- **Product:** problem, measurable outcomes, personas, primary journeys, and release goal;
+- **Scope:** capabilities in scope, explicit exclusions/deferred work, business rules, and acceptance conditions;
+- **Topology:** likely capability modules, existing module/persistence owners to reuse, audiences, selected shared/independent/deferred site strategy per audience, and any separate application boundary;
+- **Technical constraints:** instance/tenant model, server-authoritative identity, authorization, data ownership, lifecycle/state, transactions, concurrency, idempotency, audit, privacy, integrations, and migration/version concerns where relevant;
+- **Delivery:** dependency order, decision gates, implementation phases, release constraints, and contract-loop checkpoints;
+- **Verification:** required test levels, database/flavor constraints, browser/SSR needs, evidence retention and redaction rules, and release gates;
+- **Durable decisions:** selected site strategy and rationale, accepted boundaries, unresolved trade-offs, ADR candidates, and external-provider operations that may need runbooks.
+
+Repository inspection may fill a fact only when the fact was actually observed. Label it as a confirmed current-source fact and cite its path. Keep observed facts separate from confirmed user inputs, proposed target contracts, and `TODO(confirm from active source)` identifiers.
+
+## Step 5: Validate identity and protect existing records
+
+For a suite-first domain, validate the existing naming convention before writing:
+
+- short name is `{providerId}-{suiteName}`;
+- `suiteName` uses lowercase English letters only and contains no additional hyphen;
+- suite-owned source is intended to live under `vona/src/suite/<suite>/modules/` and `zova/src/suite/<suite>/modules/`;
+- modules name business capabilities rather than vague technical placeholders.
+
+Use the business suite short name as the planning directory when it is the natural scope. For a capability that belongs to an existing suite, use the existing stable suite/capability planning slug instead of creating a duplicate hierarchy.
+
+If `repo-specs/<slug>/` exists, stop before writing and present the conflict. Offer to update the existing authority set, choose a new explicitly justified slug, or stop. Do not overwrite it merely because the user asked for a “fresh” version.
+
+## Step 6: Present the confirmation gate
+
+Before creating or replacing records, summarize and request explicit confirmation of:
+
+- detected edition and source repository;
+- `providerId`, `suiteName`, short name, and output path;
+- intended suite-first Vona/Zova topology and module ownership;
+- product outcome, personas, in-scope capabilities, and deferred scope;
+- the Web/Admin/other-audience site strategy, recommendation/rationale, and every observed shared-site target;
+- tenant, authorization, persistence, site/flavor, and privacy boundaries that are actually confirmed;
+- exact independent-site identifiers that are observed and cited, plus identifiers retained as `TODO(confirm from active source)`;
+- mandatory documents and any optional extensions, with a reason for each;
+- unresolved decisions and explicit `TODO(confirm)` gates, including only the WBS branches blocked by a deferred site decision;
+- the initial status policy: delivery is `not-started` unless implementation evidence already exists;
+- the derived implementation charts: `implementation-gantt.svg` and `implementation-burndown.svg`, whose labels default to the language detected from `README.md`.
+
+Do not treat silence as approval. Once confirmed, generate the records in authority order. Confirmation to generate records does not accept a durable ADR decision: retain its ADR as `Proposed` unless the user explicitly accepts that decision. A site-strategy selection confirms that one planning input only; it does not accept another durable boundary or convert a proposed site ADR into `Accepted`. If the user asks only for a draft, or has not explicitly accepted a durable boundary, retain unresolved decisions and do not imply acceptance.
+
+## Step 7: Generate the mandatory document set
+
+Create this baseline for a new long-lived suite:
+
+```text
+repo-specs/<suite-short-name>/
+├── README.md
+├── prd.md
+├── srs.md
+├── pdp-wbs.md
+├── test-plan.md
+├── progress.md
+├── implementation-gantt.svg
+├── implementation-burndown.svg
+└── decisions/
+    └── 0001-<suite-boundary-slug>.md
+```
+
+Use the templates and authority rules in `references/repo-specs-document-set.md`. In brief:
+
+- `README.md` is the maintainer-facing index, reading order, baseline/topology summary, authority map, and related-record index;
+- `prd.md` owns outcomes, personas, scope, journeys, business rules, product requirements, launch criteria, and `PRD-*` traceability;
+- `srs.md` owns capability/persistence boundaries, data and tenant rules, authorization, state machines, transaction/concurrency/idempotency, API/DTO/OpenAPI, frontend/SSR ownership, nonfunctional contracts, and technical acceptance;
+- `pdp-wbs.md` owns dependency-ordered phases, WBS tasks, completion checks, contract-loop checkpoints, and delivery traceability;
+- `test-plan.md` owns risk priorities, test levels, `ATP-*` scenarios, fixtures, evidence format/redaction, procedures, and release gates;
+- `progress.md` owns derived status, WBS execution rows, blockers, open decisions, evidence pointers, and next proof only;
+- `implementation-gantt.svg` and `implementation-burndown.svg` are deterministic derived views, not authority. They consume `pdp-wbs.md`, `test-plan.md`, and `progress.md`; they must not introduce scope, dependencies, dates, estimates, evidence, or status. Generate them with `npm run spec:charts -- <suite>` and validate them with `npm run spec:charts:check -- <suite>`;
+- chart language defaults to the language detected from `README.md` and applies consistently to visible labels, accessibility text, and metadata;
+- `decisions/0001-*.md` owns the durable initial boundary decision, alternatives, consequences, and decision gates.
+
+Create records in a way that makes every sibling link resolvable from the final directory. Use stable prefixes consistently, such as `PRD-<DOMAIN>-*`, `SRS-<DOMAIN>-*`, `WBS-<DOMAIN>-<PHASE>-*`, and `ATP-<DOMAIN>-*`. Choose a concise domain prefix and use it consistently across all matrices. Define every exact SRS ID used in generated planning records as one formal contract in `srs.md`, and every exact ATP ID as one scenario with a procedure in `test-plan.md`, before any downstream record references it. Wildcards and ranges are compact summaries of already-defined IDs; they never substitute for a formal definition.
+
+## Step 8: Add optional records only when justified
+
+Do not generate optional files because a reference suite contains them. Select them from explicit requirements:
+
+- `presentation-contracts.md`: multiple audiences or Admin Resource scenes need durable information-area, field-boundary, or renderer decisions;
+- `semantic-presentation-rollout.md`: presentation or metadata work is staged, serial, resumable, and needs handoff gates;
+- `runbooks/<provider-or-operation>.md`: a real external provider, webhook, sandbox/live procedure, reconciliation, cutover, or incident operation is in scope;
+- additional ADRs: a separate durable security, tenancy, ownership, site/flavor, migration, integration, or scope decision exists;
+- `evidence/`: create only when actual ATP execution produces retained redacted evidence, not as an empty completeness signal.
+
+Optional records remain subordinate to the PRD/SRS/WBS/test-plan authority appropriate to their content. A presentation matrix cannot authorize an API or redefine persistence; a runbook cannot redefine a payment state machine; a rollout record cannot replace the WBS or test plan.
+
+## Step 9: Apply Cabloy-specific contract guardrails
+
+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;
+- 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;
+- specify transactions, concurrency, idempotency, audit, recovery, and historical snapshots when the business flow needs them;
+- for fullstack work, record the Vona-to-Zova forward chain and Zova-to-Vona reverse-chain checkpoint, but hand actual generation/synchronization to `cabloy-contract-loop`;
+- when Admin Resource and Web self-service consume one resource with different authority or audience, separate API/DTO contracts, server scope, state owners, and pages while retaining one domain/persistence boundary;
+- independent site composition does not create an independent persistence, tenant, identity, authorization, or domain-rule authority; shared composition does not make generic CRUD, client-side admission, or identical audience contracts sufficient;
+- an Admin-facing module alone does not authorize an independent Admin site, `SsrSite` registration, flavor, environment/configuration file, bundle, or root command;
+- ask before choosing whether a persisted-field change increments `vonaModule.fileVersion`; do not silently invent migration history;
+- use `TODO(confirm from active source)` and neutral placeholders for unobserved runtime facts; never copy site/flavor details, example-suite entities, routes, tests, CI links, or evidence into a new domain.
+
+## Step 10: Quality-check the document set
+
+Before reporting completion, verify:
+
+1. each applicable Web, Admin, or other site audience has a stated shared, independent, no-site, or `TODO(confirm)` strategy; every shared target is cited, and every unknown independent-site runtime identifier remains `TODO(confirm from active source)`;
+2. deferred site strategy or identifiers block only the dependent frontend/site WBS branch, while unrelated backend and actionable audience work remains accurately statused;
+3. every in-scope `PRD-*` requirement maps to an `SRS-*` contract, a `WBS-*` task, and an `ATP-*` scenario;
+4. every SRS contract maps backward to a product requirement and forward to planned delivery/proof;
+5. every WBS item has dependencies, a bounded task, completion checks, and expected ATP coverage;
+6. every ATP has traceability, procedure/scope, minimum proof, and evidence-retention rules;
+7. `progress.md` contains only derived status and never introduces requirements or contracts;
+8. no downstream file silently changes an upstream product, technical, or ADR decision;
+9. every `verified` claim has observed revision, environment, exact command/procedure, result, and redacted evidence location;
+10. initial rows remain `not-started`, `deferred`, or explicitly `blocked` unless existing observed evidence was intentionally carried forward;
+11. every exact `PRD-*`, `SRS-*`, `WBS-*`, and `ATP-*` reference in the planning authority set resolves to exactly one formal definition in its owning document; ranges and wildcards are aggregation notation only and cannot satisfy this check;
+12. README language distinguishes observed facts, confirmed inputs, proposed targets, and `TODO(confirm)` decisions, and does not upgrade a `Proposed` ADR into a confirmed or accepted durable boundary;
+13. `npm run spec:charts:check -- <suite>` passes, proving every WBS task has one progress row, statuses and dependencies reconcile, ATP references resolve, and both generated SVGs are current;
+14. chart language and accessibility/metadata text follow the README language policy;
+15. local Markdown links and referenced paths resolve;
+16. prospective commands are real commands discovered in the active repository, or clearly marked as commands to confirm later.
+
+If the exact-ID, status-consistency, or chart check fails, correct the authoritative planning records or regenerate the derived artifacts and rerun it before reporting generation complete. This is a static planning check, not ATP execution: do not create evidence or claim `verified` for it.
+
+After creating or changing `pdp-wbs.md`, `test-plan.md`, or `progress.md`, regenerate both derived views with `npm run spec:charts -- <suite>` and then run `npm run spec:charts:check -- <suite>`. A chart change never authorizes a planning or status change. If a later edit occurs outside this workflow, the check command is the source of truth for detecting stale views.
+
+Do not run `npm run init`, reset a database, scaffold code, or execute deployment/provider operations as an automatic consequence of writing planning records. Do not report those activities as evidence.
+
+## Step 11: Handoff and response
+
+Report:
+
+- detected edition and output directory;
+- files created or updated;
+- optional files intentionally omitted and why;
+- unresolved decisions and the next confirmation needed;
+- initial status and evidence limitations;
+- recommended next workflow (`cabloy-domain-planning`, backend/frontend scaffold, or `cabloy-contract-loop`);
+- generated or refreshed `implementation-gantt.svg` and `implementation-burndown.svg`, selected README language, and the result of `npm run spec:charts:check -- <suite>`.
+
+Keep the result practical. A good spec set gives the next implementer a shared authority map, not a fictional completion report.

package/.claude/skills/cabloy-spec-generation/evals/evals.json

@@ -0,0 +1,83 @@
+{
+  "skill_name": "cabloy-spec-generation",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to create the complete repo-specs set for a new CRM suite in this Cabloy repository. The suite name and provider prefix are not decided yet. Please guide me through the right process and tell me what you need before writing files.",
+      "expected_output": "Detects the edition and repository context, routes unresolved suite naming to cabloy-domain-planning, asks for grouped missing inputs, and does not invent CRM requirements or create a fictional document set.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "The Cabloy Basic repository is confirmed. Create a planning baseline for suite a-training (providerId a, suiteName training). It will include student, course, and attendance capabilities for authenticated Web users and tenant Admin operators. Define the initial scope as course browsing, enrollment, attendance recording, and operator management; defer payments and certificates. Produce the repository-native PRD, SRS, PDP/WBS, test plan, progress register, README authority map, and initial suite-boundary ADR, but do not claim implementation or test evidence.",
+      "expected_output": "Uses repo-specs/a-training with the seven mandatory core records, suite-first Vona/Zova topology, stable PRD/SRS/WBS/ATP identifiers and traceability, explicit deferred scope, server-side tenant/authorization and contract-loop boundaries, and not-started progress without fabricated evidence.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Plan a new Cabloy Start business suite with an Admin application, several resource scenes that need different field groupings and renderers, and a real payment provider with sandbox/live webhooks and reconciliation. The suite identity and exact Start flavor/site names are confirmed in the active Start repo. Which spec files should be generated, and what must remain conditional or evidence-backed?",
+      "expected_output": "Keeps the shared core set, adds presentation-contracts and a provider runbook only because the supplied scope justifies them, uses Start-specific facts from the active repo rather than Basic assumptions, explains when a rollout record or additional ADR is warranted, and requires redacted observed evidence before verified status.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The design is complete, so write all suite specs and mark every WBS phase verified. There is no test run yet. Please make the progress document look release-ready.",
+      "expected_output": "Refuses to claim verified status without retained ATP evidence, initializes progress as not-started or otherwise accurate, explains the revision/environment/procedure/result/redaction requirements, and does not create empty evidence records.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Our existing suite PRD says the first release is one tenant and no marketplace. I want to add an OpenSpec directory and update the WBS directly to support multiple merchants. How should the repository planning records change?",
+      "expected_output": "Treats the existing PRD and repository-native records as authoritative, rejects a parallel OpenSpec authority absent a new repository-level decision, requires the product/technical/ADR authority to change first, and then propagates updates to WBS, ATP, progress, and evidence assumptions.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Create a complete planning baseline for a new inventory suite. In the WBS, refer to SRS-INV-STOCK-01 and ATP-INV-CON-01 even if the SRS and test plan only mention those IDs in a matrix or generic prose. Do not add implementation or evidence.",
+      "expected_output": "Defines every exact SRS ID used downstream as an explicit SRS contract and every exact ATP ID as a test-plan scenario with traceability, setup, procedure, expected result, and minimum proof. It treats wildcard/range/matrix mentions as aggregation notation rather than definitions, runs a static planning-authority ID audit before completion, and does not create evidence for that audit.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Draft a new suite baseline with an unresolved tenancy boundary. Keep ADR 0001 Proposed, but title the README section Confirmed Product and Technical Baseline so it reads more decisively.",
+      "expected_output": "Keeps ADR 0001 Proposed absent explicit acceptance and uses neutral README baseline wording that distinguishes observed facts, confirmed inputs, proposed targets, and TODO(confirm) decisions. It refuses to let README language upgrade the proposed durable boundary, keeps delivery status accurate, and does not fabricate evidence.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "Generate a proposed suite baseline with an optional payment-provider runbook. The user confirms the planning inputs and output path but has not accepted the provider boundary ADR. The runbook traceability table names ATP-PAY-WEBHOOK-01, but the test plan does not define that scenario.",
+      "expected_output": "Treats confirmation to generate records as distinct from accepting the ADR, retains the provider boundary as Proposed, and uses neutral README wording. It scans the optional runbook as a generated non-evidence record, rejects the dangling ATP-PAY-WEBHOOK-01 reference until a formal test-plan scenario exists, and does not create execution evidence.",
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "Create a new long-lived suite baseline and keep its README in Chinese. Generate the complete records without implementation evidence.",
+      "expected_output": "Creates both implementation-gantt.svg and implementation-burndown.svg, initializes statuses accurately, uses the README language consistently in chart labels/accessibility/metadata, and does not fabricate dates, estimates, history, or verified evidence.",
+      "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "A later WBS dependency, ATP reference, or progress status changes after the charts were generated. Update the affected authority/status record and finish without regenerating the SVGs.",
+      "expected_output": "Regenerates both derived charts with npm run spec:charts -- <suite>, runs npm run spec:charts:check -- <suite>, and treats stale or dangling chart references as a static failure rather than changing authority to make the chart pass.",
+      "files": []
+    },
+    {
+      "id": 11,
+      "prompt": "Plan a new long-lived suite with a reader-facing Web experience and staff Admin operations. The active repository has not yet told us whether either audience should use a shared site or an independent suite-owned site. Do not guess flavor names or commands.",
+      "expected_output": "Performs edition-aware source discovery before choosing topology, evaluates Web and Admin independently, makes a contextual recommendation, and presents the four normal shared/independent Web/Admin combinations in one single-select decision with the ordinary Other path available for a custom strategy or deferral. It requires a cited observed shared target, keeps unobserved site/flavor/env/SsrSite/command identifiers as TODO(confirm from active source), and does not fabricate Basic or Start facts.",
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "For the confirmed Cabloy Basic suite strategy, choose an independent reader Web site and integration into an observed shared Admin site. The independent reader site is intended, but active source has not yet confirmed its site ID, public path, bundle, flavor, environment/configuration, SsrSite registration, or paired commands. Generate the planning records only.",
+      "expected_output": "Propagates the mixed strategy through the authority chain: PRD describes audience/channel scope, SRS owns topology and audience-specific contracts, ADR records the durable boundary subject to its status, WBS separates independent-Web delivery from shared-Admin integration, test-plan defines only source-confirmed proof, and progress remains derived. It preserves every missing independent identifier as TODO(confirm from active source), cites the shared Admin target, avoids creating source/config/scripts, and does not imply separate persistence, tenancy, identity, or authorization ownership.",
+      "files": []
+    },
+    {
+      "id": 13,
+      "prompt": "Create a suite baseline where the product needs backend catalogue work plus future Web and Admin experiences, but the user defers the Web/Admin site strategy and all site identifiers. Keep backend planning available.",
+      "expected_output": "Retains the site strategy as a governing ADR/SRS TODO(confirm), marks only dependent frontend/site implementation WBS work blocked, and keeps backend plus any runnable source-discovery work accurately not-started or unchanged. It does not globally block delivery, invent site/flavor/env/configuration/build facts, create implementation evidence, or mark planning/source discovery as verified.",
+      "files": []
+    }
+  ]
+}