feat(skills): add discovery rigor and workflow contract support

.gitignore

@@ -26,6 +26,9 @@ design-artifacts/
 __pycache__/
 .pytest_cache/
 
+# Local history
+.history/
+
 # System files
 .DS_Store
 Thumbs.db

.markdownlint-cli2.yaml

@@ -12,6 +12,7 @@ ignores:
   - .roo/**
   - .codex/**
   - .kiro/**
+  - .history/**
   - sample-project/**
   - test-project-install/**
   - z*/**

eslint.config.mjs

@@ -39,6 +39,7 @@ export default [
       // are dictated by Augment and can't be changed, so exclude
       // the entire directory from linting
       '.augment/**',
+      '.history/**',
     ],
   },
 

src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md

@@ -144,6 +144,8 @@ For each story in the epic:
 1. **Story Title**: Clear, action-oriented
 2. **User Story**: Complete the As a/I want/So that format
 3. **Acceptance Criteria**: Write specific, testable criteria
+4. **Exit Criteria**: What must be true for this story to be considered done — stated as verifiable assertions, not aspirations
+5. **Rollback Boundary**: If this story fails after merge, what is the safe rollback point? (e.g., "revert to pre-story state — no schema migrations" or "feature flag off — no data loss")
 
 **AC Writing Guidelines:**
 

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: bmad-create-workflow-contract
+description: "Defines workflow and operator contracts. Use when the user says 'create a workflow contract', 'define the operator contract', or 'formalize the workflow interface'."
+---
+
+# Workflow Contract
+
+## Overview
+
+This skill helps you formalize boundaries between systems, repos, or workflow stages through a canonical contract document. It works by surfacing contract boundaries, defining each approved surface with inline compliance questions, and checking the finished contract for cross-surface consistency. Your output is a frozen workflow contract that downstream teams and skills can treat as the authoritative interface.
+
+Follow the instructions in [workflow.md](workflow.md).
+
+## Your Approach
+
+- Make every boundary explicit enough that a new operator or repo owner can follow it without tribal knowledge.
+- Keep producer, consumer, and owner responsibilities visible at each surface.
+- Write compliance questions that can be answered with evidence, not opinion.
+- Freeze approved contract sections unless the user explicitly reopens them.
+
+## Deliverable
+
+The output document (`{planning_artifacts}/workflow-contract.md`) should leave downstream work with:
+
+- **Systems in Scope** — systems, repos, or stages with roles and owners
+- **Per-Surface Contracts** — sections driven by `./resources/contract-surface-types.csv`
+- **Compliance Questions** — inline, evidence-ready checks for each confirmed contract
+- **Boundaries and Constraints** — Always / Ask First / Never rules for operators and maintainers
+
+## Recovery
+
+If conversation context is compressed, re-read this file and [workflow.md](workflow.md). The output document frontmatter (`stepsCompleted`, `lastStep`, `mode`) is the recovery source.
+
+## On Activation
+
+- Load config and the contract surface taxonomy.
+- Discover candidate input documents, then confirm scope before loading them in full.
+- Begin with [workflow.md](workflow.md), then route into `./steps/step-01-init.md`.

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/resources/contract-surface-types.csv

@@ -0,0 +1,7 @@
+surface_type,what_to_define,table_columns,when_applicable,definition_order
+identity,"How entities are named across boundaries — IDs, aliases, canonical names, paths, manifests","Entity | Canonical Name | Aliases | Resolution Rule | Collision Rule",always,1
+ownership,"Who produces, who consumes, and who owns each concern — including dispute resolution","Concern | Producer | Consumer(s) | Owner | Handoff Point",always,2
+operator,"Commands, config paths, state transitions, proof mode, and rollback procedures","Action | Command | Config Path | Inputs | Outputs | Idempotent?",always,3
+evidence,"What proves correctness, where evidence lands, and how review consumes it","Checkpoint | Evidence Artifact | Location | Format | Reviewer",always,4
+compatibility,"Backward compatibility rules, versioning, drift detection, and breaking change process","N/A — use prose fields: Versioning scheme, Backward compat rule, Drift detection, Breaking change process",when_multiple_versions,5
+migration,"Transitional period, aliases, removal signals, cleanup procedures","N/A — use prose fields: Transitional period, Transitional aliases, Removal signal, Cleanup",when_migrating,6

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/steps/step-01-init.md

