@kudusov.takhir/ba-toolkit 3.7.0 → 3.8.1

package/CHANGELOG.md

@@ -11,6 +11,62 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.8.1] — 2026-04-10
+
+### Fixed
+
+- **`/discovery` now updates the `**Domain:**` field inside the `AGENTS.md` managed block.** Reported as "if you change the domain in `/discovery`, the AGENTS.md keeps the original init domain". Root cause: the v3.4.0+ instructions in `skills/discovery/SKILL.md` §6 said *"do not touch the managed block"* with no exception, so the AI dutifully left the domain stale even though the discovery artifact §8 recommended a different one. The fix is a targeted exception in the SKILL.md text — `/discovery` is the canonical source of truth for the project domain after `init`, and the `**Domain:**` line is the only managed-block field it may surgically update (every other managed-block field — Project, Slug, Language, Output folder, the auto-generated date comment — stays owned by `ba-toolkit init`). The reply now also mentions the domain change explicitly so the user sees that AGENTS.md was synced. Content fix only — no changes to `bin/ba-toolkit.js`, no changes to tests, no changes to skill behaviour beyond the targeted exception.
+
+---
+
+## [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
@@ -650,7 +706,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.7.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.8.1...HEAD
+[3.8.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.8.0...v3.8.1
+[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

package/package.json

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

@@ -127,7 +127,9 @@ Things we don't yet know and need to learn before committing real resources.
 
 `ba-toolkit init` already created `AGENTS.md` next to where the artifact lives — typically in the current working directory (the user is expected to `cd output/<slug>` after running init). After saving `00_discovery_{slug}.md`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree if cwd has none, for legacy v3.0 single-project layouts).
 
-**Update only the `## Pipeline Status` row for `/discovery`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename in the `File` column. **Do not touch the managed block** (`<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->`) — that's owned by `ba-toolkit init`. **Do not recreate the file at the repo root.** **Do not add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template and would be ignored by future runs.
+**Update only the `## Pipeline Status` row for `/discovery`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename in the `File` column. **Do not recreate the file at the repo root.** **Do not add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template and would be ignored by future runs.
+
+**Domain field exception (managed block).** `/discovery` is the canonical source of truth for the project domain after `ba-toolkit init`. After saving `00_discovery_{slug}.md`, compare the recommended domain in §8 of the discovery artifact against the `**Domain:**` line inside the managed block of `AGENTS.md`. **If they differ, surgically update only that single line** to the new value — do not modify any other managed-block field (`**Project:**`, `**Slug:**`, `**Language:**`, `**Output folder:**`, the auto-generated date comment). Mention the change in the user-facing reply: "Updated the project domain in AGENTS.md from `<old>` to `<new>` based on the discovery recommendation." This is the only managed-block field `/discovery` may touch; everything else inside `<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->` remains owned by `ba-toolkit init`.
 
 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.2 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.
 

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/handoff/SKILL.md

@@ -22,13 +22,15 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Generation
 
-No interview. All content is derived from the existing artifacts.
+No interview. All content is derived from the existing artifacts. The full template lives at `references/templates/handoff-template.md` and is the single source of truth — including the full inventory of pipeline-stage and cross-cutting artifacts (`/discovery`, `/principles`, `/implement-plan`, `/sprint`, `/risk`, `/glossary`, `/trace`, `/analyze`, `/estimate`), the Brief Goal → FR / FR → NFR / FR → API forward-traceability tables, the ADR summary, and the formal Sign-off section.
 
 **File:** `11_handoff_{slug}.md`
 
 ```markdown
 # Development Handoff: {Project Name}
 
+**Version:** 1.0
+**Status:** Draft | In Review | Approved
 **Date:** {date}
 **Domain:** {domain}
 **Pipeline completion:** {n}/{total} steps completed
@@ -37,19 +39,36 @@ No interview. All content is derived from the existing artifacts.
 
 ## 1. Artifact Inventory
 
-| Artifact | File | Status | Key numbers |
-|----------|------|--------|-------------|
-| Project Brief | `01_brief_{slug}.md` | ✓ Complete | {n} goals, {n} risks |
-| SRS | `02_srs_{slug}.md` | ✓ Complete | {n} FR ({must}/{should}/{could}/{wont}) |
-| User Stories | `03_stories_{slug}.md` | ✓ Complete | {n} stories across {n} epics |
-| Use Cases | `04_usecases_{slug}.md` | ✓ / ✗ Missing | {n} UC |
-| Acceptance Criteria | `05_ac_{slug}.md` | ✓ / ✗ Missing | {n} AC |
-| NFR | `06_nfr_{slug}.md` | ✓ / ✗ Missing | {n} NFR across {n} categories |
-| Research | `07a_research_{slug}.md` | ✓ / ✗ Missing / — Not run | {tech decisions} |
-| Data Dictionary | `07_datadict_{slug}.md` | ✓ / ✗ Missing | {n} entities, {n} attributes |
-| API Contract | `08_apicontract_{slug}.md` | ✓ / ✗ Missing | {n} endpoints |
-| Wireframes | `09_wireframes_{slug}.md` | ✓ / ✗ Missing | {n} screens |
-| Scenarios | `10_scenarios_{slug}.md` | ✓ / ✗ Missing / — Not run | {n} scenarios |
+### Pipeline-stage artifacts
+
+| Stage | Artifact | File | Status | Key numbers |
+|-------|----------|------|--------|-------------|
+| 0 | Discovery | `00_discovery_{slug}.md` | ✓ / ✗ Missing / — Not run | {recommended domain, MVP feature count} |
+| 0a | Principles | `00_principles_{slug}.md` | ✓ / ✗ Missing / — Not run | {testing strategy, ID conventions, NFR baseline characteristics} |
+| 1 | Project Brief | `01_brief_{slug}.md` | ✓ Complete | {n} goals, {n} stakeholders, {n} risks, {n} assumptions |
+| 2 | SRS | `02_srs_{slug}.md` | ✓ Complete | {n} FR ({must}/{should}/{could}/{wont}) |
+| 3 | User Stories | `03_stories_{slug}.md` | ✓ Complete | {n} stories across {n} epics |
+| 4 | Use Cases | `04_usecases_{slug}.md` | ✓ / ✗ Missing | {n} UC |
+| 5 | Acceptance Criteria | `05_ac_{slug}.md` | ✓ / ✗ Missing | {n} AC ({pos}/{neg}/{boundary}/{perf}) |
+| 6 | NFR | `06_nfr_{slug}.md` | ✓ / ✗ Missing | {n} NFR across {n} ISO 25010 characteristics |
+| 7 | Data Dictionary | `07_datadict_{slug}.md` | ✓ / ✗ Missing | {n} entities, {n} attributes |
+| 7a | Research | `07a_research_{slug}.md` | ✓ / ✗ Missing / — Not run | {n} ADRs, {n} integrations |
+| 8 | API Contract | `08_apicontract_{slug}.md` | ✓ / ✗ Missing | {n} endpoints |
+| 9 | Wireframes | `09_wireframes_{slug}.md` | ✓ / ✗ Missing | {n} screens |
+| 10 | Scenarios | `10_scenarios_{slug}.md` | ✓ / ✗ Missing / — Not run | {n} scenarios |
+| 11 | Handoff | `11_handoff_{slug}.md` | This document | — |
+| 12 | Implementation Plan | `12_implplan_{slug}.md` | ✓ / ✗ Missing / — Not run | {n} phases, {n} tasks |
+
+### Cross-cutting artifacts
+
+| Tool | File | Status | Key numbers |
+|------|------|--------|-------------|
+| Trace | `00_trace_{slug}.md` | ✓ / — Not run | Overall coverage {n}% |
+| Analyze | `00_analyze_{slug}.md` | ✓ / — Not run | {n} CRITICAL, {n} HIGH findings |
+| Risk | `00_risks_{slug}.md` | ✓ / — Not run | {n} risks ({n} Critical / {n} High) |
+| Sprint | `00_sprint_{slug}.md` | ✓ / — Not run | {n} sprints, {n} weeks |
+| Glossary | `00_glossary_{slug}.md` | ✓ / — Not run | {n} terms, {n} drift findings |
+| Estimate | inline in stories or `00_estimate_{slug}.md` | ✓ / — Not run | {n} SP total ± {confidence band} |
 
 ---
 
@@ -68,14 +87,18 @@ Must-priority items confirmed for the first release:
 ## 3. Traceability Coverage
 
 | Chain | Coverage |
-|-------|---------|
+|-------|----------|
+| Brief Goal → FR | {n}% ({uncovered} goals uncovered) |
 | FR → US | {n}% ({uncovered} uncovered) |
 | US → UC | {n}% |
-| US → AC | {n}% |
+| US → AC (Positive / Negative / Boundary) | {n}% / {n}% / {n}% |
 | FR → NFR | {n}% |
-| Entity → FR/US | {n}% |
-| Endpoint → FR/US | {n}% |
-| WF → US | {n}% |
+| FR → Entity | {n}% |
+| FR → API Endpoint | {n}% |
+| US → WF | {n}% |
+| US → Scenario | {n}% |
+| FR → Implementation Task (if `12_implplan` exists) | {n}% |
+| NFR → ADR | {n}% |
 
 {If coverage is below 100% for any CRITICAL chain, list uncovered items explicitly.}
 
@@ -114,13 +137,34 @@ Must-priority items confirmed for the first release:
 
 ---
 
-## 7. Artifact Files Reference
+## 7. Architecture Decision Summary
+
+Top architectural decisions from `07a_research_{slug}.md`. Dev team should read each linked ADR before starting the corresponding phase.
+
+| ADR | Decision | Drivers | Phase impact |
+|-----|----------|---------|--------------|
+| ADR-001 | {chosen tech for layer X} | NFR-{NNN}, FR-{NNN} | Phase {N} of `/implement-plan` |
+| ADR-002 | {decision} | {drivers} | {phase impact} |
+
+## 8. Artifact Files Reference
 
 All files are located in: `{output_directory}`
 
 ```
 {file tree of all generated artifacts}
 ```
+
+## 9. Sign-off
+
+Formal acceptance of the handoff package. Signing this section means the development team agrees the BA package is sufficient to begin implementation.
+
+| Role | Name | Sign-off Date | Notes |
+|------|------|---------------|-------|
+| Business Analyst | {name} | {date} | {notes} |
+| Product Manager | {name} | {date} | {notes} |
+| Tech Lead | {name} | {date} | {notes} |
+| QA Lead | {name} | {date} | {notes} |
+| Stakeholder | {name} | {date} | {notes} |
 ```
 
 ## Iterative refinement

package/skills/implement-plan/SKILL.md

@@ -69,7 +69,10 @@ Required topics for the calibration interview (skip any topic already answered b
 3. Database (engine, version, hosting model).
 4. Hosting / deployment target.
 5. Auth / identity approach (in-house vs. SSO vs. managed service).
-6. Mandatory integrations from `02_srs` (carry over verbatim — do not re-decide them).
+6. **Observability platform** — logging, metrics, traces stack (Datadog / New Relic / Grafana / OpenTelemetry self-hosted). Drives Phase 8 (Quality & NFRs) tasks.
+7. **CI/CD platform** — GitHub Actions / GitLab CI / CircleCI / Jenkins / other. Drives Phase 1 (Foundation) tasks.
+8. **Secret management** — environment variables / Vault / AWS Secrets Manager / Doppler / 1Password CLI. Drives Phase 1 (Foundation) tasks.
+9. Mandatory integrations from `02_srs` (carry over verbatim — do not re-decide them).
 
 **Step 3 — TBD slots.** If neither `/research` nor the interview yields a value for a slot (e.g. user picked "Other" without a concrete answer), record `[TBD: <slot>]` in the output's "Tech stack" header AND add a row to the "Open Assumptions" section so the AI coding agent knows it must ask before starting any task that touches that slot.
 
@@ -107,7 +110,7 @@ Each task is one atomic, AI-actionable unit of work. Rules:
 - **files:** list of file paths the AI agent should create or modify (best-effort; framework-dependent). Optional. Examples: `src/db/schema.sql`, `apps/api/src/auth/login.controller.ts`. **If unknown, omit rather than guess.**
 - **definitionOfDone:** bullet list of acceptance hooks. Pull from the linked AC where possible ("AC-001-03 passes", "endpoint returns 401 on invalid credentials"). Always include a type-check / lint hook on backend tasks and a render-state hook on UI tasks.
 
-Within a phase, order tasks so each task's `dependsOn` list points only at tasks already listed. Risk-elevated tasks (mitigating Critical / High risks from `00_risks_*.md`) come earliest within their priority tier.
+Within a phase, order tasks so each task's `dependsOn` list points only at tasks already listed. **Risk-elevated tasks come earliest within their phase**: any task whose `references` include an FR / US / NFR linked to a 🔴 Critical or 🟡 High risk in `00_risks_*.md` is pulled to the front of its phase, ahead of equally-prioritised tasks. Rationale: validate risky bets early, when there's still time to pivot. Tag risk-elevated tasks with `**Risk:** RISK-NN ↑` next to their title so the AI agent and the human reviewer both see the elevation reason.
 
 ### 7. Generation
 
@@ -132,6 +135,9 @@ Within a phase, order tasks so each task's `dependsOn` list points only at tasks
 | Database | {…} | … |
 | Hosting | {…} | … |
 | Auth | {…} | … |
+| Observability (logs / metrics / traces) | {…} | … |
+| CI / CD | {…} | … |
+| Secret management | {…} | … |
 | Mandatory integrations | {…} | … |
 
 ---

package/skills/principles/SKILL.md

@@ -38,10 +38,13 @@ If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwis
 **Required topics:**
 1. Artifact language — which language should all artifacts be generated in? (default: the language of the user's first message)
 2. Traceability strictness — should every Must-priority US require a Use Case, or only US with complex flows? (default: only complex flows)
-3. NFR baseline — which additional NFR categories are always required beyond the domain defaults? (e.g., GDPR compliance, WCAG accessibility)
-4. Definition of Ready — any project-specific acceptance criteria for finalizing an artifact? (e.g., stakeholder sign-off, specific review steps)
+3. NFR baseline — which **ISO/IEC 25010** quality characteristics are mandatory beyond the domain defaults? (Performance Efficiency / Reliability / Security / Compatibility / Usability / Maintainability / Portability / Functional Suitability — `/nfr` reads this list verbatim and treats it as a checklist).
+4. Definition of Ready — any project-specific acceptance criteria for finalizing an artifact beyond the `v3.7.0+` baseline DoR per artifact type listed in §4 below? (e.g., stakeholder sign-off, specific review steps).
 5. Quality gate — at what severity level should `/analyze` findings block `/done`? (default: CRITICAL only)
 6. Output folder structure — save all artifacts flat in the output directory (default), or inside a `{slug}/` subfolder? (useful when managing multiple projects side by side)
+7. **Testing strategy** — TDD (tests before implementation), tests-after, integration-only, manual-only, none? Drives whether `/implement-plan` task templates embed "Tests to write first" blocks. **Recommended:** TDD for production-grade systems; tests-after for prototypes; manual-only or none for spike work. *(This is the principles-based approach to the testing-discipline question that batch 6 item 2 surfaced — the right place to declare a testing strategy is here, not as a separate skill.)*
+8. **Stakeholder decision authority** — who has sign-off authority on changes to these principles? Captured by name and role. Without this, principle changes become contentious mid-project.
+9. **Code review and branching policy** — trunk-based / GitFlow / GitHub flow? Required reviewers per PR? `/implement-plan` and downstream skills assume one of these defaults but the principles file is the source of truth.
 
 ### 4. Generation
 

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

@@ -1,8 +1,11 @@
 # Discovery: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Concept (pre-brief) | In Review | Locked
 **Slug:** [SLUG]
 **Date:** [DATE]
-**Status:** Concept (pre-brief)
+**Decision date:** [DATE — when the recommended domain was locked in]
+**Decision owner:** [Name + role]
 
 ## 1. Problem Space
 
@@ -61,3 +64,23 @@ Things we do not yet know and need to learn before committing real resources.
 - **Domain:** [chosen domain]
 - **Scope hint for `/brief`:** [one-sentence summary the user can paste as inline context: `/brief [scope hint]`]
 - **Suggested first interview focus in `/brief`:** [1–2 topics from this discovery doc that are now firm enough to anchor the brief]
+
+---
+
+## 9. Hypotheses → Brief Goals (filled in after `/brief`)
+
+Forward traceability from the discovery hypotheses to the brief business goals they became. Filled in by `/brief` when it consumes this discovery artifact, then preserved here for retrospective validation: 3 months after launch, did the chosen audience hypothesis hold? Did the MVP features that the differentiation angle predicted would matter actually drive adoption?
+
+| Discovery section | Hypothesis | Brief Goal G-N | Status |
+|-------------------|------------|----------------|--------|
+| §1 Problem space | [problem statement] | G-1 | Validated / Refined / Disproved / Pending |
+| §2 Audience (Primary) | [primary segment] | G-2 | Validated / Refined / Disproved / Pending |
+| §5 MVP feature 1 | [feature] | G-3 | Validated / Refined / Disproved / Pending |
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| [name] | [role] | [YYYY-MM-DD] | [optional notes] |

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

@@ -1,5 +1,7 @@
 # Development Handoff Package: [PROJECT_NAME]
 
+**Version:** 1.0
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
@@ -8,31 +10,47 @@
 
 ---
 
-## Artifact Inventory
-
-| Artifact | File | Status | Last Updated |
-|---------|------|--------|-------------|
-| Principles | `00_principles_[SLUG].md` | ✅ Complete | [DATE] |
-| Project Brief | `01_brief_[SLUG].md` | ✅ Complete | [DATE] |
-| SRS | `02_srs_[SLUG].md` | ✅ Complete | [DATE] |
-| User Stories | `03_stories_[SLUG].md` | ✅ Complete | [DATE] |
-| Use Cases | `04_usecases_[SLUG].md` | ✅ Complete | [DATE] |
-| Acceptance Criteria | `05_ac_[SLUG].md` | ✅ Complete | [DATE] |
-| NFR | `06_nfr_[SLUG].md` | ✅ Complete | [DATE] |
-| Data Dictionary | `07_datadict_[SLUG].md` | ✅ Complete | [DATE] |
-| Research / ADRs | `07a_research_[SLUG].md` | ✅ Complete | [DATE] |
-| API Contract | `08_apicontract_[SLUG].md` | ✅ Complete | [DATE] |
-| Wireframes | `09_wireframes_[SLUG].md` | ✅ Complete | [DATE] |
-| Validation Scenarios | `10_scenarios_[SLUG].md` | ✅ Complete | [DATE] |
+## 1. Artifact Inventory
+
+### Pipeline-stage artifacts
+
+| Stage | Artifact | File | Status | Last Updated |
+|-------|----------|------|--------|--------------|
+| 0 | Discovery | `00_discovery_[SLUG].md` | ✅ Complete / — Not run | [DATE] |
+| 0a | Principles | `00_principles_[SLUG].md` | ✅ Complete / — Not run | [DATE] |
+| 1 | Project Brief | `01_brief_[SLUG].md` | ✅ Complete | [DATE] |
+| 2 | SRS | `02_srs_[SLUG].md` | ✅ Complete | [DATE] |
+| 3 | User Stories | `03_stories_[SLUG].md` | ✅ Complete | [DATE] |
+| 4 | Use Cases | `04_usecases_[SLUG].md` | ✅ Complete | [DATE] |
+| 5 | Acceptance Criteria | `05_ac_[SLUG].md` | ✅ Complete | [DATE] |
+| 6 | NFR | `06_nfr_[SLUG].md` | ✅ Complete | [DATE] |
+| 7 | Data Dictionary | `07_datadict_[SLUG].md` | ✅ Complete | [DATE] |
+| 7a | Research / ADRs | `07a_research_[SLUG].md` | ✅ Complete | [DATE] |
+| 8 | API Contract | `08_apicontract_[SLUG].md` | ✅ Complete | [DATE] |
+| 9 | Wireframes | `09_wireframes_[SLUG].md` | ✅ Complete | [DATE] |
+| 10 | Validation Scenarios | `10_scenarios_[SLUG].md` | ✅ Complete | [DATE] |
+| 11 | Handoff | `11_handoff_[SLUG].md` | This document | [DATE] |
+| 12 | Implementation Plan | `12_implplan_[SLUG].md` | ✅ Complete / — Not run | [DATE] |
+
+### Cross-cutting artifacts
+
+| Tool | File | Status | Last Updated |
+|------|------|--------|--------------|
+| Trace | `00_trace_[SLUG].md` | ✅ / — Not run | [DATE] |
+| Analyze | `00_analyze_[SLUG].md` | ✅ / — Not run | [DATE] |
+| Risk Register | `00_risks_[SLUG].md` | ✅ / — Not run | [DATE] |
+| Sprint Plan | `00_sprint_[SLUG].md` | ✅ / — Not run | [DATE] |
+| Glossary | `00_glossary_[SLUG].md` | ✅ / — Not run | [DATE] |
+| Estimate | inline in `03_stories_[SLUG].md` or `00_estimate_[SLUG].md` | ✅ / — Not run | [DATE] |
 
 ---
 
-## MVP Scope
+## 2. MVP Scope
 
 **In scope for MVP:**
 
 | ID | Title | Type | Priority |
-|----|-------|------|---------|
+|----|-------|------|----------|
 | FR-[NNN] | [Title] | Functional | Must |
 | US-[NNN] | [Story title] | Story | Must |
 
@@ -44,34 +62,43 @@
 
 ---
 
-## Traceability Coverage
+## 3. Traceability Coverage
 
-| Link | Coverage | Gap |
-|------|---------|-----|
+| Chain | Coverage | Gap |
+|-------|----------|-----|
+| Brief Goal → FR | [N]% | [N goals uncovered] |
 | FR → US | [N]% | [N orphaned FRs] |
-| US → AC | [N]% | [N stories without AC] |
-| FR → API | [N]% | [N FRs without endpoint] |
+| US → UC | [N]% | [N stories without UC] |
+| US → AC (Positive / Negative / Boundary) | [N]% / [N]% / [N]% | [N stories without negative AC] |
+| FR → NFR | [N]% | [N FRs without an NFR] |
+| FR → Entity | [N]% | [N FRs without entity] |
+| FR → API Endpoint | [N]% | [N FRs without endpoint] |
 | US → WF | [N]% | [N stories without wireframe] |
+| US → Scenario | [N]% | [N stories without scenario] |
+| FR → Implementation Task | [N]% | [N FRs without task] |
+| NFR → ADR | [N]% | [N NFRs without architectural decision] |
 
 ---
 
-## Open Items
+## 4. Open Items
 
 | # | Type | Description | Owner | Priority |
-|---|------|-------------|-------|---------|
-| 1 | [Decision \| Clarification \| Dependency] | [Description] | [Role] | P1 / P2 / P3 |
+|---|------|-------------|-------|----------|
+| 1 | Decision / Clarification / Dependency / Risk | [Description] | [Role] | P1 / P2 / P3 |
 
 ---
 
-## Top Risks for Development
+## 5. Top Risks for Development
 
-| # | Risk | Probability | Impact | Mitigation |
-|---|------|-------------|--------|-----------|
-| 1 | [Risk] | High / Med / Low | High / Med / Low | [Mitigation] |
+| # | Risk | Probability | Impact | Velocity | Treatment | Mitigation |
+|---|------|-------------|--------|----------|-----------|------------|
+| 1 | [Risk] | High / Med / Low | High / Med / Low | Days / Weeks / Months | Avoid / Reduce / Transfer / Accept | [Mitigation] |
+
+*(Pulled from `00_risks_[SLUG].md` — top 5 by score.)*
 
 ---
 
-## Recommended Development Sequence
+## 6. Recommended Development Sequence
 
 1. **[Phase / Sprint 1]** — [What to build first and why]
 2. **[Phase / Sprint 2]** — [Next priority]
@@ -79,14 +106,32 @@
 
 _Rationale: [Why this sequencing — dependencies, risk, user value.]_
 
+If `12_implplan_[SLUG].md` has been generated, use the phase ladder + Task DAG appendix from there as the canonical sequence; the recommendation above is the human-friendly summary.
+
+---
+
+## 7. Architecture Decision Summary
+
+Top architectural decisions from `07a_research_[SLUG].md`. Dev team should read each linked ADR before starting the corresponding phase.
+
+| ADR | Decision | Drivers | Phase impact |
+|-----|----------|---------|--------------|
+| ADR-001 | [chosen tech for layer X] | NFR-[NNN], FR-[NNN] | Phase [N] of `/implement-plan` |
+| ADR-002 | [decision] | [drivers] | [phase impact] |
+
 ---
 
-## Artifact Files Reference
+## 8. Artifact Files Reference
 
 ```
 output/[SLUG]/
+├── 00_discovery_[SLUG].md
 ├── 00_principles_[SLUG].md
 ├── 00_analyze_[SLUG].md
+├── 00_glossary_[SLUG].md
+├── 00_risks_[SLUG].md
+├── 00_sprint_[SLUG].md
+├── 00_trace_[SLUG].md
 ├── 01_brief_[SLUG].md
 ├── 02_srs_[SLUG].md
 ├── 03_stories_[SLUG].md
@@ -98,5 +143,20 @@ output/[SLUG]/
 ├── 08_apicontract_[SLUG].md
 ├── 09_wireframes_[SLUG].md
 ├── 10_scenarios_[SLUG].md
-└── 11_handoff_[SLUG].md     ← this document
+├── 11_handoff_[SLUG].md     ← this document
+└── 12_implplan_[SLUG].md
 ```
+
+---
+
+## 9. Sign-off
+
+Formal acceptance of the handoff package. Signing this section means the development team agrees the BA package is sufficient to begin implementation. Outstanding open items (§4) and uncovered traceability chains (§3) must be acknowledged or resolved before sign-off.
+
+| Role | Name | Sign-off Date | Notes |
+|------|------|---------------|-------|
+| Business Analyst | [name] | [YYYY-MM-DD] | [notes] |
+| Product Manager | [name] | [YYYY-MM-DD] | [notes] |
+| Tech Lead | [name] | [YYYY-MM-DD] | [notes] |
+| QA Lead | [name] | [YYYY-MM-DD] | [notes] |
+| Stakeholder / Sponsor | [name] | [YYYY-MM-DD] | [notes] |

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

@@ -1,6 +1,7 @@
 # Project Principles: [PROJECT_NAME]
 
 **Version:** 1.0
+**Status:** Draft | In Review | Approved
 **Date:** [DATE]
 **Domain:** [DOMAIN]
 **Slug:** [SLUG]
@@ -23,6 +24,11 @@ All artifacts are generated in: [LANGUAGE]
 | API Endpoints | REST path | POST /users |
 | Wireframes | WF-NNN | WF-001 |
 | Validation Scenarios | SC-NNN | SC-001 |
+| Risks | RISK-NN | RISK-01 |
+| Sprints | SP-NN | SP-01 |
+| Implementation Tasks | T-NN-NNN | T-04-007 |
+| Analyse findings | A-NN | A-01 |
+| Brief Goals | G-N | G-1 |
 
 ## 3. Traceability Requirements
 
@@ -46,56 +52,109 @@ Optional links — violations flagged as **MEDIUM**:
 
 ## 4. Definition of Ready
 
-An artifact is ready to `/done` when all of the following are true:
+An artifact is ready to `/done` when all of the following are true. The baseline below mirrors the v3.7.0+ artifact-template field set; project-specific additions go in §8.
 
 ### Functional Requirement (FR)
 - [ ] Description present and unambiguous.
 - [ ] Actor identified (not "the system" or "the user" without role).
 - [ ] Priority assigned (MoSCoW).
 - [ ] Input/Output specified.
+- [ ] **Source** field present (which stakeholder, brief goal G-N, regulatory requirement, or parent FR drove this).
+- [ ] **Verification method** specified (Test / Demo / Inspection / Analysis per IEEE 830 §7).
+- [ ] **Rationale** documented (why this requirement exists, not just what).
+- [ ] FR is grouped under a feature area (`### 3.N` in `02_srs_*.md`).
 
 ### User Story (US)
-- [ ] Role, Action, and Value filled.
-- [ ] Priority assigned.
+- [ ] Persona named (named persona with role and one-line context, not bare job title).
+- [ ] Action and Value filled.
+- [ ] Priority assigned (MoSCoW).
+- [ ] **Business Value Score** assigned (1–5 or H/M/L).
+- [ ] **Size** estimate present (XS / S / M / L / XL or Story Points).
 - [ ] Linked FR reference present.
+- [ ] **Depends on** field set (other story IDs or `—`).
+- [ ] **Definition of Ready** checklist or reference to this principles section.
+- [ ] **INVEST self-check** confirms Independent · Negotiable · Valuable · Estimable · Small · Testable.
 
 ### Use Case (UC)
-- [ ] Actor, Preconditions, Main Flow, and at least one Exceptional Flow present.
-- [ ] Linked US reference present.
+- [ ] **Goal in Context** present (which Brief goal G-N this UC serves).
+- [ ] **Scope** specified (System / Subsystem / Component) and **Level** specified (User-goal / Summary / Subfunction).
+- [ ] Primary Actor and Supporting Actors listed.
+- [ ] **Stakeholders and Interests** table present (Cockburn discipline — at least 2 stakeholders).
+- [ ] Pre-conditions and Trigger present.
+- [ ] Main Success Scenario as a numbered table.
+- [ ] At least one Exception Flow present.
+- [ ] **Success Guarantees** and **Minimal Guarantees** distinguished in post-conditions.
+- [ ] **Source** field present (linked US/FR).
 
 ### Acceptance Criterion (AC)
-- [ ] Given / When / Then all present and specific.
-- [ ] Type specified (positive / negative / boundary).
+- [ ] Given / When / Then all present, specific, and verifiable (no "the system handles correctly").
+- [ ] **Type** specified (Positive / Negative / Boundary / Performance / Security).
+- [ ] **Source** present (which business rule from `02_srs_*.md` drove this AC).
+- [ ] **Verification** method specified (Automated test / Manual test / Observed in production).
 - [ ] Linked US reference present.
+- [ ] Linked NFR present for performance and security ACs.
 
 ### NFR
-- [ ] Category specified.
+- [ ] **ISO/IEC 25010 characteristic** specified (one of the 8: Functional Suitability / Performance Efficiency / Compatibility / Usability / Reliability / Security / Maintainability / Portability).
 - [ ] Measurable metric present (numeric target, not adjective).
+- [ ] **Acceptance threshold** present separately from the metric.
 - [ ] Verification method specified.
+- [ ] **Source** present.
+- [ ] **Rationale** present.
+- [ ] Linked FR or US present.
 
 ### Data Entity
-- [ ] All attributes have types and constraints.
-- [ ] FK references point to existing entities.
+- [ ] **Source** field present (which FR/US introduced this entity).
+- [ ] **Owner** field present (which team curates this data).
+- [ ] **Sensitivity classification** present (Public / Internal / Confidential / PII / PCI / PHI / Financial).
+- [ ] All attributes have **logical types** (not DBMS-specific) and constraints.
+- [ ] FK references point to existing entities, with cascade rule specified.
+- [ ] **State machine** documented for entities with more than two distinct lifecycle states.
 
 ### API Endpoint
+- [ ] **Source** present (FR-NNN that drove this endpoint).
 - [ ] Request and Response schemas present.
 - [ ] At least one error code documented.
 - [ ] Linked FR/US present.
+- [ ] **Idempotency** marker present (Idempotent / Not idempotent / Idempotent via `Idempotency-Key` header).
+- [ ] **Required scope** specified (or "public" for unauthenticated paths).
+- [ ] **SLO** linked to an NFR.
+- [ ] **Verification** method specified (contract test / consumer-driven contract test / integration test).
 
 ### Wireframe (WF)
-- [ ] All four states present: default, loading, empty, error.
+- [ ] **Source** present (US-NNN this screen serves).
+- [ ] All **8 canonical states** described that apply: Default / Loading / Empty / Loaded / Partial / Success / Error / Disabled.
 - [ ] Navigation links (from / to) specified.
 - [ ] Linked US present.
+- [ ] **Linked AC** present (scenarios this screen verifies).
+- [ ] **Linked NFR** present for performance- and accessibility-sensitive screens.
+
+### Risk
+- [ ] **Probability**, **Impact**, **Velocity** scored (per ISO 31000 + PMBOK 7).
+- [ ] **Treatment strategy** classified (Avoid / Reduce / Transfer / Accept).
+- [ ] **Owner** assigned.
+- [ ] **Review cadence** set.
+
+### Implementation Task (T-NN-NNN, from `/implement-plan`)
+- [ ] At least one `references` id present (FR / US / AC / Entity / Endpoint / WF / SC).
+- [ ] `dependsOn` list points only at task ids that exist in the same plan.
+- [ ] `definitionOfDone` checklist present, with at least one hook tied to a linked AC.
+- [ ] Phase assignment matches the canonical 9-phase ladder.
 
-## 5. NFR Baseline
+## 5. NFR Baseline (ISO/IEC 25010)
 
-The following NFR categories are required regardless of domain:
+NFR categories follow **ISO/IEC 25010:2011** Software Quality Model. The following ISO 25010 characteristics are required for this project regardless of domain — `/nfr` reads this list verbatim and treats it as a mandatory checklist:
 
-- **Security:** authentication method, data encryption at rest and in transit.
-- **Availability:** uptime SLA with a numeric target.
-- **Compliance:** applicable laws and data retention policy.
+- **Security** — confidentiality (encryption at rest and in transit), authentication strength, audit trail.
+- **Reliability** — availability SLA with a numeric target, RTO / RPO for disaster recovery.
+- **Compatibility** — applicable laws and data retention policy *(historically labelled "Compliance" but maps to ISO 25010 Compatibility + Functional Suitability sub-characteristics)*.
 
-[ADDITIONAL_NFR_CATEGORIES]
+[ADDITIONAL_NFR_CATEGORIES — list other ISO 25010 characteristics that are mandatory for this project, e.g.:
+- **Performance Efficiency** — required if the project has user-facing latency or throughput targets.
+- **Usability** — required if WCAG 2.1 AA accessibility is mandated.
+- **Maintainability** — required if the project must hand off to a different team post-launch.
+- **Portability** — required if multi-cloud or vendor-neutral hosting is a constraint.
+]
 
 ## 6. Quality Gates
 
@@ -113,6 +172,50 @@ For `/analyze` findings:
 - `flat` (default) — all artifacts saved directly in the output directory.
 - `subfolder` — all artifacts saved under `{output_dir}/[SLUG]/`.
 
-## 8. Project-Specific Notes
+## 8. Testing Strategy
+
+**Strategy:** TDD | Tests-after | Integration-only | Manual-only | None
+
+| Strategy | Means | When `/implement-plan` task templates embed "Tests to write first" |
+|----------|-------|--------------------------------------------------------------------|
+| TDD | Tests written before implementation; red → green → refactor | Yes — every task with linked AC gets a "Tests to write first" sub-block |
+| Tests-after | Implementation first, tests immediately after | No — task DoD just lists the AC scenarios that must pass |
+| Integration-only | No unit tests; integration tests at the API or UI layer | No — integration test harness is set up in Phase 1 |
+| Manual-only | Tests are manual QA scripts run before release | No — task DoD references manual scenario IDs from `/scenarios` |
+| None | Prototype / spike — no automated tests at all | No — explicit `// no test` marker on every task |
+
+`/implement-plan` reads this section to decide whether to embed test specifications in each task. Default is **TDD** for production-grade systems.
+
+## 9. Code Review and Branching
+
+**Branching model:** trunk-based | GitHub flow | GitFlow | other
+**Required reviewers per PR:** [N]
+**Merge gate:** [CI green + N reviews / CODEOWNERS approval / specific reviewer]
+
+## 10. Stakeholder Decision Authority
+
+Who can approve a change to these principles, and to which sections.
+
+| Section | Decision authority | Notes |
+|---------|--------------------|-------|
+| §1 Language | [Role] | |
+| §2 ID Conventions | [Role] | |
+| §3 Traceability | [Role] | |
+| §4 Definition of Ready | [Role] | |
+| §5 NFR Baseline | [Role] | |
+| §6 Quality Gates | [Role] | |
+| §7 Output Structure | [Role] | |
+| §8 Testing Strategy | [Role] | |
+| §9 Branching | [Role] | |
+
+## 11. Project-Specific Notes
 
 [ADDITIONAL_CONVENTIONS]
+
+---
+
+## Approvals
+
+| Name | Role | Approval Date | Notes |
+|------|------|---------------|-------|
+| [name] | [role] | [YYYY-MM-DD] | [optional notes] |

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

@@ -1,57 +1,81 @@
 # Technology Research & Architecture Decisions: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
+**ADR format:** Michael Nygard format extended with Drivers and Alternatives Considered
 **References:** `02_srs_[SLUG].md`, `06_nfr_[SLUG].md`, `07_datadict_[SLUG].md`
 
+> The output of this research is the **primary tech-stack source** for `/implement-plan` (added in v3.4.0). The Tech Stack table at the bottom is read by `/implement-plan` to populate its header without re-asking the calibration interview.
+
 ---
 
 ## Architecture Decision Records (ADRs)
 
 ### ADR-001: [Decision Title]
 
-**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[NNN]
-**Date:** [DATE]
+| Field | Value |
+|-------|-------|
+| **Status** | Proposed / Accepted / Deprecated / Superseded by ADR-[NNN] |
+| **Proposal date** | [YYYY-MM-DD] |
+| **Decision date** | [YYYY-MM-DD when the decision was locked in] |
+| **Decision owner** | [Name + role] |
+
+**Drivers:** *(what forced this decision — reference specific FRs, NFRs, regulatory constraints, cost or time pressure)*
+- NFR-[NNN] — [why this NFR forces the decision]
+- FR-[NNN] — [why this FR forces the decision]
+- [Regulatory / cost / time-to-market constraint]
 
 **Context:**
-[What situation or requirement forces us to make this decision? Reference specific NFRs or FRs.]
+[What situation requires us to make this decision now. Background a future maintainer would need to understand the decision.]
 
-**Options Considered:**
+**Alternatives Considered:**
 
-| Option | Pros | Cons |
-|--------|------|------|
-| [Option A] | [pros] | [cons] |
-| [Option B] | [pros] | [cons] |
+| Option | Pros | Cons | Disqualifying factor |
+|--------|------|------|----------------------|
+| [Option A] | [pros] | [cons] | — |
+| [Option B] | [pros] | [cons] | [why ruled out] |
+| [Option C] | [pros] | [cons] | [why ruled out] |
 
-**Decision:** [Option A / B / other], because [rationale].
+**Decision:** [Option A / B / other], because [rationale anchored in the Drivers above].
 
 **Consequences:**
-- [Positive consequence]
-- [Trade-off or risk]
 
-**References:** NFR-[NNN], FR-[NNN]
+- **Positive:** [what becomes easier]
+- **Negative:** [trade-off or risk]
+- **Neutral:** [side effect that is neither good nor bad but worth noting]
 
 ---
 
 ### ADR-002: [Decision Title]
 
-**Status:** Proposed | Accepted
-**Date:** [DATE]
+| Field | Value |
+|-------|-------|
+| **Status** | [status] |
+| **Proposal date** | [date] |
+| **Decision date** | [date] |
+| **Decision owner** | [Name + role] |
 
-**Context:** [Context for this decision.]
+**Drivers:**
+- [driver]
 
-**Options Considered:**
+**Context:** [Context.]
 
-| Option | Pros | Cons |
-|--------|------|------|
-| [Option A] | [pros] | [cons] |
-| [Option B] | [pros] | [cons] |
+**Alternatives Considered:**
+
+| Option | Pros | Cons | Disqualifying factor |
+|--------|------|------|----------------------|
+| [Option A] | [pros] | [cons] | — |
+| [Option B] | [pros] | [cons] | [why ruled out] |
 
 **Decision:** [Chosen option and rationale.]
 
 **Consequences:**
-- [Consequence]
+
+- **Positive:** [consequence]
+- **Negative:** [consequence]
 
 <!-- Repeat ADR block for each major architectural decision. -->
 
@@ -95,5 +119,33 @@
 ## Open Questions
 
 | # | Question | Owner | Target Date |
-|---|---------|-------|-------------|
+|---|----------|-------|-------------|
 | 1 | [Unresolved technical question] | [Role] | [Date] |
+
+---
+
+## Tech Stack Summary *(consumed by `/implement-plan`)*
+
+This table is the primary tech-stack source for `/implement-plan`. Every row should have a concrete value (or `[TBD: <slot>]` if the decision is genuinely deferred). `/implement-plan` skips its own calibration interview when this table is complete.
+
+| Layer | Choice | Source ADR |
+|-------|--------|------------|
+| Frontend | [framework + language + build tool] | ADR-[NNN] |
+| Backend | [framework + language + runtime] | ADR-[NNN] |
+| Database | [engine + version + hosting] | ADR-[NNN] |
+| Hosting / deployment | [cloud + region + container model] | ADR-[NNN] |
+| Auth / identity | [in-house / SSO / managed service] | ADR-[NNN] |
+| Observability | [logs + metrics + traces platform] | ADR-[NNN] |
+| Mandatory integrations | [list from §Integration Map] | — |
+
+---
+
+## NFR → ADR Traceability
+
+Forward traceability from each Non-functional Requirement in `06_nfr_[SLUG].md` to the ADR(s) that satisfy it. NFRs without a linked ADR are flagged — every Must-priority NFR should drive at least one architectural decision.
+
+| NFR ID | ISO 25010 Characteristic | Linked ADRs | Coverage Status |
+|--------|--------------------------|-------------|-----------------|
+| NFR-001 | Performance Efficiency | ADR-002, ADR-005 | ✓ |
+| NFR-003 | Reliability | ADR-004 | ✓ |
+| NFR-005 | Security | (uncovered) | ✗ |

package/skills/research/SKILL.md

@@ -10,6 +10,10 @@ Optional step between `/datadict` and `/apicontract`. Documents technology decis
 
 Running this step prevents "beautiful but impractical" API contracts by surfacing constraints early.
 
+**Standard alignment:** ADRs follow the **Michael Nygard format** (the de facto industry standard since 2011) extended with explicit Drivers, Alternatives Considered, and Decision Date fields.
+
+**Downstream consumers.** The output of `/research` is the **primary tech-stack source** for `/implement-plan` (added in v3.4.0). When `/research` is run, `/implement-plan` parses its ADRs and Integration Map to populate the Tech Stack header without asking the calibration interview. Make sure each tech-stack ADR (frontend, backend, database, hosting, auth, observability) has a clear winning decision so `/implement-plan` doesn't fall back to its own interview.
+
 ## Context loading
 
 0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions.
@@ -31,11 +35,19 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 **Required topics:**
 1. Existing infrastructure — is there a current backend, database, or API the new system must integrate with or extend?
-2. API style preference — REST, GraphQL, gRPC, or a combination? Any existing API gateway or BFF?
-3. Real-time requirements — do any user stories require live updates (WebSocket, SSE, polling)?
-4. Third-party integrations — which external services are confirmed (payment gateway, auth provider, analytics, CDN)?
-5. Data storage constraints — any vendor lock-in restrictions, cloud provider preferences, on-premise requirements?
-6. Compliance constraints — any restrictions on where data can be stored (jurisdiction, residency)?
+2. **Frontend stack** — framework, language, build tool? *(consumed by `/implement-plan` Tech Stack header)*
+3. **Backend stack** — framework, language, runtime? *(consumed by `/implement-plan`)*
+4. **Database** — engine, version, hosting model? *(consumed by `/implement-plan`)*
+5. **Hosting / deployment target** — which cloud, which region, container vs serverless? *(consumed by `/implement-plan`)*
+6. **Auth / identity** — in-house vs SSO vs managed service (Auth0, Clerk, Cognito)? *(consumed by `/implement-plan`)*
+7. **Observability platform** — logging, metrics, traces (Datadog, New Relic, Grafana, OpenTelemetry self-hosted)? *(consumed by `/implement-plan` Phase 8)*
+8. API style preference — REST, GraphQL, gRPC, or a combination? Any existing API gateway or BFF?
+9. Real-time requirements — do any user stories require live updates (WebSocket, SSE, polling)?
+10. Third-party integrations — which external services are confirmed (payment gateway, auth provider, analytics, CDN)?
+11. Data storage constraints — any vendor lock-in restrictions, cloud provider preferences, on-premise requirements?
+12. Compliance constraints — any restrictions on where data can be stored (jurisdiction, residency)?
+13. **Build vs buy** — for each major capability, is custom code worth it or is a vendor / open-source library sufficient?
+14. **Open-source vs proprietary tolerance** — any blanket policy (e.g. "no AGPL", "preferred Apache 2.0 / MIT", "vendor SLAs required")?
 
 Supplement with domain-specific typical integrations from the reference.
 
@@ -110,9 +122,10 @@ _(Repeat ADR block for each key decision.)_
 
 **Rules:**
 - ADR numbering: ADR-001, ADR-002, ...
-- Every ADR must include at least two options compared.
-- Decisions must reference FR or NFR that drove the choice.
+- Every ADR must include **Drivers** (FR / NFR / regulatory / cost / time-to-market — what forced the decision), **Alternatives Considered** (at least two), **Decision** (chosen option + rationale), and **Consequences** (positive and negative). This is the Nygard format extended.
+- Decisions must reference FR or NFR that drove the choice in the Drivers field.
 - Open Questions section is mandatory — even if empty (write "None").
+- The artifact carries an **NFR → ADR** traceability matrix at the bottom so a senior reviewer can verify which NFRs drove which architectural decisions.
 
 ## Iterative refinement