npm - cabloy - Versions diffs - 5.1.194 → 5.1.196 - Mend

cabloy 5.1.194 → 5.1.196

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/repo-agent-governance/skills/cabloy-spec-generation/SKILL.md CHANGED Viewed

@@ -1,227 +1,137 @@
 ---
 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`.
+description: Use this skill to create or maintain Cabloy suite specifications under repo-specs, including PRD, SRS, PDP/WBS, acceptance planning, progress, and suite ADRs. It supports a complete new baseline, incremental maintenance, and explicitly lightweight planning. Route unresolved naming through cabloy-domain-planning and return here; hand approved bounded implementation to cabloy-spec-execution, not directly to broad scaffolding.
 ---
 # 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.
+Create or maintain repository-native planning authority. Planning is not source implementation, acceptance evidence, ADR acceptance, or execution authorization.
-## Goals
+Read before substantial generation or revision:
-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.
+- `references/repo-aware-discovery.md`: edition, source discovery, and observed versus new target semantics;
+- `references/repo-specs-document-set.md`: authority and proportionate document architecture;
+- `references/canonical-spec-input.md`: canonical declarations, parser compatibility, and the three quality gates;
+- `references/traceability-and-status-rules.md`: stable IDs, evidence, and authority-first updates.
-Read these references before generating or substantially revising records:
+## 1. Discover the active repository
-- `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.
+Inspect the root, working tree, edition markers, root `package.json`, existing `repo-specs/` indexes, relevant suite/module topology, and authored governance. Discover `npm run vona` / `npm run zova` command families when planning cites implementation commands.
-## Step 1: Detect the repository and edition
+- Exactly `__CABLOY_BASIC__`: use observed Basic scripts, UI, sites, flavors, and output paths.
+- Exactly `__CABLOY_START__`: resolve those details from the active Start source; do not copy Basic examples.
+- Both markers: stop; the checkout is invalid or ambiguous.
+- Neither: inspect the owning package and nearby structure, then ask before edition-sensitive planning.
-From the repository root, inspect:
+Cite inspected paths. Keep repository facts separate from user inputs, target design, and evidence. Never read or expose `.env*` contents to recommend worktree identity or ports.
-1. `git rev-parse --show-toplevel` and `git status --short`;
-2. `__CABLOY_BASIC__` and `__CABLOY_START__`;
-3. the root `package.json` and `repo-agent-governance/` (or the active generated adapter);
-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.
+## 2. Choose one planning mode
-Interpret the markers as follows:
+| Mode | Scope and protection | Quality branch |
+| --- | --- | --- |
+| Complete new baseline | New long-lived suite: six core Markdown records plus initial ADR; both charts after complete chart inputs exist. | Full `spec:check`, then chart generation/freshness, then human decision/status review. |
+| Incremental maintenance | Read the existing README/authority map; update affected upstream authority and downstream links only. Preserve IDs, accepted decisions, evidence, and unrelated statuses. | Full audit when the authority set is complete; report legacy gaps separately. Charts only with complete supported inputs. |
+| Lightweight planning | Explicitly approved small demo, utility, or limited planning scope. Agree on selected records, omitted owners, limits, and no implied full-suite closure. | `spec:check --lightweight` for available owners/references/links; manually review the limited chain. No forced full set or charts with incomplete inputs. |
-- `__CABLOY_BASIC__` present: use Cabloy Basic source and public-doc assumptions;
-- `__CABLOY_START__` present: use Cabloy Start source and resolve its own 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.
+An existing directory is the normal incremental destination, not an automatic conflict. Ask about a conflict only for a genuine identity collision, parallel authority, or requested destructive replacement. Do not reset the directory or regenerate the whole baseline by default.
-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.
+A growing business domain defaults to the complete baseline. Ask before choosing lightweight scope. Do not invent requirements to fill omitted documents.
-## Step 2: Classify the request
+## 3. Resolve identity without changing the workflow
-Choose one mode:
+For unresolved provider/suite/module naming, route to `cabloy-domain-planning` with a **naming-only return to generation**. Validate the returned names and resume this mode and its confirmation gate. Naming confirmation does not authorize source scaffolding.
-### New suite baseline
+For suite-first ownership, the short name is `{providerId}-{suiteName}`; `suiteName` uses lowercase English letters only, without another hyphen. Use capability names for modules. Reuse the stable existing suite/capability planning slug rather than creating a competing hierarchy.
-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>/`.
+## 4. Resolve only missing site strategy
-### Existing suite extension
+First inspect active shared-site composition owners, extension points, independent-site conventions, and framework constraints. A capability module or an Admin audience alone does not require an independent site.
-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.
+- If both Web and Admin strategies are unresolved, evaluate them separately, recommend contextually, and present one single-select decision: shared/shared, independent/shared, shared/independent, independent/independent. Keep Other for custom/no-site/deferred choices.
+- If only one audience is in scope or unresolved, ask only about that audience.
+- If an established strategy already governs the requested change, preserve it; do not repeat the four-way question absent a material change.
-### Proportionate planning
+Choosing strategy confirms only that input. It does not accept an ADR or approve implementation.
-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.
+Classify every target as **observed existing**, **proposed new**, or **explicitly approved new** under the discovery reference. Shared integration requires an observed owner. A proposed independent tuple may be designed before its source exists: validate framework constraints and collisions, obtain explicit design approval, and retain its governing ADR as `Proposed` until separately accepted. An explicitly approved new tuple with an `Accepted` ADR can be created by a bounded execution task; source pre-existence is not a prerequisite.
-### Routing to another skill
+Unknown or unchecked values stay `TODO(confirm)` with the exact missing design/source/conflict check. Block only dependent site/frontend implementation; keep backend, unrelated audiences, and runnable discovery tasks actionable.
-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.
+## 5. Collect the remaining inputs
-## Step 3: Resolve site strategy when applicable
+Ask only for missing inputs in a compact clarification pass:
-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.
+- identity/output path, outcomes, personas, journeys, scope, exclusions, and acceptance;
+- modules and reused persistence/identity owners; audience strategy and target classification;
+- tenant, server-authoritative identity/authorization, privacy, lifecycle, transactions, concurrency, idempotency, audit, integrations, and migration/version decisions where material;
+- dependencies, release constraints, contract-loop checkpoints, test levels, fixture cleanup, proof/redaction, and optional records;
+- durable decisions, ADR candidates, and unresolved gates.
-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:
+Label recommendations as proposals. A request for comprehensiveness is not permission to invent security or business decisions.
-1. shared Web + shared Admin;
-2. independent Web + shared Admin;
-3. shared Web + independent Admin;
-4. independent Web + independent Admin.
+## 6. Confirm generation scope
-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.
+Before writing, present the edition/root, mode, identity/path, intended ownership, outcomes/scope, site strategy/target tuple classification, affected records, justified omissions/extensions, unresolved gates, and initial status/evidence policy. Include planned chart eligibility and README language.
-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.
+Keep three approvals separate:
-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.
+1. **Generation approval** authorizes the named planning edits only.
+2. **Design/ADR approval** explicitly approves a durable decision; record `Accepted` only for the decision actually accepted. A tuple design approval is not source-existence proof.
+3. **Execution approval** belongs to a bounded WBS dossier in `cabloy-spec-execution`.
-## Step 4: Confirm the remaining planning inputs
+Do not treat silence, strategy selection, naming confirmation, or generation approval as another approval. Drafts retain `Proposed` ADRs and controlling `TODO(confirm)` gates.
-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.
+## 7. Write authority first
-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:
+For a complete new baseline, create:
 ```text
-repo-specs/<suite-short-name>/
+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-<suite-boundary-slug>.md
+└── decisions/0001-<boundary>.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.
+With complete supported chart inputs, generate `implementation-gantt.svg` and `implementation-burndown.svg` as derived views. Use canonical declarations in `references/canonical-spec-input.md` for new records. Each exact PRD/SRS/WBS/ATP ID has one definition in its owner, not merely a matrix, range, or evidence mention.
-## Step 8: Add optional records only when justified
+For updates, change PRD/SRS/ADR first, then mappings, WBS, ATP, evidence assumptions, and progress. Preserve stable IDs and history. Legacy catalogue tables remain compatible; missing formal definitions are a reported legacy gap, not permission to invent business meaning or rewrite legacy business records to satisfy a tool.
-Do not generate optional files because a reference suite contains them. Select them from explicit requirements:
+Add presentation contracts, rollout records, runbooks, extra ADRs, or evidence only when confirmed scope justifies them. Never create empty evidence or fabricate an `EVD-*` record.
-- `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.
+## 8. Preserve Cabloy boundaries
-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.
+- Keep suite business planning in `repo-specs/`, public/agent guidance in `repo-docs/`, and supporting maintainer rationale in `repo-docs-internal/`.
+- Reuse persistence and identity ownership. An independent site does not create a separate tenant, identity, authorization, persistence, or domain-rule authority.
+- Treat the active Vona instance as tenant by default. Authorization and scope are server-authoritative, not menus or browser filters.
+- Separate genuinely different Admin/Web API/DTO, server-scope, frontend state, and page contracts while retaining one domain/persistence boundary.
+- Plan forward and reverse contract-loop checkpoints; actual regeneration belongs to the specialist invoked by execution. Never hand-edit generated consumers.
+- Ask before choosing the persisted-field `vonaModule.fileVersion` strategy.
+- A new wrapper is a **planned addition**, not a currently runnable command. Validate its durable manifest destination and paired SSR/REST design; execution must create and observe it before running it.
-## Step 9: Apply Cabloy-specific contract guardrails
+## 9. Apply three independent quality gates
-While drafting, preserve these principles and tailor them to confirmed scope:
+Use the active root scripts, verified from `package.json`:
-- `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; `repo-agent-governance/skills/` is authored 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;
-- 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.
+```bash
+npm run spec:check -- <suite>
+# Explicit lightweight branch:
+npm run spec:check -- <suite> --lightweight
+```
-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.
+1. **Planning authority audit**: `spec:check` validates definition roles, exact references, PRD -> SRS -> WBS -> ATP associations, and local links. Explicit Traceability belongs in declaration bodies. Review gaps and decisions manually; a static pass is not design acceptance.
+2. **Chart model/freshness**: only with complete supported README/WBS/ATP/progress inputs, run `npm run spec:charts -- <suite>` then `npm run spec:charts:check -- <suite>`. This proves supported model consistency and SVG freshness only. Regenerate after WBS, test-plan, progress, or README title/language changes. No complete input means an explicit chart omission/blocker, not invented definitions or status.
+3. **Human approval/evidence**: review ADR status, controlling TODOs, scope, and evidence-backed status. Only retained applicable ATP proof can justify `verified`; neither audit nor charts can approve a design or implementation.
-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.
+For incremental legacy gaps, report the missing definition/owner/link and affected chain without silently changing business meaning. If correction needs a new decision, request it and report the update as incomplete at that gate. Lightweight results must state skipped owners/chain coverage; never advertise a full-suite pass.
-## Step 11: Handoff and response
+Planning creation alone initializes delivery as `not-started`, `deferred`, or specifically `blocked`. Preserve carried-forward observed evidence with its revision/authority limits. Do not run init, database reset, scaffolding, deployment/provider operations, or acceptance tests as an automatic consequence of planning.
-Report:
+## 10. Finish with a bounded execution handoff
-- 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>`.
+Report edition/mode/path, files changed, omissions, unresolved decisions, approval domains, actual audit results, chart eligibility/freshness/language, and evidence limitations. Identify one candidate WBS increment or finite phase and its dependencies, acceptance proof, and controlling gates.
-Keep the result practical. A good spec set gives the next implementer a shared authority map, not a fictional completion report.
+The next implementation entry is `cabloy-spec-execution`, which still requires explicit target/dossier approval. Do not jump directly from generation to broad backend/frontend scaffolding, execute an adjacent task, or claim release closure.

package/repo-agent-governance/skills/cabloy-spec-generation/evals/evals.json CHANGED Viewed

@@ -5,79 +5,227 @@
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Reads active edition and repository before assumptions.",
+        "Routes unresolved names through naming-only domain planning and returns to generation.",
+        "Asks grouped missing inputs without writing or scaffolding before approval."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Confirms complete-baseline scope and generation separately from ADR acceptance.",
+        "Uses stable formally defined PRD/SRS/WBS/ATP IDs and exact declared associations.",
+        "Initial status is accurate; no invented execution evidence or source existence."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Reads active Start facts rather than borrowing Basic runtime identifiers.",
+        "Adds presentation/runbook records only for explicit scope.",
+        "Retains provider operation and proof gates; planned commands are not passing results."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Rejects verified status without actual retained ATP proof.",
+        "Does not fabricate artifacts or empty evidence records.",
+        "Keeps status and next proof accurate despite release-ready wording request."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Reads existing authority and preserves stable identity/history.",
+        "Requires upstream PRD/SRS/ADR approval before downstream merchant-scope changes.",
+        "Does not introduce parallel OpenSpec authority without repository-level decision."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Defines exact SRS and ATP records in their owners rather than counting matrix/prose mentions.",
+        "ATP declaration has substantive Setup, Procedure, Expected result, Minimum proof, and Traceability.",
+        "Separates authority audit, chart gate, and human approval/evidence."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Retains Proposed ADR and controlling tenancy TODO.",
+        "Uses neutral README wording without upgrading proposed durable decisions.",
+        "Generation approval does not count as ADR acceptance or execution approval."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Audits optional non-evidence runbook references.",
+        "Reports missing ATP definition rather than using a matrix/evidence row as definition.",
+        "Keeps provider ADR Proposed without separate explicit acceptance."
+      ]
     },
     {
       "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": []
+      "expected_output": "With complete supported chart inputs, 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": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "With complete supported input, generates both derived views using README language.",
+        "Canonical declarations and progress header names match the new input contract.",
+        "No fabricated dates, estimates, history, or verified proof."
+      ]
     },
     {
       "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": []
+      "expected_output": "With complete supported chart inputs, 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": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Changes authority/status first, then regenerates/checks both eligible charts.",
+        "Reports chart model/freshness separately from authority audit and ATP proof.",
+        "Does not hand-edit SVGs or invent definitions to satisfy charts."
+      ]
     },
     {
       "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": []
+      "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 unknown or unchecked tuple values as explicit TODO(confirm) design/discovery gates, and does not fabricate Basic or Start facts.",
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "When both audiences are unresolved, offers contextual four-way single-select plus Other.",
+        "Shared targets are inspected/cited; new designs are labeled proposed rather than observed.",
+        "Leaves unchecked values gated without assuming Basic/Start tuple details."
+      ]
     },
     {
       "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": []
+      "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 gates proof on observed commands or approved-new command creation, and progress remains derived. It retains unspecified or unchecked tuple values as explicit TODO(confirm) design/discovery gates, cites the shared Admin target, avoids creating source/config/scripts, and does not imply separate persistence, tenancy, identity, or authorization ownership.",
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Keeps mixed strategy and separates independent-Web creation from shared-Admin integration.",
+        "Unspecified tuple values remain explicit design/discovery gates, not fabricated facts.",
+        "Allows a future validated explicitly approved new design without requiring pre-existing source; no implementation now."
+      ]
     },
     {
       "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": []
+      "files": [
+        "files/scenarios.json"
+      ],
+      "expectations": [
+        "Blocks only dependent site/frontend implementation branches.",
+        "Preserves actionable backend/discovery status without inventing site facts.",
+        "Deferred strategy remains controlling TODO/ADR gate rather than globally blocking every task."
+      ]
+    },
+    {
+      "id": 14,
+      "prompt": "Plan a new independent Web-only training site. Candidate tuple: flavor evalTrainingWeb, site ID evalTrainingReader, public path /eval-training, site module training-site, bundle derived from the inspected release rule, and root wrapper build:zova:eval:training:web as a planned addition. These are proposals, not current source facts. Inspect active framework constraints and collisions; then show the concrete design and generation gates. In follow-up I will separately approve the tuple, accept its ADR, and approve only one bounded execution dossier. Do not demand that future source already exists.",
+      "expected_output": "Validates the candidate tuple against active framework/source constraints and collisions, separates proposed from approved-new state, and permits later bounded creation only with explicit design approval, Accepted ADR, and execution dossier approval. The new wrapper remains a planned addition until created/observed.",
+      "expectations": [
+        "Inspects active constraints and collisions without treating fixture candidates as source truth.",
+        "Single Web audience does not trigger redundant Web/Admin four-way question.",
+        "Generation approval alone does not accept the ADR or authorize creation.",
+        "After separate design approval and Accepted ADR, future source absence alone is not a blocker; execution remains bounded.",
+        "New wrapper is never presented as currently runnable."
+      ],
+      "files": [
+        "files/scenarios.json"
+      ]
+    },
+    {
+      "id": 15,
+      "prompt": "Update one approved requirement in an existing repo-specs suite. Read its authority map; keep existing IDs, evidence, accepted shared-site strategy, and unrelated progress. The directory already exists because this is an incremental change, not a request to reset or recreate it. Show the proposed diff and confirmation gate first.",
+      "expected_output": "Uses incremental maintenance, preserves established strategy and history, asks only for missing delta decisions, updates upstream authority before downstream associations, and reports legacy gaps without altering business definitions for tools.",
+      "expectations": [
+        "Existing directory is normal update destination, not automatic conflict.",
+        "No directory reset, baseline recreation, ID renumbering, or unrelated status change.",
+        "Established strategy skips redundant four-way choice.",
+        "Legacy audit/chart gaps are distinct and not repaired by invented business meaning."
+      ],
+      "files": [
+        "files/scenarios.json"
+      ]
+    },
+    {
+      "id": 16,
+      "prompt": "This is an explicitly lightweight backend-only tutorial planning request, not a long-lived suite. Agree on README plus one PRD requirement only; omit SRS/WBS/ATP/progress/ADR and charts. Do not create placeholders for omitted owners. Confirm the limited output, then use the appropriate audit branch and report its limits.",
+      "expected_output": "Confirms explicitly lightweight scope, creates only approved records, runs positional spec:check with --lightweight, reports omitted full-chain coverage, and skips charts for incomplete input without fabricating owners or proof.",
+      "expectations": [
+        "Uses npm run spec:check -- <suite> --lightweight only after scope approval.",
+        "Omitted owners are stated; no dangling references or phantom declarations.",
+        "No forced full baseline, empty progress/evidence, or charts with incomplete input.",
+        "Static lightweight pass is not full-chain or behavioral/ATP success."
+      ],
+      "files": [
+        "files/scenarios.json"
+      ]
+    },
+    {
+      "id": 17,
+      "prompt": "I invoked spec generation for a new CRM baseline, but provider/suite names need validation first. Use domain planning only to settle names. After I confirm the naming option, return to the baseline conversation; do not scaffold a suite/module or run contract generation.",
+      "expected_output": "Uses a naming-only domain-planning detour, returns validated identity to the original generation mode, and requires generation/ADR/execution approvals separately before any later implementation.",
+      "expectations": [
+        "Domain planning is explicitly naming-only and returns to generation.",
+        "Naming confirmation does not trigger scaffold or dependency commands.",
+        "Generation resumes mode/input collection and its own confirmation gate.",
+        "Final implementation handoff is one bounded spec-execution candidate, not broad direct scaffold."
+      ],
+      "files": [
+        "files/scenarios.json"
+      ]
     }
   ]
 }