@@ -0,0 +1,75 @@
+# Step 1: Initialization
+
+Establish whether this contract is grounded in enough upstream context, identify the systems and boundaries in scope, and choose the approval cadence that fits the number of surfaces to define.
+
+## Recovery
+
+If `{outputFile}` exists, recover per workflow.md §RECOVERY PROTOCOL.
+
+## Gather Inputs
+
+Search in `{planning_artifacts}/**`, `{output_folder}/**`, and `{project_knowledge}/**` when that path is configured:
+
+| Document Type | Glob Pattern | Priority |
+|--------------|-------------|----------|
+| Discovery Context | `*discovery-context*.md` | Primary — may already contain Contract Candidates |
+| Architecture | `*architecture*.md` | High — system boundaries and technical decisions |
+| PRD | `*prd*.md` | Medium — requirements and constraints |
+| Technical Design | `*tech-spec*.md`, `*technical-design*.md` | Medium — implementation details and tradeoffs |
+| Epics / Stories | `*epic*.md`, `*stor*.md` | Low — implementation slices |
+
+Before loading document contents, present the discovered candidates and use `vscode_askQuestions` to confirm which documents are in scope. In autonomous mode, self-serve the scope selection from workspace evidence and log it.
+
+For sharded folders, load `index.md` first and then the relevant shards from the selected documents.
+
+Use these loading rules:
+
+- Load every discovered file the user confirms is in scope.
+- Treat Discovery Context as the strongest seed source; check it for a **Contract Candidates** section.
+- Track loaded files in frontmatter `inputDocuments`.
+
+Minimum input check:
+
+| Condition | Action |
+|-----------|--------|
+| At least one of Discovery Context, Architecture, or Technical Design loaded and confirmed in scope | Proceed |
+| None found | Halt: `A Workflow Contract needs upstream context. Please run bmad-discovery-rigor, bmad-create-architecture, or provide a technical design first.` |
+
+From the loaded documents, extract:
+
+- **Contract Candidates** from Discovery Context when present
+- **Systems, repos, or services** named across the source material
+- **Boundaries** between components or stages
+- **Identity schemes** such as IDs, aliases, paths, or manifest names
+
+Build a preliminary systems map:
+
+| System / Repo | Role (Producer / Consumer / Both) | Repo / Location | Owner |
+|--------------|-----------------------------------|-----------------|-------|
+
+## Select Mode and Initialize Output
+
+Load `../resources/contract-surface-types.csv` and count how many contract surfaces need definition based on the seeded candidates, systems, and boundaries.
+
+| Surface count | Mode | Behavior |
+|--------------|------|----------|
+| ≤ 3 | Lightweight | Single halt gate per step; compact presentation |
+| > 3 | Full | Per-surface halt gates; batch presentation |
+
+Copy `../workflow-contract-template.md` to `{outputFile}` and update frontmatter:
+
+- Replace `{{project_name}}`, `{{user_name}}`, and `{{date}}` placeholders in the copied template before writing it.
+- Render the document title with the resolved project name so the initialized file contains no leftover template placeholders.
+- Write the preliminary systems map into the `## Systems in Scope` table immediately so recovery and later verification use saved state rather than reconstructed notes.
+
+```yaml
+stepsCompleted: [1]
+inputDocuments: [list of loaded files]
+mode: '[lightweight or full]'
+surfaceCount: [count]
+lastStep: 'step-01-init'
+```
+
+Present the documents loaded, contract candidates seeded, systems identified, and selected mode with surface count.
+
+**🛑 HALT — Use `vscode_askQuestions` to confirm the selected scope and mode before proceeding. In autonomous mode, self-serve and log the decision.**

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/steps/step-02-define.md

@@ -0,0 +1,112 @@
+# Step 2: Contract Surface Discovery and Definition
+
+Turn the systems map into explicit contract surfaces, let the user triage which ones belong in this document, then define each included surface with evidence-ready compliance questions. Mark each confirmed section frozen with `<!-- frozen-after-approval -->`.
+
+## Recovery
+
+Recover per workflow.md §RECOVERY PROTOCOL. If context was compressed, announce the recovered state before proceeding.
+
+## Enumerate and Triage Surfaces
+
+Load `../resources/contract-surface-types.csv`. For each system boundary from step 1, probe each surface type with this taxonomy:
+
+| Surface Type | Probe Question |
+|-------------|---------------|
+| identity | How are entities named across this boundary? Stable IDs or context-dependent? |
+| ownership | Who produces, consumes, and owns each artifact or config? |
+| operator | What commands does an operator run? Which configs and state transitions matter? |
+| evidence | What proves correctness, and where does that evidence land? |
+| compatibility | What backward-compatibility rules apply? Versioning? Drift detection? |
+| migration | Is there a transition period, and do old and new systems coexist? |
+
+Apply `when_applicable` from the CSV with this filter:
+
+| when_applicable value | Include? |
+|----------------------|----------|
+| always | Yes — probe for every boundary |
+| when_multiple_versions | Only if versioning or parallel versions exist |
+| when_migrating | Only if a migration is in progress or planned |
+
+Zero-surface guard:
+
+| Surfaces found | Action |
+|----------------|--------|
+| 0 | Halt: `No contract surfaces were discovered from the input documents. This usually means either the systems in scope do not have cross-boundary contracts to define, or the source material does not describe boundaries clearly enough. Consider invoking bmad-discovery-rigor before returning here.` |
+| ≥ 1 | Proceed to presentation |
+
+Present discovered surfaces in a table:
+
+| # | Boundary | Surface Type | Source | Status |
+|---|----------|-------------|--------|--------|
+| 1 | [system → system] | [type] | Seeded / New | [pending] |
+
+Ask the user to triage each surface as:
+
+- **Include** — define it formally in this contract
+- **Defer** — acknowledge it but leave it out of this document
+- **N/A** — the boundary or surface does not actually apply
+
+**🛑 HALT — Use `vscode_askQuestions` to collect Include / Defer / N/A decisions. In autonomous mode, self-serve from workspace evidence and log the triage.**
+
+## Draft and Confirm Contracts
+
+Work through included surfaces in the CSV `definition_order` (identity → ownership → operator → evidence → compatibility → migration).
+
+For each included surface:
+
+- Draft the contract using the CSV `table_columns`
+- Add 2-3 inline compliance questions that can be answered with evidence and cover the happy path plus at least one edge case
+- Make those compliance questions specific to the actual contract content, not generic templates
+- Highlight any places where the input documents were silent or contradictory
+- Present the draft for confirmation
+
+Mode-dependent presentation:
+
+| Mode | Presentation |
+|------|-------------|
+| Lightweight (≤3 surfaces) | Present all drafted contracts at once, then single halt |
+| Full (>3 surfaces) | Present one contract at a time, halt after each |
+
+**🛑 HALT — Use `vscode_askQuestions` for contract confirmation per the mode rules above. In autonomous mode, self-serve from workspace evidence and log the result.**
+
+On confirmation, mark the section frozen with `<!-- frozen-after-approval -->`.
+
+## Verify Consistency and Update Document
+
+After all contracts are defined, verify consistency across them:
+
+| Check | What to verify |
+|-------|---------------|
+| Identity ↔ Operator | Do operator commands use the canonical names from Identity? |
+| Ownership ↔ Operator | Does the owning entity also run or authorize the operator commands it owns? |
+| Operator ↔ Evidence | Do operator outputs land where Evidence expects to find them? |
+| Evidence ↔ Compatibility | Does drift detection inspect the locations where evidence is produced? |
+
+If inconsistencies appear, present them and ask the user to resolve them with `vscode_askQuestions` before continuing. In autonomous mode, self-serve the most defensible resolution from workspace evidence and log it.
+
+Write all confirmed contract sections and their inline compliance questions to `{outputFile}`.
+
+Populate the **Boundaries and Constraints** table:
+
+| Category | Rule |
+|----------|------|
+| Always | [rules that must always hold — from confirmed contracts] |
+| Ask First | [rules that need human judgment case by case] |
+| Never | [hard prohibitions — from contracts and constraints] |
+
+Update frontmatter:
+
+```yaml
+stepsCompleted: [1, 2]
+lastStep: 'step-02-define'
+```
+
+Present:
+
+```markdown
+**All contracts defined.** {N} contract sections frozen with {M} compliance questions.
+
+[C] Continue to finalization
+```
+
+**🛑 HALT — Use `vscode_askQuestions` to confirm continuation into finalization. In autonomous mode, self-serve and log the decision.**

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/steps/step-03-finalize.md

