@kudusov.takhir/ba-toolkit 3.4.1 → 3.6.0

package/CHANGELOG.md

@@ -11,6 +11,90 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.6.0] — 2026-04-10
+
+### Highlights
+
+- **Group A skill audit pass on `/usecases`, `/ac`, `/nfr`, `/datadict`, `/apicontract`, `/wireframes`, `/scenarios`** — 7 pipeline-core skills brought to the same senior-BA rigour as the v3.5.0 pilot. ~32 Critical + High findings applied. The same six systemic patterns surfaced in the pilot are now fixed across the entire pipeline core: full standards conformance (Cockburn for use cases, ISO 25010 for NFRs, OpenAPI shape for the API contract), explicit "why" fields (Source / Owner / Sensitivity / Verification) on every artifact element, cross-artifact forward-traceability matrices on every shipped artifact, document-control metadata, single-source-of-truth templates with no inline drift, and required-topics lists extended with universal BA inquiries.
+
+### Changed
+
+- **`skills/usecases/SKILL.md` and `skills/references/templates/usecases-template.md`** — full Cockburn alignment:
+  - Inline template removed from SKILL.md; the standalone `usecases-template.md` is now the single source of truth (mirror of the same drift fix applied to `/stories` in v3.5.0).
+  - Cockburn-mandated fields added to every UC: **Goal in Context** (which Brief goal G-N this UC serves), **Stakeholders and Interests** table (Cockburn discipline — surfaces non-obvious requirements that the primary actor alone misses), **Scope** (system / subsystem / component, distinct from Level), **Source** (which US/FR drove this UC into existence), **Success Guarantees** vs **Minimal Guarantees** (post-conditions split per Cockburn — what's true after success vs what's true after *any* termination including failure).
+  - Required-topics list extended from 5 to 8: Goal in Context, Stakeholders and Interests, Scope level added.
+  - New US → UC coverage matrix at the bottom of the artifact for forward traceability with `(uncovered)` flagging.
+- **`skills/ac/SKILL.md` and `skills/references/templates/ac-template.md`** — explicit AC-NNN-NN ID scheme (drift fix), provenance fields, US → AC coverage matrix:
+  - Inline template removed; standalone is the single source of truth. Inline used `### AC-NNN-NN` IDs while standalone used `### Scenario N` without numeric IDs — different ID schemes between the two templates.
+  - Every AC carries **Type** (Positive / Negative / Boundary / Performance / Security), **Source** (which business rule from `02_srs_*.md` drove the AC — required, no AC without provenance), **Verification** (Automated test / Manual test / Observed in production), **Linked FR**, and **Linked NFR** (for performance and security ACs).
+  - Required-topics list extended from 5 to 9: performance bounds per scenario, idempotency, observability (audit log requirements), state transitions linking AC to entity state machines.
+  - New US → AC coverage matrix at the bottom — forward traceability with column per AC type so `Must` stories with no negative or no boundary AC are flagged at glance.
+- **`skills/nfr/SKILL.md` and `skills/references/templates/nfr-template.md`** — full ISO/IEC 25010 alignment, FR → NFR matrix:
+  - **Standard alignment with ISO/IEC 25010:2011** Software Quality Model — every NFR maps to one of the 8 ISO 25010 characteristics: Functional Suitability, Performance Efficiency, Compatibility, Usability, Reliability, Security, Maintainability, Portability. Project-specific extensions (Compliance, Localisation, Observability) explicitly note their parent ISO characteristic so the audit trail is consistent. Previous version named ad-hoc categories without standard backing.
+  - Each NFR template gains an **Acceptance threshold** field separate from the metric — "metric: p95 latency in ms" + "acceptance threshold: < 300ms" — so verification is unambiguous.
+  - Required-topics list extended from 6 to 13: ISO 25010 characteristic-by-characteristic walk plus SLO/SLI commitment, observability, disaster recovery runbook, data sovereignty, deprecation policy.
+  - New FR → NFR coverage matrix flags Must FRs with no linked Performance / Reliability / Security NFR.
+  - New per-characteristic priority summary table at the bottom.
+- **`skills/datadict/SKILL.md` and `skills/references/templates/datadict-template.md`** — logical model only, provenance, state machines, FR → Entity matrix:
+  - **Scope boundary made explicit:** `/datadict` is the **logical** data model (entities, attributes, conceptual types, relationships, state transitions). Physical schema (specific DBMS, indexes, sharding, partitioning) belongs in `/research` (step 7a) as ADRs. Previous version mixed the two by asking "DBMS choice" as a required topic.
+  - Each entity carries **Source** (which FR/US introduced it — required, no entity without provenance), **Owner** (which team curates it), **Sensitivity** (Public / Internal / Confidential / PII / PCI / PHI / Financial — feeds /nfr Security NFRs and GDPR compliance), and a **State Machine** section listing states + legal transitions for any entity with more than two distinct lifecycle states.
+  - Required-topics list extended from 6 to 10: PII inventory and retention policy, audit/history requirements, state machines, referential integrity cascade rules, time-zone handling, data ownership.
+  - Logical types replace DBMS-specific types (`String / Integer / Decimal / Boolean / Timestamp / UUID / Enum / FK / JSON / Binary` instead of `ObjectId / VARCHAR / NUMERIC`). Physical type mapping happens in `/research`.
+  - New FR → Entity coverage matrix at the bottom flags data-touching FRs with no linked entity.
+- **`skills/apicontract/SKILL.md` and `skills/references/templates/apicontract-template.md`** — OpenAPI 3.x shape, idempotency, FR → Endpoint matrix:
+  - **Standard alignment with OpenAPI 3.x** structure (servers, paths, parameters with `in` location, request body, responses keyed by HTTP status, components/schemas, security schemes). Markdown is the format, OpenAPI is the shape.
+  - Per-endpoint metadata table now carries **Source** (FR/US — required), **Required scope** (OAuth2 / JWT scope), **Idempotency** (Idempotent / Not idempotent / Idempotent via `Idempotency-Key` header), per-endpoint **Rate limit**, per-endpoint **SLO** (latency target linked to NFR), and **Verification** method (contract test / consumer-driven contract test / integration test).
+  - Required-topics list extended from 7 to 12: idempotency keys, content negotiation, CORS policy, API deprecation policy with `Sunset` header (RFC 8594), per-endpoint SLO.
+  - New "Idempotency, CORS, and Deprecation" section in the template documents the cross-cutting policies.
+  - New FR → Endpoint coverage matrix flags FRs with no linked endpoint.
+- **`skills/wireframes/SKILL.md` and `skills/references/templates/wireframes-template.md`** — canonical 8-state list, accessibility-first, US → WF matrix:
+  - **Mandatory state list expanded from 4 to 8** canonical states: Default, Loading, Empty, Loaded, Partial, Success, Error, Disabled. The previous 4-state minimum (default / loading / empty / error) missed half of the states a senior UX BA would catch in review.
+  - Each screen carries **Source** (US — required), **Linked AC** (scenarios this screen verifies), **Linked NFR** (performance and accessibility NFRs that apply to UI), and an **Internationalisation** flag (LTR / RTL / both, long-string accommodation).
+  - Required-topics list extended from 6 to 8: explicit accessibility level (WCAG 2.1 A / AA / AAA — affects design decisions at wireframe stage, not just NFR time), internationalisation (RTL, long-string accommodation, locale-aware formatting).
+  - New US → WF coverage matrix flags Must stories with no linked screen.
+- **`skills/scenarios/SKILL.md` and `skills/references/templates/scenarios-template.md`** — drift fix, FR/NFR linking, expanded coverage matrix:
+  - Inline template fields and table columns no longer drift from the standalone template. Both now carry the same per-scenario field set.
+  - Each scenario carries **Source — Linked FR**, **Source — Linked NFR**, **Frequency** (how often the scenario runs in production — drives test investment), and **Stakes** (cost of failure — data loss, lost revenue, regulatory breach, reputation).
+  - Required-topics list extended from 5 to 8: frequency, stakes / blast radius, recovery scenarios.
+  - Coverage Summary expanded from 4 columns to 6: User Stories, FRs, NFRs, ACs, API Endpoints, Wireframes — with `(uncovered)` flagging on each axis.
+- **Document-control metadata (`Version`, `Status`) added to all 7 templates** — same `Draft / In Review / Approved / Superseded` lifecycle introduced for `/brief` and `/srs` in v3.5.0. Pipeline-core artifacts are controlled documents and need to answer "which version did we agree to?" three months in.
+
+### Cross-pattern impact
+
+After Group A and the pilot, **all 9 currently-shipped pipeline-stage skills** (`/discovery`, `/principles`, `/brief`, `/srs`, `/stories`, `/usecases`, `/ac`, `/nfr`, `/datadict`, `/apicontract`, `/wireframes`, `/scenarios`) carry the six systemic improvements: standards conformance, "why" fields, cross-artifact forward traceability, document control, single-source-of-truth templates, and BA-grade required-topics coverage. Group B (cross-cutting utilities: `/trace`, `/analyze`, `/clarify`, `/estimate`, `/glossary`, `/risk`, `/sprint`) and Group C (bookend skills: `/handoff`, `/implement-plan`, `/export`, `/publish`) remain at their current rigour and may receive a lighter sweep in a future session if patterns repeat.
+
+---
+
+## [3.5.0] — 2026-04-09
+
+### Highlights
+
+- **Pilot skill audit pass on `/brief`, `/srs`, `/stories`** — 14 senior-BA findings (6 Critical + 8 High) applied. Three skills now match the rigour a 25-year BA from a top-tier consultancy would expect: `/brief` separates Constraints from Assumptions and forces an explicit Out of Scope section, `/srs` adds Source / Verification / Rationale per FR plus a Brief-Goal → FR traceability matrix, `/stories` makes INVEST a quality gate and adds Persona / Business Value / Dependencies fields.
+
+### Changed
+
+- **`skills/brief/SKILL.md` and `skills/references/templates/brief-template.md`** — six findings applied:
+  - **Section numbering bug fixed** — workflow steps no longer jump from §6 to §8 (renumbered §8 → §7, §9 → §8). Was a sloppiness flag for any reviewer opening the file.
+  - **Out of Scope section is now mandatory** — added §4.2 to the artifact template. A brief is a contract; what is excluded matters as much as what is included. Without this, scope creep starts on the first standup.
+  - **Constraints and Assumptions split into two sections** (§6 and §7 in the new template). They have different change-management implications and BABOK v3 separates them. Constraints carry `Type / Source / Implication`; Assumptions carry `Statement / Owner / Validate by / Risk if false`.
+  - **Required-topics list extended from 7 to 11.** Added the four canonical brief inquiries every senior BA asks: buyer-vs-user separation, decision-making authority (who can sign off, by name and role), regulatory pre-screening (yes/no per regime: GDPR, HIPAA, FDA SaMD, SOC 2, PCI DSS, SOX, KYC/AML, FERPA, COPPA, EU AI Act, accessibility), and explicit failure criteria (asymmetric to success criteria — flushes out red lines).
+  - **Document control metadata added to the template** — `Version`, `Status` (Draft / In Review / Approved / Superseded), and an `Approvals` table at the bottom. A brief is a controlled document and needs to answer "which version did we agree to?" three months in.
+  - **Stakeholder table gains a "Sign-off authority" column** so the brief records not just who is interested but who has veto power.
+- **`skills/srs/SKILL.md` and `skills/references/templates/srs-template.md`** — four findings applied:
+  - **FR template gains three IEEE 830-mandated fields:** `Source` (which stakeholder, brief goal, regulatory requirement, or parent FR drove this requirement — required for traceability), `Verification` (Test / Demo / Inspection / Analysis — without it an FR is a wish, not a contract), `Rationale` (*why* this requirement exists, not just *what* — helps future maintainers know what is safe to push back on).
+  - **New §7 "Traceability — Brief Goal → FR" table.** Forward traceability from `01_brief_<slug>.md` §2 business goals to the FRs that satisfy them. Every Brief goal must have at least one linked FR; uncovered goals are flagged so they cannot silently disappear from the project.
+  - **§3 Functional Requirements is now grouped by feature area** as `### 3.N [Area name]` subsections, each with a reserved FR-ID range (FR-001..099 for area 1, FR-100..199 for area 2, …). New FRs inserted later go into their area's free numbers, not the global tail — IDs stay stable. Was a flat list, which became unreadable for any non-trivial system.
+  - **Required-topics list extended from 6 to 11.** Added the five universal SRS inquiries that downstream skills (`/datadict`, `/nfr`, `/apicontract`) inherit gaps from when they're missing: authentication and authorisation model (SSO / SAML / OIDC / RBAC / ABAC / MFA), data ownership and stewardship, audit and logging requirements, data retention and deletion (GDPR right-to-erasure), reporting needs.
+- **`skills/stories/SKILL.md` and `skills/references/templates/stories-template.md`** — five findings applied:
+  - **SKILL.md inline template removed in favour of a single source of truth at `references/templates/stories-template.md`.** Previously the inline template and the standalone file had drifted apart (the inline version had no `Size:` field and an inline AC reference; the standalone had `Size:` and a file-path AC reference). Two agents reading different parts produced different outputs. The SKILL.md now lists the field set and points at the standalone template; the standalone template is the only place that carries the per-story block layout.
+  - **INVEST is now an explicit quality gate.** The template has an `INVEST self-check:` line per story (Independent · Negotiable · Valuable · Estimable · Small · Testable). The `/validate` command description now requires every story to pass INVEST. The `/split` guidance references INVEST's "Small" / "Independent" criteria and Mike Cohn's nine story-splitting patterns instead of the previous arbitrary "more than 3 scenarios" rule.
+  - **Persona field replaces bare role.** Stories now use `**As** [Maria, ops supervisor at a 50-warehouse 3PL handling 200 returns/week]` instead of `**As an** admin`. Personas carry goals, frustrations, and context that drive UX decisions; bare job titles do not.
+  - **Business Value Score field added** (1–5 or High / Med / Low). Captures relative ranking *within* the same MoSCoW priority tier so a PM can sequence among 30 Must stories instead of treating them as interchangeable.
+  - **Depends on field added** so story-to-story dependencies are visible to `/sprint` and `/implement-plan`. A story that can't start until US-007 is done now says so in the template and won't get planned in the wrong sprint.
+  - **New "FR → Story coverage matrix" sub-table in the Coverage Summary.** Forward traceability from FR to US, with `(uncovered)` flag for any FR missing a linked story. Was previously a manual cross-reference task.
+
+---
+
 ## [3.4.1] — 2026-04-09
 
 ### Fixed
