@kudusov.takhir/ba-toolkit 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -11,6 +11,109 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.8.0] — 2026-04-10
+
+### Highlights
+
+- **Group C skill audit pass on `/discovery`, `/principles`, `/research`, `/handoff`, `/implement-plan`, `/export`** — the bookend skills (entry, conventions, technology research, exit) brought to senior-BA rigour. ~26 Critical + High findings applied. Highlights: full Michael Nygard ADR format with Drivers / Alternatives / Decision Date for `/research`, expanded `/handoff` artifact inventory covering all 15 pipeline stages plus cross-cutting tools, formal Sign-off section for `/handoff`, principles Definition of Ready section synchronised with the v3.5.0+ template fields across every artifact type, new ISO/IEC 25010 alignment in the principles NFR baseline, new Testing Strategy section in `/principles` (the principled approach to TDD that resolves the batch 6 item 2 question), new Hypotheses → Brief Goals retrospective traceability in `/discovery`, observability + CI/CD + secret management slots in `/implement-plan`, and full v3.5.0+ stories template field support in `/export` (Persona / Business Value Score / Depends on / INVEST embedded in exported issues with full FR/UC/AC/NFR/WF traceability columns). After this pass, **22 of 24 shipped skills** carry the senior-BA improvements.
+
+### Changed
+
+- **`skills/principles/SKILL.md` and `skills/references/templates/principles-template.md`** — biggest debt of the audit because `/principles` is the source of truth that downstream skills read for Definition of Ready, ID conventions, and quality gates. The DoR section had drifted out of sync with the v3.5.0+ template fields across every artifact type:
+  - **Definition of Ready (§4) rewritten** to mirror the v3.7.0+ baseline per artifact type. Every DoR checklist now requires the same fields the artifact templates carry: FR adds Source / Verification / Rationale / area-grouping; US adds Persona / Business Value Score / Size / Depends on / INVEST self-check; UC adds Goal in Context / Scope / Stakeholders & Interests / Source / Success vs Minimal Guarantees split; AC adds Source / Verification / Linked NFR; NFR adds ISO 25010 characteristic / Acceptance threshold / Source / Rationale; Entity adds Source / Owner / Sensitivity / state machine for stateful entities; Endpoint adds Source / Idempotency / Required scope / SLO / Verification; Wireframe adds Source / Linked AC / Linked NFR / canonical 8-state list (was 4 states). New artifact types added: Risk DoR (Probability / Impact / Velocity / Treatment Strategy / Owner / Review cadence per ISO 31000) and Implementation Task DoR (references / dependsOn validity / definitionOfDone with linked AC).
+  - **ID Conventions table (§2) extended** with the post-v3.5.0 entity types that were previously missing: Risks (`RISK-NN`), Sprints (`SP-NN`), Implementation Tasks (`T-NN-NNN`), Analyse findings (`A-NN`), and Brief Goals (`G-N`).
+  - **NFR Baseline (§5) aligned with ISO/IEC 25010**. The three previously-listed categories (Security, Availability, Compliance) were ad-hoc; the new section explicitly maps every category to the parent ISO 25010 characteristic and lists the other 5 characteristics as candidate additions with one-line guidance on when each becomes mandatory.
+  - **New §8 Testing Strategy section** with five canonical strategies (TDD / Tests-after / Integration-only / Manual-only / None) and explicit guidance on which one drives `/implement-plan` to embed "Tests to write first" blocks per task. **This is the principled resolution of the batch 6 item 2 question** — TDD support lives in `/principles`, not as a separate `/tdd-tests` skill, exactly as the rationale recorded in `todo.md` "Removed from the backlog" predicted.
+  - **New §9 Code Review and Branching** section (trunk-based / GitHub flow / GitFlow / required reviewers / merge gate) and **new §10 Stakeholder Decision Authority** table (per-section decision authority by name and role).
+  - **3 new required-topics** in the SKILL.md interview: testing strategy, stakeholder decision authority, code review and branching policy.
+  - **Document-control metadata added**: `Status` field plus `Approvals` table at the bottom.
+- **`skills/discovery/SKILL.md` and `skills/references/templates/discovery-template.md`** — retrospective traceability and decision provenance:
+  - **New §9 Hypotheses → Brief Goals mapping table** filled in by `/brief` when it consumes the discovery artifact. Forward traceability from each discovery hypothesis to the Brief goal it became, with a Status column (Validated / Refined / Disproved / Pending) so a 3-month-post-launch retrospective can answer "did the chosen audience hypothesis hold?" and "did the predicted MVP features actually drive adoption?".
+  - **`Decision date`** and **`Decision owner`** fields in the header so the recommendation moment is timestamped and attributable.
+  - **`Status` field** (Concept (pre-brief) / In Review / Locked) and **`Approvals` table** for the cases where the discovery artifact is signed off as a decision document.
+- **`skills/research/SKILL.md` and `skills/references/templates/research-template.md`** — full Michael Nygard ADR format + downstream-consumer awareness:
+  - **Standard alignment with the Michael Nygard ADR format** (the de facto industry standard since 2011), extended with explicit **Drivers** field (what forced the decision — FRs, NFRs, regulatory, cost, time-to-market) and **Alternatives Considered** table with a `Disqualifying factor` column. Every ADR carries Status, Proposal date, Decision date, Decision owner, Drivers, Context, Alternatives Considered, Decision, Consequences (positive / negative / neutral) — the field set a senior architect would expect on a serious project.
+  - **`/implement-plan` integration** documented explicitly. The output of `/research` is the primary tech-stack source for `/implement-plan` (added in v3.4.0); the new Tech Stack Summary table at the bottom of the research artifact is read directly by `/implement-plan` to populate its header without re-asking the calibration interview.
+  - **Required-topics list extended from 6 to 14**. Added the explicit tech-stack slots `/implement-plan` consumes: Frontend stack, Backend stack, Database, Hosting / deployment target, Auth / identity, Observability platform. Added Build vs Buy and Open-source vs Proprietary tolerance as common BA inquiries.
+  - **New NFR → ADR traceability matrix** at the bottom flags Must NFRs without an architectural decision.
+  - **Document-control metadata added** (Version / Status).
+- **`skills/handoff/SKILL.md` and `skills/references/templates/handoff-template.md`** — full pipeline coverage and formal sign-off:
+  - **Artifact Inventory expanded from 11 rows to 21 rows** (15 pipeline-stage rows + 6 cross-cutting tool rows). Was missing /discovery (stage 0), /principles (stage 0a), /implement-plan (stage 12), and every cross-cutting artifact (sprint, risk, glossary, trace, analyze, estimate). The inventory is now the canonical "what's in the package" reference for the dev team.
+  - **Traceability Coverage expanded from 7 chains to 11 chains** to reflect the new traceability matrices added in pilot / Group A / Group B: Brief Goal → FR (added in v3.5.0 SRS template), US → AC broken down by Positive / Negative / Boundary type, FR → NFR, FR → Entity, FR → Endpoint, US → WF, US → Scenario, FR → Implementation Task, NFR → ADR.
+  - **New §7 Architecture Decision Summary** lists the top ADRs from `/research` with their drivers and which `/implement-plan` phase they affect — so the dev team learns the architectural decisions without having to read `/research` separately.
+  - **New §9 Sign-off section** with a formal acceptance table (Business Analyst / Product Manager / Tech Lead / QA Lead / Stakeholder). Senior BA expectation: handoff is the formal acceptance step and needs an explicit sign-off flow with named approvers.
+  - **Document-control metadata added** (Version / Status). Same P1 pattern as the rest of the audit.
+- **`skills/implement-plan/SKILL.md`** — extended Tech Stack with operational slots, risk-aware sequencing within phases:
+  - **Tech Stack table extended from 6 rows to 9 rows.** Added: **Observability** (logging / metrics / tracing platform — Datadog / New Relic / Grafana / OTel), **CI / CD** (GitHub Actions / GitLab CI / CircleCI / Jenkins), **Secret management** (env vars / Vault / Secrets Manager / Doppler / 1Password CLI). Without these slots, the AI coding agent has to invent operational choices on the fly.
+  - **Calibration interview extended from 6 to 9 questions** to cover the same three new slots when `/research` is missing.
+  - **Risk-aware sequencing within phases** is now explicit. Tasks whose `references` link to FRs / US / NFRs tied to a 🔴 Critical or 🟡 High risk in `00_risks_*.md` are pulled to the front of their phase, ahead of equally-prioritised tasks. Tagged with `**Risk:** RISK-NN ↑` next to the task title. Rationale: validate risky bets early when there's still time to pivot. Was generic "ordered by dependencies, then priority"; now also "then by risk elevation".
+- **`skills/export/SKILL.md`** — interview-protocol compliance, v3.5.0+ stories template field support, full traceability in exports:
+  - **Format interview now follows the standard interview protocol** — table-based options, Recommended marker, inline-context support per protocol rule 9. Was a flat numbered question list that bypassed the protocol.
+  - **Exported issues now carry every v3.5.0+ stories template field**: Persona (named persona with role + context, not bare job title), Business Value Score, Size, Depends on (rendered as "Blocked by" link in trackers that support it), INVEST self-check. Trackers with custom field support (Jira, Linear) get them as separate fields; CSV gets extra columns; GitHub Issues embeds them in the issue body since GitHub has no custom-field surface.
+  - **Full cross-artifact traceability in exported issues**: Linked FR, Linked UC, Linked AC (per scenario, with their `AC-NNN-NN` IDs), Linked NFR (for performance- and security-relevant stories), Linked Wireframe. Was previously only `FR Reference`. Modern issue trackers can re-establish the traceability graph without re-reading the source artifacts.
+  - **CSV format expanded from 10 columns to 17** to carry the new fields (Persona, Value, Size, FR, UC, AC list, NFR, WF, Depends on, AC Summary).
+
+### Cross-pattern impact
+
+After the pilot, Group A, Group B, and Group C audits, **22 of 24 shipped skills** carry the senior-BA improvements: standards conformance to canonical frameworks (BABOK v3, IEEE 830, ISO 25010, ISO 31000, ISO 1087-1, OpenAPI 3.x, Cockburn use cases, INVEST, MoSCoW, PMBOK 7, Cone of Uncertainty, Michael Nygard ADRs), explicit "why" / provenance / ownership fields on every artifact element, cross-artifact bidirectional traceability with severity-aware coverage gaps, document control with versions and approvers, single-source-of-truth templates with no inline drift, and BA-grade required-topics coverage. The two skills not yet audited are `/publish` (a thin CLI wrapper with nothing structural to audit) and `/clarify` (already audited in Group B). The skill audit rollout is functionally complete.
+
+---
+
+## [3.7.0] — 2026-04-10
+
+### Highlights
+
+- **Group B skill audit pass on `/trace`, `/analyze`, `/clarify`, `/estimate`, `/glossary`, `/risk`, `/sprint`** — 7 cross-cutting utilities brought to senior-BA rigour. ~33 Critical + High findings applied. Highlights: full ISO 31000 + PMBOK 7 alignment for `/risk` (Velocity axis, treatment-strategy classification), Cone of Uncertainty + confidence bands for `/estimate`, IEEE 830 §4.3 quality attributes mapped to `/analyze` finding categories, definition-quality discipline (Aristotelian form) for `/glossary`, structured table output for `/clarify`, bidirectional traceability + `/implement-plan` integration for `/trace`, focus-factor + ceremonies-aware net velocity for `/sprint`. Two utility templates (`risk-template.md`, `sprint-template.md`) rewritten from concrete Nova Analytics worked examples back to placeholder convention to match the other 19 templates.
+
+### Changed
+
+- **`skills/trace/SKILL.md` and `skills/references/templates/trace-template.md`** — bidirectional traceability + `/implement-plan` integration:
+  - Inline template removed; standalone is the single source of truth (drift fix — inline had 8 columns, standalone had 11; mismatched column sets).
+  - **Bidirectional traceability is now the default.** Forward (FR → downstream) catches "what does this requirement become?"; reverse (US/UC/AC/NFR/Entity/API/WF/SC/Task → FR) catches "why does this artifact exist?". Senior BA needs both directions to validate provenance.
+  - **`/implement-plan` integration.** The matrix now includes a `Task` column populated from `12_implplan_*.md` (introduced in v3.4.0). The chain is now `FR → US → UC → AC → NFR → Entity → ADR → API → WF → SC → Task`.
+  - **Calibration interview added** (was generation-only): direction (forward / reverse / bidirectional, default bidirectional), scope, severity-thresholds source.
+  - **Coverage Gaps now grouped by severity** (🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low) read from `00_principles_*.md` §3 instead of just listing orphans flat.
+- **`skills/analyze/SKILL.md` and `skills/references/templates/analyze-template.md`** — IEEE 830 alignment + Owner column + delta mode:
+  - **Finding categories expanded from 5 to 8** and explicitly mapped to **IEEE 830 §4.3 SRS quality attributes**: Duplication (consistency), Ambiguity (unambiguous, including modal-verb confusion), Coverage Gap (complete + traceable), Terminology Drift (consistent), Invalid Reference (traceable), **Inconsistency** (same fact stated differently across artifacts), **Underspecified Source** (post-v3.5.0 provenance discipline — FR/UC/AC/Entity/Endpoint missing the `Source` field), **Stakeholder Validation Gap** (post-v3.5.0 assumption discipline — assumptions without Owner or past Validate by date).
+  - **Owner column added** to every finding. Senior BAs always assign accountability — a finding with no owner doesn't get fixed.
+  - **Calibration interview added**: severity threshold source, categories to include, delta mode (only new findings since the last `/analyze` run).
+- **`skills/clarify/SKILL.md`** — extended ambiguity catalogue + structured table output + ripple-effect handling:
+  - **Ambiguity categories expanded from 6 to 11.** Added: Quantification gaps (numbers without units, frequencies without windows), Time-zone gaps (timestamps without TZ), Currency gaps (amounts without currency), Scale gaps ("users" without specifying CCU/registered/MAU/DAU), Modal verb confusion (must / shall / should / may inconsistency per IEEE 830).
+  - **Output format changed from numbered list to structured table** with columns `# | Location | Category | Question | Answer`. The user can answer in-place by filling the rightmost column or defer with `(deferred)`.
+  - **Ripple-effect check added.** Before saving, the skill identifies any answer that affects other artifacts (e.g., a new role propagates from `/srs` to `/stories` personas, `/usecases` actors, `/scenarios` personas) and offers to update each affected file via `/revise`. Was previously a single sentence buried in step 2.
+- **`skills/estimate/SKILL.md`** — Cone of Uncertainty + confidence bands + planning poker honesty:
+  - **Cone of Uncertainty discipline.** Calibration question 5 asks the estimation phase (Discovery / Brief / SRS / AC / Wireframes / Implementation Plan) and emits the confidence band that matches the standard variance for that phase: ±400% / ±100% / ±50% / ±25% / ±10%. Every estimate now carries a confidence label (Order of magnitude / ROM / Budget / Definitive / Control). Single-point estimates without a confidence band are misread as commitments — the Cone discipline prevents this.
+  - **Risk multiplier and tech-debt allocation added** as calibration questions. Stories linked to 🔴 Critical risks default to +20%; tech-debt reservation defaults to 20% of velocity.
+  - **Planning poker honesty.** New section "Estimation discipline — what this skill is and is not" makes explicit that this is an analytical single-estimator pass, not a team commitment, and recommends running planning poker with the dev team using these numbers as the starting anchor. Senior BAs never confuse an analytical estimate with a team commit.
+  - **Estimation Summary table** now carries the confidence band per story, the risk-adjusted total, the tech-debt reservation, and the net feature capacity — not just a flat SP total that hides the assumptions.
+- **`skills/glossary/SKILL.md`** — Aristotelian definition discipline + ISO 1087-1 alignment + extended sources:
+  - **Standard alignment with ISO 1087-1** (Terminology Work — Vocabulary). Definitions follow the **Aristotelian form**: genus + differentia + purpose. The skill rejects circular definitions ("a User is a user of the system"), self-referential definitions, definitions that name features without identifying the genus, and definitions that name the genus without distinguishing from siblings.
+  - **New Step 2b — Definition quality check.** Walks every term in the glossary, classifies definitions as Circular / Self-referential / Missing genus / Missing differentia, and lists weak definitions in a sub-section of the drift report with a recommended rewrite. Senior BAs catch this on every glossary review.
+  - **Sources expanded** to include `00_discovery_*.md` (concept terms), `00_principles_*.md` (convention names), and `12_implplan_*.md` (phase names, technology choices). 12 source files → 14.
+  - **Drift report now requires a justification** for the canonical name choice — not just "Customer" but "Customer because it appears earliest, most frequently, and matches the domain reference". Without justification, drift recommendations are arbitrary.
+- **`skills/risk/SKILL.md` and `skills/references/templates/risk-template.md`** — full ISO 31000 + PMBOK 7 alignment, Velocity axis, Treatment Strategy classification, calibration interview, document control, placeholder template:
+  - **Standard alignment with ISO 31000** (Risk Management — Guidelines) and **PMI PMBOK 7**. Each risk now carries the canonical risk-management fields, not just probability × impact.
+  - **Velocity axis added** (Years / Months / Weeks / Days / Immediate). Velocity records how fast the risk materialises once triggered — determines reaction time and whether mitigation has to be in place before the trigger or whether reactive response is enough. P × I alone is insufficient for a senior risk register.
+  - **Treatment strategy field added** with the four canonical strategies from PMBOK 7 / ISO 31000: **Avoid** (eliminate the cause), **Reduce / Mitigate** (lower probability or impact), **Transfer** (insurance / vendor / contract), **Accept** (acknowledge and budget). Previous version only documented mitigation + contingency without classifying the strategy.
+  - **Review cadence per risk** (Monthly / Quarterly / Ad hoc). Without a cadence, risks become "set and forget" — the canonical failure mode.
+  - **Calibration interview added** (was generation-only): risk tolerance (Low / Medium / High), domain-specific frameworks (FAIR for cyber, ISO 14971 for medical, COSO ERM for financial, NIST RMF for US federal), review cadence, treatment-strategy preference.
+  - **`risk-template.md` rewritten from a concrete Nova Analytics worked example to placeholder convention** with `[PROJECT_NAME]`, `[Owner]`, `[Velocity]`, etc. Aligns with the other 19 templates that use placeholder syntax. The Nova Analytics example was misread as the canonical content by agents that didn't realise it was a sample.
+  - Document-control metadata (`Version`, `Status`) added to the template.
+- **`skills/sprint/SKILL.md` and `skills/references/templates/sprint-template.md`** — focus factor + ceremonies-aware net velocity, persona column, dependency awareness, placeholder template:
+  - **Net velocity replaces theoretical velocity as the assignment basis.** The skill now distinguishes theoretical velocity (100% capacity) from net velocity, applying focus factor (default 65%), buffer / slack (default 15%), and ceremonies cost (default 1 day per developer per 2-week sprint). Formula: `Net = Theoretical × Focus × (1 − Buffer) − Ceremonies`. Senior scrum masters never schedule against the theoretical number — that's how teams overcommit and miss sprints. Was assigning against raw theoretical velocity.
+  - **Calibration interview extended from 6 to 10 questions**: focus factor, buffer / slack, ceremonies overhead, holidays / PTO added.
+  - **Persona column added** to every sprint detail table (per the v3.5.0+ stories template). Sprint plans now reflect which personas each sprint serves so the team builds empathy.
+  - **Business Value Score and Depends on fields read from the v3.5.0+ stories template** explicitly in the priority-ordering algorithm. Was relying on implicit prerequisites only.
+  - **Context loading extended** to read `00_principles_*.md` for team capacity defaults and `00_discovery_*.md` for early MVP signals.
+  - **`sprint-template.md` rewritten from a concrete Nova Analytics worked example to placeholder convention** with `[PROJECT_NAME]`, `[Persona]`, etc. The new template carries the net-velocity header, the persona column, the explicit capacity model section, and explicit assumption documentation. Aligns with the other 19 templates.
+  - Document-control metadata (`Version`, `Status`) added to the template.
+
+### Cross-pattern impact
+
+After the pilot, Group A, and Group B, **15 of the 24 shipped skills** carry the senior-BA improvements: standards conformance to canonical frameworks (BABOK v3, IEEE 830, ISO 25010, ISO 31000, ISO 1087-1, OpenAPI 3.x, Cockburn use cases, INVEST, MoSCoW, PMBOK 7, Cone of Uncertainty, IEEE 830 §4.3 quality attributes), explicit "why" / provenance fields, cross-artifact forward and reverse traceability, document control, single-source-of-truth templates without inline drift, and BA-grade required-topics coverage. Group C (bookend skills: `/discovery`, `/principles`, `/research`, `/handoff`, `/implement-plan`, `/export`, `/publish`) remains at current rigour and may receive a lighter sweep in a future session.
+
+---
+
 ## [3.6.0] — 2026-04-10
 
 ### Highlights