@@ -0,0 +1,57 @@
+# Step 3: Finalization and Handoff
+
+Verify that the contract is complete enough to trust, run any final challenge pass that adds value, then save the contract and recommend the next workflow.
+
+## Recovery
+
+Check `{outputFile}` frontmatter per workflow.md step sequence. If context was compressed, recover and announce the recovered state.
+
+## Verify the Contract
+
+Verify each item against `{outputFile}`:
+
+| # | Check | How to verify |
+|---|-------|--------------|
+| 1 | Systems in Scope populated | At least one system row with role and owner |
+| 2 | At least one contract section defined | Non-empty contract content exists |
+| 3 | Each contract section has frozen marker | `<!-- frozen-after-approval -->` present |
+| 4 | Inline compliance questions present | Each contract has at least one compliance question |
+| 5 | Boundaries and Constraints populated | At least one row in each category |
+| 6 | No placeholder text remaining | No `[TODO]`, `[TBD]`, or `{{...}}` anywhere in the document, including frontmatter and title |
+| 7 | Cross-contract consistency verified | Step 2 consistency check was completed |
+
+If any check fails, state which one failed, explain why, and ask how to proceed.
+
+**🛑 HALT if any check fails — use `vscode_askQuestions` to resolve or explicitly defer the failure before finalizing. In autonomous mode, self-serve and log the decision.**
+
+## Optional Adversarial Review
+
+If `bmad-review-adversarial-general` is available, invoke it against the compiled contract to look for unstated assumptions, missing boundaries, ambiguous ownership, or unverifiable claims.
+
+If findings are returned, present them to the user, use `vscode_askQuestions` to resolve or explicitly defer them, and do not proceed to save until that gate is complete. In autonomous mode, self-serve the most defensible resolution from workspace evidence and log it.
+
+Skip this pass if the skill is not installed or the contract is straightforward.
+
+## Save and Recommend Next Steps
+
+Update `{outputFile}` frontmatter:
+
+```yaml
+stepsCompleted: [1, 2, 3]
+status: 'complete'
+completedDate: '{date}'
+lastStep: 'step-03-finalize'
+```
+
+Recommend the next workflow based on contract content:
+
+| Contract content signals | Recommended skill | Reason |
+|-------------------------|-------------------|--------|
+| Implementation slices in input docs | `bmad-sprint-planning` | Plan implementation of the contract |
+| Architecture decisions still needed | `bmad-create-architecture` | Design the system that fulfills the contract |
+| Story creation still needed | `bmad-create-epics-and-stories` | Break the contract into implementation stories |
+| Came directly from discovery | Note the discovery lineage | Contract is now ready for the next phase |
+
+Present a completion summary with systems in scope, contracts defined, compliance question count, boundary rules, saved location, and recommended next step. Note that downstream skills should load this contract as reference.
+
+**🛑 Workflow contract workflow complete.**

src/bmm-skills/3-solutioning/bmad-create-workflow-contract/workflow-contract-template.md

@@ -0,0 +1,32 @@
+---
+stepsCompleted: []
+inputDocuments: []
+mode: ''
+surfaceCount: 0
+workflowType: 'workflow-contract'
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+lastStep: ''
+---
+
+# Workflow Contract — {{project_name}}
+
+_Canonical contract surfaces for cross-system or cross-repo workflow integration. Built collaboratively through step-by-step discovery. Contract types driven by `contract-surface-types.csv`._
+
+## Systems in Scope
+
+| System | Role (Producer / Consumer / Both) | Repo / Location | Owner |
+|--------|-----------------------------------|-----------------|-------|
+
+## Contracts
+
+_Each contract section includes its compliance questions inline._
+
+## Boundaries and Constraints
+
+| Category | Rule |
+|----------|------|
+| Always | |
+| Ask First | |
+| Never | |