@@ -511,7 +595,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.6.0...HEAD
+[3.6.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.5.0...v3.6.0
+[3.5.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.1...v3.5.0
 [3.4.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.4.0...v3.4.1
 [3.4.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.2.0...v3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "3.4.1",
+  "version": "3.6.0",
   "description": "AI-powered Business Analyst pipeline — 24 skills from concept discovery to a sequenced implementation plan an AI coding agent can execute, with one-command Notion + Confluence publish. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",

package/skills/ac/SKILL.md

@@ -33,6 +33,10 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 3. Which boundary values are critical?
 4. Which US need multiple AC (different roles, states)?
 5. Are there data precision requirements (decimal places, formats)?
+6. **Performance bounds per scenario** — does any AC carry a response-time / throughput requirement that must be verified at acceptance?
+7. **Idempotency** — for action-based scenarios, can the action be safely retried? AC must specify whether duplicate requests produce the same result.
+8. **Observability** — what audit log entry, metric, or trace must this scenario produce? Verifiable by inspecting logs, not just the user-facing response.
+9. **State transitions** — which entity state changes during the scenario? Links the AC to the entity state machines defined in `/datadict`.
 
 Supplement with domain-specific questions from the reference.
 
@@ -40,26 +44,15 @@ Supplement with domain-specific questions from the reference.
 
 **File:** `05_ac_{slug}.md`
 
-```markdown
-# Acceptance Criteria: {Name}
-
-## US-{NNN}: {Short description}
-
-### AC-{NNN}-{NN}: {Scenario name}
-**Type:** {positive | negative | boundary}
-- **Given** {initial state}
-- **When** {action}
-- **Then** {expected result}
-
-**Links:** US-{NNN}, UC-{NNN}
-```
+The full per-AC field set lives at `references/templates/ac-template.md` and is the single source of truth. Each AC carries: ID (`AC-NNN-NN`), Type (positive / negative / boundary / performance / security), Given / When / Then, Linked US, Linked UC, Linked FR, Linked NFR (for performance/security ACs), Source (which business rule from `02_srs_{slug}.md` drove this AC), and Verification method (automated test / manual test / observed in production). The artifact also carries a US → AC coverage matrix at the bottom.
 
 **Rules:**
 - Numbering relative to US: AC-001-01 (first AC for US-001).
 - Every US has at least one positive AC.
-- Must-priority US have at least one negative AC.
+- Must-priority US have at least one negative AC AND at least one boundary AC.
 - Given = specific state. When = single action. Then = verifiable result.
-- Avoid vague wording — replace "system handles correctly" with concrete behavior.
+- Avoid vague wording — replace "system handles correctly" with concrete observable behaviour ("response status is 401", "audit log contains entry with action=login_failed", "stock count decremented by exactly the ordered quantity").
+- Every AC must reference its source business rule via the `Source` field — no AC without provenance.
 
 ## Back-reference update
 

package/skills/apicontract/SKILL.md

@@ -27,14 +27,21 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 3–7 topics per round, 2–4 rounds.
 
+**Standard alignment:** API Contract approximates the **OpenAPI 3.x** structure (servers, paths, parameters with `in` location, request body, responses keyed by HTTP status, components/schemas, security schemes). Markdown is the format, OpenAPI is the shape.
+
 **Required topics:**
-1. Protocol — REST, WebSocket, GraphQL, combination?
-2. API versioning — URI-based, header-based?
-3. Authentication — JWT, API Key, OAuth2?
-4. Webhook contracts — needed for incoming events from external systems?
-5. Error format — standard (RFC 7807) or custom?
-6. Pagination — cursor-based, offset-based? Limits?
-7. Rate limiting — any restrictions? For which endpoints?
+1. Protocol — REST, WebSocket, GraphQL, gRPC, or combination?
+2. API versioning — URI-based (`/v1/`), header-based (`Accept-Version`), or media-type versioning?
+3. Authentication and authorisation — JWT / OAuth2 / API Key / mTLS? Required scopes per endpoint group?
+4. Webhook contracts — incoming events from external systems? Outgoing events to subscribers?
+5. Error format — RFC 7807 Problem Details, or custom? Localised error messages?
+6. Pagination — cursor-based, offset-based, or key-set? Default and max page size?
+7. Rate limiting — global vs per-endpoint vs per-tenant? Headers (RateLimit-*)? 429 response shape?
+8. **Idempotency** — how does the API support safe retries on POST? `Idempotency-Key` header? Server-side dedupe window?
+9. **Content negotiation** — JSON only, or also CSV / XML / Protobuf? Accept header semantics?
+10. **CORS policy** — which origins are allowed for browser callers? Which headers exposed?
+11. **API deprecation policy** — how is breaking change communicated? `Sunset` header? Deprecation grace period?
+12. **Per-endpoint SLO** — latency target per endpoint group, links to NFRs?
 
 Supplement with domain-specific questions from the reference.
 
@@ -89,7 +96,13 @@ Supplement with domain-specific questions from the reference.
 **Rules:**
 - Endpoints grouped by domain (Auth, Users, Core, Admin, etc.).
 - JSON schemas are representative examples with types in comments.
-- Attributes consistent with Data Dictionary.
+- Attributes consistent with Data Dictionary entity field types.
+- Every endpoint has a **Source** field (FR-NNN) — no endpoint without provenance.
+- Every endpoint has an **Idempotency** marker (idempotent / not idempotent / idempotent via Idempotency-Key header).
+- Every endpoint has a **Required scope** (or "public" for unauthenticated paths) when OAuth2 / JWT scopes are in use.
+- Every endpoint has a **Verification** method (contract test / consumer-driven contract test / integration test).
+- Every endpoint has an **SLO** field linking to an NFR (latency target, error budget).
+- The artifact carries an FR → Endpoint coverage matrix at the bottom.
 
 ## Iterative refinement
 

package/skills/brief/SKILL.md

@@ -48,10 +48,14 @@ Cover 3–7 topics per round, 2–4 rounds. Do not generate the artifact until s
 1. Product type — what exactly is being built?
 2. Business goal — what problem does the product solve?
 3. Target audience and geography.
-4. Key stakeholders — who is interested, who makes decisions?
-5. Known constraints — deadlines, budget, regulatory requirements, mandatory integrations.
-6. Competitive products or references.
-7. Success criteria — specific metrics or qualitative goals.
+4. **Buyer vs. user separation** — who pays for the product vs. who uses it day-to-day? In B2B SaaS, EdTech, healthcare and many other domains these are different people with different priorities. If they coincide, record "buyer = user".
+5. Key stakeholders — who is interested, who makes decisions?
+6. **Decision-making authority** — who can sign off on the brief now, and who can sign off on changes later? Capture by name and role, not just by team.
+7. **Regulatory pre-screening** — which of the following regimes apply: GDPR / UK GDPR, HIPAA, FDA SaMD, SOC 2, PCI DSS, SOX, KYC / AML, FERPA / COPPA, EU AI Act, accessibility (Section 508 / WCAG / EN 301 549)? Single yes/no per regime — gates the rest of the pipeline.
+8. Known constraints — deadlines, budget, technology mandates, mandatory integrations.
+9. Reference products and analogues — products in this space the user admires (and why), products that failed (and why). Anchors the project to real-world references and surfaces unstated requirements.
+10. Success criteria — specific metrics or qualitative goals.
+11. **Failure criteria** — what would make us call this project a failure? Asymmetric to success criteria; flushes out red lines that "what's success" never reveals.
 
 If a domain reference is loaded, supplement general questions with domain-specific ones. Formulate questions concretely, with example answers in parentheses.
 
@@ -62,17 +66,37 @@ If a domain reference is loaded, supplement general questions with domain-specif
 ```markdown
 # Project Brief: {Project Name}
 
+**Version:** 0.1
+**Status:** Draft | In Review | Approved | Superseded
 **Domain:** {saas | fintech | ecommerce | healthcare | logistics | on-demand | social-media | real-estate | igaming | edtech | govtech | ai-ml | custom:{name}}
 **Date:** {date}
+**Slug:** {slug}
 
 ## 1. Project Summary
 ## 2. Business Goals and Success Metrics
 ## 3. Target Audience
+   ### 3.1 Buyer
+   ### 3.2 User (if different from Buyer)
 ## 4. High-Level Functionality Overview
-## 5. Stakeholders and Roles
-## 6. Constraints and Assumptions
-## 7. Risks
-## 8. Glossary
+   ### 4.1 In Scope
+   ### 4.2 Out of Scope
+## 5. Stakeholders and Decision-Making Authority
+## 6. Constraints
+## 7. Assumptions
+## 8. Risks
+## 9. Success and Failure Criteria
+   ### 9.1 Success Criteria
+   ### 9.2 Failure Criteria
+## 10. Reference Products and Analogues
+## 11. Glossary
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| {name} | {role} | {date} | {notes} |
 ```
 
 ### 6. AGENTS.md update
@@ -83,7 +107,7 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the user that the project was likely set up before v3.1 and tell them to run `ba-toolkit init --name "..." --slug {slug}` to scaffold the per-project `AGENTS.md`. Do not create one yourself with arbitrary structure.
 
-### 8. Iterative refinement
+### 7. Iterative refinement
 
 - `/revise [section]` — rewrite a section.
 - `/expand [section]` — add detail.
@@ -91,7 +115,7 @@ If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the use
 - `/validate` — check completeness and consistency.
 - `/done` — finalize and update `AGENTS.md`. Next step: `/srs`.
 
-### 9. Closing message
+### 8. Closing message
 
 After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
 

package/skills/datadict/SKILL.md

@@ -27,13 +27,19 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 3–7 topics per round, 2–4 rounds.
 
+**Scope boundary:** `/datadict` describes the **logical** data model — entities, attributes, conceptual types, relationships, state transitions. It does **not** prescribe the physical model (specific DBMS, indexes, sharding, partitioning). Physical-model decisions (PostgreSQL vs MongoDB, schema-per-tenant vs shared, index strategy) belong in `/research` (step 7a) as ADRs. If the user mentions a specific DBMS, note it as an existing constraint or as input to `/research`, not as a mandatory topic here.
+
 **Required topics:**
-1. DBMS — MongoDB, PostgreSQL, MySQL, other?
-2. Existing schema — is there one to account for or extend?
-3. Audit entities — which require full audit trail?
-4. Soft delete — is soft deletion used?
-5. Amount storage — in minor units (cents) or major currency units?
-6. Versioning — is change history needed for any entities?
+1. **Existing schema or system of record** — is there a legacy schema to account for or extend? Migration path?
+2. **PII inventory** — which fields are PII / PCI / PHI / financial? What is the retention policy per class? Which fields must be encrypted at rest? Which masked in UI?
+3. **Audit and history** — which entities require a full audit trail (every change logged with actor + timestamp)? Which need temporal / bitemporal storage (point-in-time queries)?
+4. **Soft delete** — which entities support soft deletion (`deleted_at`) vs hard delete? Cascade rules on parent deletion?
+5. **State machines** — which entities are stateful (Order, Subscription, Application, Case)? List the states and the legal transitions for each. **Mandatory question for any entity that has more than two distinct lifecycle states.**
+6. **Referential integrity** — cascade rules on parent deletion (cascade / restrict / set null / prevent). Required for every FK.
+7. **Time-zone handling** — are timestamps stored in UTC and converted at the presentation layer, or stored in local time with a TZ field?
+8. **Amount storage** — financial amounts in minor units (cents) or major units? Currency code stored alongside?
+9. **Versioning** — is change history needed for any entities (e.g. price history, terms-of-service version)?
+10. **Data ownership** — which team / role owns each entity for ongoing curation, schema changes, and incident response?
 
 Supplement with domain-specific questions and mandatory entities from the reference.
 
@@ -41,39 +47,16 @@ Supplement with domain-specific questions and mandatory entities from the refere
 
 **File:** `07_datadict_{slug}.md`
 
-```markdown
-# Data Dictionary: {Name}
-
-## General Information
-- **DBMS:** {type}
-- **Naming Conventions:** {camelCase | snake_case}
-- **Common Fields:** {createdAt, updatedAt, deletedAt}
-
-## Entity: {Name} ({English collection/table name})
-
-**Description:** {purpose in the system.}
-**Linked FR/US:** {references.}
-
-| Attribute | Type | Required | Constraints | Description |
-|-----------|------|----------|-------------|-------------|
-| _id / id | ObjectId / UUID | yes | PK | Unique identifier |
-| {name} | {type} | {yes/no} | {constraints} | {description} |
-
-**Indexes:**
-- {name}: {fields}, {type}
-
----
-
-## Entity Relationships
-
-| Entity A | Relationship | Entity B | Description |
-|----------|-------------|----------|-------------|
-```
+The full per-entity field set lives at `references/templates/datadict-template.md` and is the single source of truth. Each entity carries: name, **Source** (which FR/US introduced this entity), **Owner** (which team / role curates it), **Sensitivity** (Public / Internal / Confidential / PII / PCI / PHI), description, attribute table (with logical types, not DBMS-specific), relationships with cascade rules, **state machine** (if applicable), indexes (logical, not physical), retention policy, and notes. The artifact carries an FR → Entity coverage matrix at the bottom.
 
 **Rules:**
-- Data types match the chosen DBMS.
-- Constraints include: PK, FK, unique, not null, enum, min/max, regex.
-- Attribute and entity names in English; descriptions in the user's language.
+- Data types are **logical** (String, Integer, Decimal, Boolean, Timestamp, UUID, Enum, FK, JSON, Binary), not DBMS-specific. Physical type mapping happens in `/research` ADRs.
+- Constraints include: PK, FK with cascade rule, unique, not null, enum, min/max, regex, default.
+- Attribute and entity names in English (or per the project ID convention from `00_principles_*.md`); descriptions in the user's language.
+- Every entity has a **Source** field (FR-NNN or US-NNN) — no entity without provenance.
+- Every entity has an **Owner** field — accountability for schema changes and data quality.
+- Every entity has a **Sensitivity** classification — feeds /nfr Security NFRs and GDPR compliance.
+- Stateful entities (Order, Subscription, Application, Case, Account, …) **must** include a state machine section listing states and legal transitions.
 
 ## Iterative refinement
 

package/skills/nfr/SKILL.md

@@ -27,13 +27,22 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 3–7 topics per round, 2–4 rounds.
 
+**Standard alignment:** NFR categories follow **ISO/IEC 25010** Software Quality Model (the international standard for software quality characteristics). Every NFR maps to one of the 8 ISO 25010 characteristics: **Functional Suitability**, **Performance Efficiency**, **Compatibility**, **Usability**, **Reliability**, **Security**, **Maintainability**, **Portability**. Project-specific categories (Compliance, Localisation, Observability) can be added but each must be marked as an extension and explain which ISO 25010 characteristic it derives from.
+
 **Required topics:**
-1. Performance — target CCU (Concurrent Users), RPS (Requests Per Second), acceptable response time?
-2. Availability — required SLA? Acceptable downtime? Maintenance windows?
-3. Security — encryption, authentication, access audit?
-4. Compliance — applicable standards and laws? Data retention?
-5. Scalability — expected growth, horizontal scaling?
-6. Compatibility — browsers, OS, devices?
+1. **Performance Efficiency (ISO 25010)** — time behaviour (response time, throughput), resource utilisation (CPU, memory, network), capacity (CCU, RPS).
+2. **Reliability (ISO 25010)** — availability SLA, maturity (defect rate), fault tolerance, recoverability (RTO/RPO).
+3. **Security (ISO 25010)** — confidentiality (encryption at rest and in transit), integrity, non-repudiation (audit trail), accountability (per-user attribution), authenticity (authentication strength).
+4. **Compatibility (ISO 25010)** — co-existence (with other systems), interoperability (data exchange formats), browser/OS/device support.
+5. **Usability (ISO 25010)** — learnability, operability, accessibility (WCAG level), user error protection.
+6. **Maintainability (ISO 25010)** — modularity, reusability, analysability, modifiability, testability (code coverage target).
+7. **Portability (ISO 25010)** — adaptability (different environments), installability, replaceability.
+8. **Functional Suitability (ISO 25010)** — completeness, correctness, appropriateness — usually covered by FRs but worth a sanity check at NFR time.
+9. **SLO and SLI** — what service-level objectives do we commit to externally, and which service-level indicators do we measure internally to track them?
+10. **Observability** — what metrics, logs, and traces are mandatory? Retention period for each?
+11. **Disaster recovery** — RTO and RPO are not just numbers; what is the *runbook* and how often is it tested?
+12. **Data sovereignty** — where can each data class be stored and processed? Cloud regions allowed?
+13. **Deprecation policy** — how are NFR thresholds tightened over time, and how is breaking change communicated?
 
 Supplement with domain-specific questions and mandatory categories from the reference.
 
@@ -41,23 +50,13 @@ Supplement with domain-specific questions and mandatory categories from the refe
 
 **File:** `06_nfr_{slug}.md`
 
-```markdown
-# Non-functional Requirements: {Name}
-
-## NFR-{NNN}: {Category} — {Short Description}
-- **Category:** {performance | security | availability | scalability | compatibility | localization | compliance | audit | ...}
-- **Description:** {detailed description}
-- **Metric:** {measurable criterion}
-- **Verification Method:** {how it will be tested}
-- **Priority:** {Must | Should | Could | Won't}
-- **Linked FR/US:** {references}
-```
+The full per-NFR field set lives at `references/templates/nfr-template.md` and is the single source of truth. Each NFR carries: ID (`NFR-NNN`), ISO 25010 characteristic, sub-characteristic, description, measurable metric, **acceptance threshold** (the bar that says "we passed"), verification method, source (which stakeholder, regulation, or FR drove this NFR), rationale, priority, and linked FRs / USs / Brief constraints. The artifact carries an FR → NFR coverage matrix and a per-characteristic priority summary at the bottom.
 
 **Rules:**
 - Numbering: NFR-001, NFR-002, ...
-- Every NFR must have a measurable metric. Avoid "the system should be fast."
-- Group by category.
-- Domain-specific mandatory categories from the reference.
+- Every NFR must have a measurable metric **and** an acceptance threshold. Avoid "the system should be fast."
+- Group by ISO 25010 characteristic.
+- Domain-specific mandatory categories from the reference are also mapped to ISO 25010 characteristics so the audit trail is consistent.
 
 ## Back-reference update
 

package/skills/references/templates/ac-template.md

@@ -1,58 +1,109 @@
 # Acceptance Criteria: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
-**References:** `03_stories_[SLUG].md`, `04_usecases_[SLUG].md`
+**References:** `03_stories_[SLUG].md`, `04_usecases_[SLUG].md`, `02_srs_[SLUG].md`
 
 ---
 
 ## US-001: [Story Title]
 
-> As a [role], I want to [action], so that [benefit].
+> As a [persona], I want to [action], so that [benefit].
 
-### Scenario 1: [Happy path name]
+### AC-001-01: [Happy path scenario name]
+
+**Type:** Positive
+**Source:** [business rule from `02_srs_[SLUG].md` FR-NNN, or stakeholder name]
+**Verification:** Automated test | Manual test | Observed in production
+
+**Given** [precondition — concrete state, not "the system is ready"]
+**When** [action — single, observable trigger]
+**Then** [expected result — concrete and verifiable, not "the system handles it"]
+
+**Links:** US-001, UC-[NNN], FR-[NNN]
+
+---
+
+### AC-001-02: [Negative scenario name]
+
+**Type:** Negative
+**Source:** [business rule]
+**Verification:** Automated test
 
 **Given** [precondition]
 **When** [action]
-**Then** [expected result]
+**Then** [expected error response, error code, user-facing message]
 
-### Scenario 2: [Alternative or edge case name]
+**Links:** US-001, UC-[NNN], FR-[NNN]
 
-**Given** [precondition]
+---
+
+### AC-001-03: [Boundary scenario name]
+
+**Type:** Boundary
+**Source:** [business rule with the limit]
+**Verification:** Automated test
+
+**Given** [precondition at the boundary value]
 **When** [action]
-**Then** [expected result]
+**Then** [expected behaviour at the boundary — does it allow or reject?]
 
-### Scenario 3: [Negative / error case name]
+**Links:** US-001, FR-[NNN]
 
-**Given** [precondition]
+---
+
+### AC-001-04: [Performance scenario name, if applicable]
+
+**Type:** Performance
+**Source:** NFR-[NNN]
+**Verification:** Load test | APM measurement
+**Linked NFR:** NFR-[NNN]
+
+**Given** [load condition — concurrent users, request rate]
 **When** [action]
-**Then** [expected result]
+**Then** [response time / throughput target, e.g. "p95 latency < 300ms"]
+
+**Links:** US-001, NFR-[NNN]
+
+---
 
-**Definition of Done:**
-- [ ] All scenarios above pass
+**Definition of Done for US-001:**
+- [ ] All ACs above pass
 - [ ] Edge case [X] handled
 - [ ] UI matches wireframe WF-[NNN]
+- [ ] Audit log entry produced for AC-001-01 path
 
 ---
 
 ## US-002: [Story Title]
 
-> As a [role], I want to [action], so that [benefit].
+> As a [persona], I want to [action], so that [benefit].
 
-### Scenario 1: [Happy path name]
+### AC-002-01: [Happy path]
+
+**Type:** Positive
+**Source:** [business rule]
+**Verification:** Automated test
 
 **Given** [precondition]
 **When** [action]
 **Then** [expected result]
 
-### Scenario 2: [Negative case name]
+**Links:** US-002, FR-[NNN]
 
-**Given** [precondition]
-**When** [action]
-**Then** [expected result]
+<!-- Repeat AC block per scenario. Each US-NNN section mirrors the stories artifact. -->
+
+---
+
+## US → AC Coverage Matrix
 
-**Definition of Done:**
-- [ ] All scenarios above pass
+Forward traceability from each User Story in `03_stories_[SLUG].md` to its Acceptance Criteria. Every Must-priority story must have at least one positive AC AND at least one negative AC AND at least one boundary AC; uncovered combinations are flagged.
 
-<!-- Repeat AC block for each User Story. Each US-NNN section mirrors the stories artifact. -->
+| US ID | Positive AC | Negative AC | Boundary AC | Performance AC | Coverage Status |
+|-------|-------------|-------------|-------------|----------------|-----------------|
+| US-001 | AC-001-01 | AC-001-02 | AC-001-03 | AC-001-04 | ✓ Full |
+| US-002 | AC-002-01 | (missing) | (missing) | — | ⚠ Positive only |
+| US-003 | (missing) | (missing) | (missing) | — | ✗ Uncovered |

package/skills/references/templates/apicontract-template.md

@@ -1,12 +1,16 @@
 # API Contract: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
 **API Style:** REST | GraphQL | gRPC
 **Base URL:** `https://api.[domain].com/v1`
 **Auth:** Bearer JWT | API Key | OAuth 2.0
-**References:** `02_srs_[SLUG].md`, `07_datadict_[SLUG].md`
+**Versioning:** URI (`/v1/`) | Header (`Accept-Version`) | Media-type
+**Standard:** Approximates OpenAPI 3.x structure
+**References:** `02_srs_[SLUG].md`, `07_datadict_[SLUG].md`, `06_nfr_[SLUG].md`
 
 ---
 
@@ -34,9 +38,16 @@ Token obtained via `POST /auth/token`. Expires in [N] minutes. Refresh via `POST
 
 ### POST /[resource]
 
-**Description:** [What this endpoint does.]
-**Auth required:** Yes | No
-**Linked FR:** FR-[NNN] | **Linked Story:** US-[NNN]
+| Field | Value |
+|-------|-------|
+| **Description** | [What this endpoint does] |
+| **Source** | FR-[NNN], US-[NNN]  *(Required — what drove this endpoint)* |
+| **Auth required** | Yes / No |
+| **Required scope** | `resource:write` / public |
+| **Idempotency** | Idempotent / Not idempotent / Idempotent via `Idempotency-Key` header |
+| **Rate limit** | [N requests / minute / IP] or "global default" |
+| **SLO** | p95 < 300ms (NFR-[NNN]) |
+| **Verification** | Contract test / consumer-driven contract test / integration test |
 
 **Request body:**
 
@@ -175,9 +186,31 @@ Token obtained via `POST /auth/token`. Expires in [N] minutes. Refresh via `POST
 |-----------|-----------|---------|
 | 400 | VALIDATION_ERROR | Request body or params fail validation |
 | 401 | UNAUTHORIZED | Missing, expired, or invalid token |
-| 403 | FORBIDDEN | Authenticated but insufficient permissions |
+| 403 | FORBIDDEN | Authenticated but insufficient permissions / scope |
 | 404 | NOT_FOUND | Resource does not exist |
 | 409 | CONFLICT | State conflict (duplicate, wrong status) |
 | 422 | BUSINESS_RULE_ERROR | Request is valid but violates a business rule |
 | 429 | RATE_LIMITED | Too many requests |
 | 500 | INTERNAL_ERROR | Unexpected server error |
+
+---
+
+## Idempotency, CORS, and Deprecation
+
+**Idempotency:** POST endpoints marked "Idempotent via header" accept an `Idempotency-Key` header (UUID v4 recommended). The server stores the request fingerprint + response for [N] hours. A retried request with the same key returns the cached response without re-executing the side effect.
+
+**CORS policy:** Allowed origins listed in `[config file]`. Browsers from allowed origins may use the API directly with JWT in `Authorization` header. `OPTIONS` preflight responses cache for [N] seconds (`Access-Control-Max-Age`).
+
+**API deprecation policy:** Breaking changes are announced via the `Sunset` HTTP response header (RFC 8594) at least [N] months in advance. The `Deprecation` header is set on every response from a deprecated endpoint. A deprecated endpoint continues to function for the entire grace period; only after the sunset date does it return `410 Gone`.
+
+---
+
+## FR → Endpoint Coverage Matrix
+
+Forward traceability from each Functional Requirement in `02_srs_[SLUG].md` §3 to the API endpoints that implement it. An FR with no linked endpoint is flagged — every customer- or system-facing FR should have at least one linked endpoint.
+
+| FR ID | FR Title | Linked Endpoints | Coverage Status |
+|-------|----------|------------------|-----------------|
+| FR-001 | [title] | `POST /auth/login`, `POST /auth/refresh` | ✓ |
+| FR-002 | [title] | `GET /catalog`, `GET /catalog/:id` | ✓ |
+| FR-003 | [title] | (uncovered) | ✗ |