@@ -595,7 +698,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.6.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.8.0...HEAD
+[3.8.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.7.0...v3.8.0
+[3.7.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.6.0...v3.7.0
 [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "3.6.0",
+  "version": "3.8.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/analyze/SKILL.md

@@ -19,19 +19,34 @@ Cross-cutting command. Performs a read-only analysis across all existing pipelin
 
 Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
 
+## Calibration interview
+
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended**, render variants in the user's language (rule 11), and wait for an answer.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/analyze` (e.g., `/analyze focus on security and performance`), parse it as a category-focus hint and run only those categories.
+
+If the user invokes `/analyze` with no inline hint, run a short calibration interview (skip any question already answered by `00_principles_*.md`):
+
+1. **Severity threshold** — which severity blocks `/done`? Read from `00_principles_*.md` §6 if present, otherwise ask. **Recommended:** CRITICAL only.
+2. **Categories to include** — all 8 canonical categories, or focus on a subset (e.g., only Coverage Gap and Invalid Reference for a fast pre-handoff sanity check)?
+3. **Delta mode** — produce a full report, or a delta against the prior `00_analyze_*.md` (only new findings since the last run)?
+
 ## Analysis categories
 
-### 1. Duplication (DUP)
+The 8 canonical categories cover the IEEE 830 §4.3 SRS quality attributes (correct, unambiguous, complete, consistent, verifiable, modifiable, traceable, ranked) plus modern BA concerns (terminology drift, source provenance, validation gaps).
+
+### 1. Duplication (DUP) — *IEEE 830: consistency*
 - Functionally equivalent or near-duplicate FRs within SRS.
 - User stories that describe the same action for the same role.
 - Repeated business rules across multiple artifacts.
 
-### 2. Ambiguity (AMB)
+### 2. Ambiguity (AMB) — *IEEE 830: unambiguous*
 - Requirements containing metrics-free adjectives: "fast", "reliable", "scalable", "secure", "simple", "efficient" without a measurable criterion.
 - Underspecified scope: "the system" or "the user" without a concrete actor.
 - Conditional requirements without defined conditions.
+- Modal verb confusion: inconsistent use of "must / shall / should / may" — IEEE 830 expects strict modal discipline.
 
-### 3. Coverage Gap (GAP)
+### 3. Coverage Gap (GAP) — *IEEE 830: complete + traceable*
 - FR without at least one linked US.
 - US without linked UC (if Use Cases artifact exists).
 - US without AC (if AC artifact exists).
@@ -39,20 +54,42 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 - Data entities not linked to any FR or US.
 - API endpoints not linked to any FR or US.
 - Wireframes not linked to any US.
+- Tasks (from `12_implplan_*.md`) not linked to any FR/US/AC.
 
-### 4. Terminology Drift (TERM)
+### 4. Terminology Drift (TERM) — *IEEE 830: consistent*
 - The same concept referred to by different names across artifacts (e.g., "Wallet" in SRS vs "Balance" in Stories vs "Account" in Data Dictionary).
 - Abbreviations expanded differently in different artifacts.
 
-### 5. Invalid Reference (REF)
+### 5. Invalid Reference (REF) — *IEEE 830: traceable*
 - Links to IDs that do not exist (FR-NNN, US-NNN, UC-NNN, etc.).
 - References to roles not defined in the SRS roles section.
 - API endpoint links in wireframes pointing to non-existent endpoints.
+- Brief Goal references (G-N) in the SRS §7 traceability table that do not exist in `01_brief_*.md` §2.
+
+### 6. Inconsistency (INC) — *IEEE 830: consistent*
+- Same fact stated differently across artifacts (e.g., `01_brief` says €1.5M GMV target, `02_srs` §1.2 says €2M).
+- A constraint in `01_brief` §6 contradicted by an FR in `02_srs` §3.
+- Priority disagreement: same item Must in one artifact and Should in another.
+
+### 7. Underspecified Source (SRC) — *post-v3.5.0 provenance discipline*
+- FR without `Source` field (introduced in v3.5.0).
+- Use Case without `Source` field.
+- AC without `Source` field.
+- Entity without `Source` or `Owner` field.
+- Endpoint without `Source` field.
+- Stakeholder name referenced as a source but missing from `01_brief` §5 stakeholders table.
+
+### 8. Stakeholder Validation Gap (VAL) — *post-v3.5.0 assumption discipline*
+- Assumption in `01_brief` §7 with no `Owner` or `Validate by` date.
+- Assumption past its `Validate by` date and still not converted to a fact or risk.
+- Brief goal in §2 with no measurable success metric.
 
 ## Generation
 
 **File:** `00_analyze_{slug}.md`
 
+The full report layout lives at `references/templates/analyze-template.md` and is the single source of truth. Each finding carries: ID, Severity, Category (one of the 8 above), Location (artifact + element ID), Description, Recommendation, and **Owner** (which role is accountable for fixing the finding — assigned by `00_principles_*.md` §4 Definition of Ready ownership where applicable, otherwise by domain default).
+
 ```markdown
 # Cross-Artifact Quality Analysis: {Name}
 
@@ -61,13 +98,15 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Finding Report
 
-| ID | Category | Severity | Location | Summary | Recommendation |
-|----|----------|----------|----------|---------|----------------|
-| A1 | Duplication | HIGH | srs:FR-003, srs:FR-017 | Both describe user authentication | Merge into a single FR |
-| A2 | Ambiguity | MEDIUM | srs:NFR-002 | "Low latency" has no metric | Add target value in ms |
-| A3 | Coverage Gap | CRITICAL | srs:FR-008 | No linked user story | Create US or remove FR |
-| A4 | Terminology | HIGH | srs, stories | "Wallet" vs "Balance" used interchangeably | Standardize in glossary |
-| A5 | Invalid Ref | CRITICAL | ac:AC-003-01 | Links US-099 which does not exist | Fix reference |
+| ID | Category | Severity | Location | Summary | Recommendation | Owner |
+|----|----------|----------|----------|---------|----------------|-------|
+| A1 | Duplication | HIGH | srs:FR-003, srs:FR-017 | Both describe user authentication | Merge into a single FR | BA |
+| A2 | Ambiguity | MEDIUM | srs:NFR-002 | "Low latency" has no metric | Add target value in ms | BA |
+| A3 | Coverage Gap | CRITICAL | srs:FR-008 | No linked user story | Create US or remove FR | BA |
+| A4 | Terminology | HIGH | srs, stories | "Wallet" vs "Balance" used interchangeably | Standardize in glossary | BA |
+| A5 | Invalid Ref | CRITICAL | ac:AC-003-01 | Links US-099 which does not exist | Fix reference | BA |
+| A6 | Underspecified Source | HIGH | srs:FR-012 | No `Source` field per v3.5.0+ template | Add Source field | BA |
+| A7 | Stakeholder Validation Gap | HIGH | brief:Assumption-3 | No Owner; past Validate by date | Convert to risk or validate | PM |
 
 ## Coverage Summary
 
@@ -89,17 +128,18 @@ Top 5 highest-severity items to address first, with recommended commands:
 1. {Finding ID} — {summary} → `/clarify FR-NNN` or `/revise [section]`
 ```
 
-**Severity scale:**
-- **CRITICAL** — blocks pipeline advancement or handoff (missing mandatory link, non-existent ID).
-- **HIGH** — significant quality risk (duplication, key term drift, missing metric for Must-priority item).
-- **MEDIUM** — quality concern, does not block (missing metric for Should-priority, minor overlap).
+**Severity scale** *(read from `00_principles_*.md` §6 if present, otherwise defaults below):*
+- **CRITICAL** — blocks pipeline advancement or handoff (missing mandatory link, non-existent ID, IEEE 830 traceability violation).
+- **HIGH** — significant quality risk (duplication, key term drift, missing metric for Must-priority item, Underspecified Source on a Must-priority artifact).
+- **MEDIUM** — quality concern, does not block (missing metric for Should-priority, minor overlap, IEEE 830 modifiability concern).
 - **LOW** — style or completeness suggestion.
 
 **Rules:**
 - Finding IDs are sequential: A1, A2, ...
 - Each finding references the exact artifact file and element ID.
+- Each finding has an **Owner** assigned (BA / PM / Tech Lead / Designer / Stakeholder name).
 - Coverage rows are generated only for artifact pairs where both files exist.
-- The report is read-only — no artifacts are modified.
+- The report is read-only — no artifacts are modified by `/analyze`. Use `/clarify` or `/revise` to act on findings.
 
 ## Iterative refinement
 

package/skills/clarify/SKILL.md

@@ -35,7 +35,7 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Analysis pass
 
-Scan the target artifact (or the specified section) for the following ambiguity categories:
+Scan the target artifact (or the specified section) for the following 11 ambiguity categories. Categories A–F are the original set; G–K are post-v3.5.0 additions that catch the gaps a senior BA would notice on a regulated or international project.
 
 ### A. Metrics-free adjectives
 Requirements containing words like "fast", "reliable", "scalable", "secure", "user-friendly", "simple", "efficient", "high performance", "low latency" without a measurable criterion.
@@ -47,7 +47,7 @@ Terms, abbreviations, or roles used in the artifact but not defined in the gloss
 Business rules or constraints that contradict each other or contradict rules in prior artifacts.
 
 ### D. Missing mandatory fields
-Elements that lack required fields per the artifact's own template (e.g., a FR without Priority, a US without Linked FR, an AC without a Then clause).
+Elements that lack required fields per the artifact's own template (e.g., a FR without Priority, a US without Linked FR, an AC without a Then clause, an FR without `Source` per the v3.5.0+ template).
 
 ### E. Ambiguous actors or scope
 Actions assigned to "the system", "the user", or "admin" where the specific role or external system is unclear.
@@ -55,27 +55,47 @@ Actions assigned to "the system", "the user", or "admin" where the specific role
 ### F. Duplicate or overlapping requirements
 Functionally equivalent or near-duplicate elements within the artifact or across artifacts.
 
+### G. Quantification gaps
+Numbers without units, frequency claims without a window ("every 5 minutes" vs "5 minutes p95"), thresholds without a measurement method, percentages without a base.
+
+### H. Time-zone gaps
+Timestamps without a stated time zone, "midnight" without specifying which time zone's midnight, business-hour rules without a region.
+
+### I. Currency gaps
+Monetary amounts without a currency code, multi-region pricing without a per-region table, conversion rules without a rate source.
+
+### J. Scale gaps
+"Users" without specifying which population (concurrent / registered / monthly active / daily active), "data" without volume, "requests" without rate.
+
+### K. Modal verb confusion
+Inconsistent use of must / shall / should / may. IEEE 830 expects strict modal discipline: "shall" = mandatory contractual obligation, "should" = recommended, "may" = permitted, "must" = required by external constraint. Mixed modals across the same artifact undermine acceptance.
+
 ## Output to the user
 
-Present findings as a numbered list of targeted questions. Each item references the exact location (section, element ID, line summary):
+Present findings as a structured table the user can answer in-place rather than as a numbered list of free-text questions. Each row references the exact location (section + element ID), the category, the question, and an empty answer cell:
 
 ```
-Ambiguities found in {artifact_file}:
-
-1. [FR-003] "The system must respond quickly" — what is the acceptable response time in milliseconds under normal load?
-2. [US-007] Role "Manager" is used here but not defined in the SRS Roles section — is this equivalent to "Admin", or a separate role?
-3. [NFR-002 vs FR-015] NFR-002 requires TLS 1.3 only, but FR-015 mentions "standard encryption" — should FR-015 explicitly reference NFR-002?
-4. [AC-005-02] The "Then" clause states "the system handles the error correctly" — what is the specific expected behavior (message shown, state reset, redirect)?
+Ambiguities found in {artifact_file} ({N} questions):
+
+| # | Location | Category | Question | Answer |
+|---|----------|----------|----------|--------|
+| 1 | FR-003 | A — Metrics-free | "The system must respond quickly" — what is the acceptable response time in ms under normal load? | _(awaiting answer)_ |
+| 2 | US-007 | B — Undefined term | Role "Manager" used here but not defined in `02_srs_*.md` Roles. Equivalent to "Admin"? Separate role? | _(awaiting answer)_ |
+| 3 | FR-015 vs NFR-002 | C — Conflicting | NFR-002 requires TLS 1.3 only; FR-015 mentions "standard encryption". Reference NFR-002 explicitly? | _(awaiting answer)_ |
+| 4 | AC-005-02 | A — Metrics-free | "Then" clause says "system handles the error correctly" — specific expected behaviour? | _(awaiting answer)_ |
+| 5 | FR-022 | I — Currency gap | "User charged a fee" — currency? per region? | _(awaiting answer)_ |
 ```
 
+The table format lets the user fill in answers in the rightmost column and copy-paste the table back. It also lets the user defer specific questions explicitly by writing `(deferred)` instead of an answer.
+
 If no ambiguities are found, state that clearly and suggest `/analyze` for a broader cross-artifact check.
 
 ## Resolution
 
-After presenting the list, wait for the user to answer. Accept answers inline (user can reply to all questions in one message or answer one by one). After all answers are received:
+After presenting the table, wait for the user to answer. Accept answers inline (the user can reply with the table filled in, or answer free-form by row number). After all answers are received:
 
 1. Apply the answers to update the artifact (rewrite affected elements).
-2. If an answer affects a prior artifact (e.g., a role definition belongs in the SRS), flag it and offer to update that artifact as well.
+2. **Ripple-effect check.** Before saving, identify any answer that affects a prior or downstream artifact (a role definition affects `/srs` Roles section AND `/stories` personas AND `/usecases` actors AND `/scenarios` personas; a new business rule affects `/srs` business rules AND `/ac` Given/When/Then conditions AND `/datadict` constraints AND `/apicontract` validation rules). For each ripple, list the affected files and offer to update them with `/revise`. Do not auto-modify unrelated artifacts without confirmation.
 3. Save the updated artifact.
 
 ## Closing message

package/skills/estimate/SKILL.md

@@ -35,12 +35,24 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Calibration interview
 
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended**, render variants in the user's language (rule 11), and wait for an answer.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/estimate` (e.g., `/estimate t-shirt, post-srs phase, +20% buffer`), parse it and skip the matching questions.
+
 Before estimating, ask the following (skip questions where the answer is already clear from context):
 
-1. **Scale:** Story Points (Fibonacci: 1 / 2 / 3 / 5 / 8 / 13 / 21), T-shirt sizes (XS / S / M / L / XL), or ideal person-days? _(default: Story Points Fibonacci)_
+1. **Scale:** Story Points (Fibonacci: 1 / 2 / 3 / 5 / 8 / 13 / 21), T-shirt sizes (XS / S / M / L / XL), or ideal person-days? **Recommended:** Fibonacci Story Points.
 2. **Reference stories:** Do you have known reference stories to anchor the scale? (e.g. "US-003 is a 3" or "login is an S") If yes, calibrate against those.
-3. **Team assumptions:** Full-stack developer pair? Or separate frontend/backend? _(affects day estimates only)_
+3. **Team assumptions:** Full-stack developer pair? Or separate frontend/backend? *(affects day estimates only)*
 4. **Out of scope for this estimate:** Any stories to skip (e.g., already estimated, on ice)?
+5. **Estimation phase (Cone of Uncertainty band)** — what's the maturity of the underlying artifacts? **Recommended:** select the band that matches the latest completed pipeline step.
+   - **Discovery / Brief only** — variance ±400% (4× spread); confidence label "Order of magnitude".
+   - **Post-SRS** — variance ±100%; confidence label "Rough order of magnitude (ROM)".
+   - **Post-AC + Use Cases** — variance ±50%; confidence label "Budget estimate".
+   - **Post-Wireframes + Datadict + APIcontract** — variance ±25%; confidence label "Definitive estimate".
+   - **Post-Implementation Plan** — variance ±10%; confidence label "Control estimate".
+6. **Risk multiplier** — apply a buffer for high-risk stories (those linked to 🔴 Critical or 🟡 High risks in `00_risks_*.md`)? **Recommended:** +20% on Critical-linked stories, +10% on High-linked.
+7. **Technical debt allocation** — % of velocity reserved for tech debt, bug-fixes, support? **Recommended:** 20% (industry baseline).
 
 If the user types `/estimate` without additional input and prior context is sufficient, proceed with defaults and state assumptions clearly.
 
@@ -62,6 +74,17 @@ Apply the reference stories as anchors. If no references are given, calibrate in
 
 Do not pad estimates — model what a reasonably skilled team would take, not a worst-case scenario.
 
+## Estimation discipline — what this skill is and is not
+
+This skill produces a **single-estimator analytical pass**. A senior BA running estimation in production would augment this with:
+
+- **Planning poker** — team-based estimation where each developer commits independently and outliers discuss before re-voting. The canonical agile-team estimation technique. `/estimate` cannot do this — it must be run with the dev team after the analytical pass.
+- **Wideband Delphi** — multi-round expert estimation with anonymous re-voting. Used when the team is distributed or when politics distort consensus. Same caveat — requires real humans.
+
+**Cone of Uncertainty.** Boehm's classic principle: estimates made early in the lifecycle (post-Brief, post-Discovery) carry up to 4× variance from the eventual reality, narrowing to 1.25× by the time implementation is detailed. This skill **always emits a confidence label** based on the user-selected estimation phase (calibration question 5). A 5 SP estimate at the post-Brief phase is "5 SP ± 400%"; the same estimate at the post-Implementation-Plan phase is "5 SP ± 10%".
+
+**Single-point estimates without a confidence band are dangerous** — they are misread as commitments. Every estimate produced by this skill carries an explicit confidence band tied to the Cone of Uncertainty.
+
 ## Output
 
 ### If scope ≤ 20 stories — update `03_stories_{slug}.md` in-place
@@ -79,23 +102,32 @@ Standalone estimation report with the full table.
 ```
 ## Estimation Summary — [PROJECT_NAME]
 Scale: [Story Points / T-shirt / Days]
-
-| US | Title | Epic | Estimate | Key drivers |
-|----|-------|------|---------|-------------|
-| US-001 | [Title] | E-01 | 3 SP | 2 AC scenarios, simple UI |
-| US-002 | [Title] | E-01 | 8 SP | external payment API, 4 AC scenarios |
-| US-003 | [Title] | E-02 | 13 SP | new domain area, complex state machine |
+Estimation phase: [Discovery / Brief / SRS / AC / Wireframes / Implementation Plan]
+Confidence band: [±400% / ±100% / ±50% / ±25% / ±10%]
+Confidence label: [Order of magnitude / ROM / Budget / Definitive / Control]
+
+| US | Title | Epic | Estimate | Confidence | Key drivers |
+|----|-------|------|----------|------------|-------------|
+| US-001 | [Title] | E-01 | 3 SP ± 25% | Definitive | 2 AC scenarios, simple UI |
+| US-002 | [Title] | E-01 | 8 SP ± 25% | Definitive | external payment API, 4 AC scenarios |
+| US-003 | [Title] | E-02 | 13 SP ± 50% | Budget | new domain area, complex state machine, RISK-02 +20% |
 ...
 
 | Metric | Value |
 |--------|-------|
 | Total stories estimated | [N] |
-| Total Story Points | [N] SP |
+| Total Story Points (point estimate) | [N] SP |
+| Total with confidence band | [N – N] SP ([low] – [high]) |
 | Largest story | US-[NNN] ([N] SP) — [reason] |
 | Stories ≥ 13 SP (consider splitting) | [N]: US-[NNN], … |
 | Average per story | [N] SP |
+| Risk-adjusted total (high-risk +20%) | [N] SP |
+| Tech debt reservation ([N]%) | [N] SP |
+| **Net feature capacity** | [N] SP |
 ```
 
+> ⚠️ **Single-estimator caveat.** This is an analytical estimation pass by a single estimator. For a real team commitment, run **planning poker** with the dev team using these numbers as the starting anchor and re-vote on any item where the team's estimate differs by more than one Fibonacci step.
+
 ### Splitting recommendations
 
 For any story estimated at 13 SP or higher (or XL), suggest a concrete split:

package/skills/export/SKILL.md

@@ -36,14 +36,20 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Format interview
 
-If the format is not specified, ask:
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended**, render variants in the user's language (rule 11), and wait for an answer.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/export` (e.g., `/export jira PROJ`, `/export github owner/repo`), parse it as a format + target hint and skip the matching questions.
 
-1. **Target tool:** Jira, GitHub Issues, Linear, CSV, or other?
-2. **Scope:** All stories, a specific epic, or specific story IDs?
-3. **Include AC?** Embed acceptance criteria in the issue body? (default: yes)
-4. **Jira-specific:** Project key (e.g., `PROJ`)? Epic link field name (default: `customfield_10014`)? Story Points field name (default: `story_points`)?
+If the format is not specified, ask the following (skip any question already answered by inline context):
+
+1. **Target tool:** Jira / GitHub Issues / Linear / CSV / Other? **Recommended:** Jira (most enterprise teams).
+2. **Scope:** All stories / a specific epic / specific story IDs?
+3. **Include AC?** Embed acceptance criteria in the issue body? **Recommended:** yes — without AC, the imported issue is just a story title.
+4. **Jira-specific:** Project key (e.g., `PROJ`)? Epic link field name (default: `customfield_10014`)? Story Points field name (default: `customfield_10016`)?
 5. **GitHub-specific:** Repository (e.g., `owner/repo`)? Label prefix for epics (e.g., `epic:`)? Milestone name (optional)?
 
+The exported issue body now includes **all v3.5.0+ stories template fields**: Persona (named, with context), Business Value Score, Size, Linked FR, Depends on (rendered as a "Blocked by" link in trackers that support it), Definition of Ready, INVEST self-check. Trackers that support custom fields (Jira, Linear) get them as separate fields; CSV gets extra columns; GitHub Issues embeds them in the issue body.
+
 ## Export formats
 
 ---
@@ -111,14 +117,14 @@ Or via CLI: jira import --file export_{slug}_jira.json
 
 Output file: `export_{slug}_github.json`
 
-Array of issue objects, one per story. Compatible with `gh` CLI batch import.
+Array of issue objects, one per story. Compatible with `gh` CLI batch import. The body embeds all v3.5.0+ stories template fields since GitHub Issues has no custom field support.
 
 ```json
 [
   {
     "title": "US-001: {Story title}",
-    "body": "## User Story\n\nAs a **{role}**, I want to **{action}**, so that **{benefit}**.\n\n---\n\n## Acceptance Criteria\n\n**Scenario 1 — {name}**\n- Given {precondition}\n- When {action}\n- Then {result}\n\n---\n\n**FR Reference:** FR-{NNN}\n**Priority:** {Must | Should | Could | Won't}\n**Estimate:** {N SP | —}",
-    "labels": ["{epic-label}", "user-story", "{priority-label}"],
+    "body": "## User Story\n\nAs **{persona — named persona with role and context}**, I want to **{action}**, so that **{benefit}**.\n\n---\n\n## Acceptance Criteria\n\n**Scenario 1 — {name}** *(AC-001-01)*\n- Given {precondition}\n- When {action}\n- Then {result}\n\n---\n\n## Traceability\n\n- **Linked FR:** FR-{NNN}\n- **Linked Use Case:** UC-{NNN}\n- **Linked Acceptance Criteria:** AC-001-01, AC-001-02, AC-001-03\n- **Linked NFR:** NFR-{NNN} (if applicable)\n- **Linked Wireframe:** WF-{NNN} (if applicable)\n\n---\n\n## Metadata\n\n- **Priority:** {Must | Should | Could | Won't}\n- **Business Value Score:** {1–5}\n- **Size:** {XS | S | M | L | XL}\n- **Estimate:** {N SP | —}\n- **Depends on:** US-{NNN}, US-{NNN}\n- **INVEST self-check:** Independent ✓ · Negotiable ✓ · Valuable ✓ · Estimable ✓ · Small ✓ · Testable ✓",
+    "labels": ["{epic-label}", "user-story", "{priority-label}", "value:{1-5}", "size:{xs-xl}"],
     "milestone": "{milestone-name-or-null}"
   }
 ]
@@ -181,11 +187,11 @@ Linear does not have a native bulk JSON import — use the Linear SDK or Zapier.
 Output file: `export_{slug}_stories.csv`
 
 ```
-ID,Title,Epic,Role,Action,Benefit,Priority,Estimate,FR Reference,AC Summary
-US-001,"{Story title}",E-01,"{role}","{action}","{benefit}",Must,3 SP,FR-001,"{first AC scenario summary}"
+ID,Title,Epic,Persona,Action,Benefit,Priority,Value,Size,Estimate,FR,UC,AC,NFR,WF,Depends on,AC Summary
+US-001,"{Story title}",E-01,"{persona name + role + context}","{action}","{benefit}",Must,5,M,3 SP,FR-001,UC-001,"AC-001-01;AC-001-02;AC-001-03",NFR-002,WF-005,—,"{first AC scenario summary}"
 ```
 
-Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets.
+Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets. Includes all v3.5.0+ stories template fields plus full cross-artifact traceability columns (FR / UC / AC / NFR / WF / Depends on) so a downstream tool can re-establish links without re-reading the source artifacts.
 
 ---
 

package/skills/glossary/SKILL.md

@@ -19,22 +19,27 @@ Examples:
 - `/glossary drift` — only show terminology drift findings, do not regenerate
 - `/glossary add [Term]: [Definition]` — manually add a term to the glossary
 
+**Standard alignment:** definition style follows the **Aristotelian definition** (genus + differentia + purpose) used by ISO 1087-1 (Terminology Work — Vocabulary). A well-formed definition names the **kind** the term belongs to (genus), then **what makes it specific** (differentia), and optionally its **purpose**. Example: "A **Workspace** is a tenant boundary [genus: tenant boundary] for billing and access control [differentia + purpose]." Bad definitions are circular ("a User is someone who uses the system") or self-referential ("a Subscription is a user's subscription") — `/glossary` rejects these and asks for a rewrite.
+
 ## Context loading
 
-0. If `00_principles_*.md` exists, load it — apply language convention (section 1) and ID naming convention (section 2).
+0. If `00_principles_*.md` exists, load it — apply language convention (section 1), ID naming convention (section 2), and any glossary-specific rules in section 8 (Project-Specific Notes).
 1. Scan the output directory for all existing artifacts. Load each one found:
+   - `00_discovery_{slug}.md` — concept terms, candidate audience names, reference product names
+   - `00_principles_{slug}.md` — convention names, mandatory category names
    - `01_brief_{slug}.md` — Brief Glossary section
    - `02_srs_{slug}.md` — Definitions and Abbreviations section, User Roles
-   - `03_stories_{slug}.md` — actor names used in "As a..." statements
-   - `04_usecases_{slug}.md` — actor names, system names
+   - `03_stories_{slug}.md` — persona names, role names used in "As a..." statements
+   - `04_usecases_{slug}.md` — actor names, system names, stakeholder names
    - `05_ac_{slug}.md` — state names, condition terms
-   - `06_nfr_{slug}.md` — category names, compliance standard names
-   - `07_datadict_{slug}.md` — entity names, field names, enum values
+   - `06_nfr_{slug}.md` — category names, compliance standard names, ISO 25010 sub-characteristics
+   - `07_datadict_{slug}.md` — entity names, field names, enum values, state machine state names
    - `07a_research_{slug}.md` — technology names, ADR decisions
-   - `08_apicontract_{slug}.md` — error codes, resource names
+   - `08_apicontract_{slug}.md` — error codes, resource names, scope names
    - `09_wireframes_{slug}.md` — screen names, UI component names
    - `10_scenarios_{slug}.md` — persona names, scenario types
    - `11_handoff_{slug}.md` — any additional terms
+   - `12_implplan_{slug}.md` — phase names, task ids, technology choices from the Tech Stack header
 2. Load `skills/references/domains/{domain}.md` — Domain Glossary section.
 3. If `00_glossary_{slug}.md` already exists, load it to merge rather than replace.
 
@@ -61,11 +66,12 @@ For each term, record:
 
 ### Step 2 — Terminology drift detection
 
-Identify cases where the same concept appears under different names in different artifacts:
+Identify cases where the same concept appears under different names in different artifacts. The recommendation must include a **justification** for the canonical name choice — not just "Customer" but "Customer because it appears earliest (in the Brief), most frequently (8 occurrences), and matches the domain reference":
 
 ```
 ⚠️ Drift: "Customer" (Brief), "User" (SRS), "Account" (Data Dictionary) — all refer to the registered buyer entity.
 → Recommend canonical name: "Customer"
+→ Justification: appears in the Brief (the source-of-truth glossary per project convention), used 8 times across artifacts vs 3 for "User" and 2 for "Account", and matches the e-commerce domain reference glossary.
 ```
 
 Flag drift as:
@@ -73,6 +79,17 @@ Flag drift as:
 - 🟡 **Medium** — synonym used in 1 artifact (easy to harmonise).
 - 🟢 **Low** — informal variation in a description field only.
 
+### Step 2b — Definition quality check
+
+For every term that has a definition, verify the definition follows the Aristotelian form (genus + differentia + purpose). Flag definitions that are:
+
+- 🔴 **Circular** — define the term using the term itself ("a User is a user of the system", "a Subscription is the user's subscription").
+- 🔴 **Self-referential** — define the term by quoting the artifact that uses it ("a Workspace is the workspace described in section 2").
+- 🟡 **Missing genus** — definition lists features but never names the kind ("Workspace: has billing, members, settings" — what *kind of thing* is it?).
+- 🟡 **Missing differentia** — names the genus but doesn't distinguish from siblings ("a Workspace is a container").
+
+The drift report includes a "Definition quality" sub-section that lists all weak definitions with a recommended rewrite. Senior BAs catch this on every glossary review.
+
 ### Step 3 — Undefined term detection
 
 Identify terms used in requirements but not defined anywhere in the glossary or domain reference: