universal-dev-standards 5.3.2 → 5.5.0

package/bundled/ai/standards/user-story-mapping.ai.yaml

@@ -0,0 +1,108 @@
+# User Story Mapping - AI Optimized
+# Source: XSPEC-069 Wave 4 Product Layer Pack
+
+id: user-story-mapping
+title: User Story Mapping Standards
+version: "1.0.0"
+status: Active
+tags: [product, user-story, story-map, mvp, agile, backlog]
+summary: |
+  Defines how teams construct and use story maps to plan product releases.
+  Covers the three-layer story map structure (Backbone activities, Walking
+  Skeleton sub-tasks, Detail Stories), the MVP horizontal slice rule that
+  ensures all backbone activities are covered minimally before deepening
+  any single activity, INVEST compliance per story, and Given/When/Then
+  acceptance criteria linked to measurable product metrics. Designed to
+  prevent incomplete MVPs and ensure every story is testable and traceable.
+
+requirements:
+  - id: REQ-001
+    title: Story Map Three Layers
+    description: |
+      Every story map MUST be structured in three horizontal layers:
+      (1) Backbone (top row) — user activities at the highest abstraction
+      level, representing the complete end-to-end user journey. Each backbone
+      item is a verb phrase from the user's perspective (e.g., "Find a product",
+      "Complete purchase", "Track order"). The backbone must represent the
+      full journey, not only implemented features.
+      (2) Walking Skeleton (middle row) — sub-tasks for each backbone activity,
+      representing the minimum steps required to make the backbone activity
+      functional. Organized vertically under each backbone item.
+      (3) Detail Stories (bottom rows) — specific user stories that implement
+      variations, enhancements, and edge cases for each walking skeleton step.
+      Prioritized vertically within each column (higher = higher priority).
+    level: MUST
+    examples:
+      - "Backbone: [Browse] → [Search] → [Add to Cart] → [Checkout] → [Track Order]"
+      - "Walking skeleton under [Checkout]: [Enter address] → [Select payment] → [Confirm order]"
+      - "Detail story under [Select payment]: 'As a buyer, I want to pay with saved card'"
+      - "Backbone covers full journey even if some activities are out of scope for v1"
+
+  - id: REQ-002
+    title: MVP Horizontal Slice Rule
+    description: |
+      The MVP release boundary MUST be defined as a horizontal slice across
+      the story map, covering all backbone activities at the walking skeleton
+      level. An MVP that covers only a subset of backbone activities (a
+      vertical slice that perfects one activity while others are absent or
+      non-functional) is PROHIBITED, as it creates a product experience that
+      cannot be evaluated end-to-end by users. Exception: single-activity
+      products (e.g., a focused utility app) are exempt if the product's
+      full value proposition is delivered by that one activity. Exceptions
+      MUST be documented with rationale in the story map.
+    level: MUST
+    examples:
+      - "Valid MVP: Browse(skeleton) + Search(skeleton) + Checkout(skeleton) — all activities covered"
+      - "Invalid MVP: Browse(full polish) + Search(full polish) — checkout absent, no end-to-end flow"
+      - "Exception documented: 'This MVP is a single-purpose QR code scanner; one activity is complete'"
+      - "Release planning: draw MVP line horizontally after walking skeleton row for all columns"
+
+  - id: REQ-003
+    title: Story INVEST Compliance
+    description: |
+      Every user story in the story map MUST comply with the INVEST criteria
+      as defined in requirement-engineering.ai.yaml: Independent (can be
+      developed and delivered without depending on unfinished stories),
+      Negotiable (details open for discussion; not a fixed contract),
+      Valuable (delivers value to user or business if shipped alone),
+      Estimable (team can size it; sufficient detail exists),
+      Small (fits within one sprint at most; split if larger),
+      Testable (acceptance criteria exist that can be objectively verified).
+      Stories that fail INVEST must be refined before entering a sprint.
+      INVEST assessment MUST be performed during backlog refinement sessions.
+    level: MUST
+    examples:
+      - "Story fails Independent: 'As a user I want to checkout' depends on 15 unfinished stories → split"
+      - "Story fails Small: estimated 13 story points → split into 3 smaller stories"
+      - "Story fails Testable: 'improve the UI' → rewrite with Given/When/Then AC"
+      - "Backlog refinement checklist includes INVEST review for each new story"
+
+  - id: REQ-004
+    title: Acceptance Criteria Format
+    description: |
+      Every user story MUST have at least one acceptance criterion written in
+      Given/When/Then (GWT) format. Acceptance criteria MUST be tied to a
+      measurable product outcome from the product-metrics-standards hierarchy
+      where applicable. Stories with acceptance criteria that cannot be
+      objectively verified (e.g., "the page looks good") are non-compliant.
+      Acceptance criteria MUST be written before development begins and MUST
+      not be modified after development starts without PM and dev lead
+      sign-off (same revision policy as PRD changes).
+    level: MUST
+    examples:
+      - "Given I have items in my cart / When I click 'Checkout' / Then I see the address form"
+      - "Given I enter an invalid card / When I submit / Then I see error 'Invalid card number'"
+      - "Metric tie: 'This story contributes to checkout completion rate (North Star driver)'"
+      - "Non-compliant AC: 'The checkout button should be prominent' — not objectively verifiable"
+
+anti_patterns:
+  - "Vertical MVP slicing: perfecting one user activity while other backbone activities are absent"
+  - "Stories without acceptance criteria entering development (no clear definition of done)"
+  - "Backbone activities not mapped to actual user goals (mapped to system components instead)"
+  - "Story map used only for planning and discarded; not kept as a living release planning tool"
+  - "Detail stories added directly without backbone and walking skeleton context"
+
+related_standards:
+  - prd-standards
+  - requirement-engineering
+  - product-metrics-standards

package/bundled/ai/standards/workflow-enforcement.ai.yaml

@@ -1,253 +1,47 @@
-# Workflow Enforcement Standards - AI Optimized
-# Source: core/workflow-enforcement.md
+# Workflow Enforcement Standards - DEPRECATED STUB
+# This file has been migrated to DevAP per DEC-049 (UDS/DevAP responsibility split).
+# Canonical location: dev-autopilot/standards/flow/workflow-enforcement.ai.yaml
+# Migration: XSPEC-086 Phase 2 (2026-04-27)
+#
+# Human-readable standard: core/workflow-enforcement.md (remains in UDS)
+# Deprecation schedule: UDS 5.4.0 deprecated → UDS 6.0.0 removed
 
 id: workflow-enforcement
 meta:
-  version: "1.0.0"
-  updated: "2026-03-19"
+  version: "1.0.1"
+  updated: "2026-04-27"
+  deprecated: true
+  deprecated_since: "5.4.0"
+  removal_version: "6.0.0"
+  canonical_owner: devap
+  canonical_path: "dev-autopilot/standards/flow/workflow-enforcement.ai.yaml"
   source: core/workflow-enforcement.md
-  description: Machine-enforceable workflow gates that prevent phase skipping in development methodologies
-
-enforcement_modes:
-  enforce:
-    description: Block phase transition, show guidance to correct phase
-    behavior: AI refuses to proceed and explains which prerequisite is missing
-    default: true
-
-  suggest:
-    description: Show warning but allow override with user confirmation
-    behavior: AI warns about skipped prerequisites but proceeds if user insists
-
-  off:
-    description: No enforcement checks
-    behavior: AI follows workflow steps without gate checks
-
-config_location: ".uds/config.yaml"
-config_key: "workflow.enforcement_mode"
-
-gates:
-  sdd:
-    description: Spec-Driven Development phase gates
-    phases:
-      - phase: discuss
-        prerequisites: []
-        note: Entry point, no prerequisites
-
-      - phase: create
-        prerequisites:
-          - check: orphan_specs
-            command: "ls docs/specs/SPEC-*.md 2>/dev/null"
-            condition: warn_if_non_terminal_specs_exist
-            on_fail: warn_and_offer_cleanup
-            blocking: false
-
-      - phase: review
-        prerequisites:
-          - check: spec_exists
-            command: "ls docs/specs/SPEC-*.md"
-            condition: at_least_one_spec_exists
-            on_fail: guide_to_create
-            blocking: true
-          - check: spec_status_draft
-            command: "grep -m1 '^status:' docs/specs/SPEC-XXX.md"
-            condition: status_is_draft
-            on_fail: guide_to_create
-            blocking: true
-
-      - phase: approve
-        prerequisites:
-          - check: spec_in_review
-            condition: status_is_review
-            on_fail: guide_to_review
-            blocking: true
-          - check: review_comments_addressed
-            condition: no_unresolved_comments
-            on_fail: guide_to_resolve_comments
-            blocking: true
-
-      - phase: implement
-        prerequisites:
-          - check: spec_exists
-            command: "ls docs/specs/SPEC-*.md"
-            condition: at_least_one_spec_exists
-            on_fail: guide_to_create
-            blocking: true
-          - check: spec_approved
-            condition: status_is_approved
-            on_fail: guide_to_approve
-            blocking: true
-          - check: workflow_state
-            command: "ls .workflow-state/sdd-*.yaml 2>/dev/null"
-            condition: check_for_resumable_state
-            on_fail: start_fresh
-            blocking: false
-
-      - phase: verify
-        prerequisites:
-          - check: implementation_exists
-            condition: spec_has_implementation_commits
-            on_fail: guide_to_implement
-            blocking: true
-          - check: ac_coverage
-            condition: all_ac_have_code_and_tests
-            on_fail: list_incomplete_acs
-            blocking: true
-
-  tdd:
-    description: Test-Driven Development phase gates
-    phases:
-      - phase: red
-        prerequisites:
-          - check: feature_defined
-            condition: user_has_described_behavior
-            on_fail: ask_for_behavior_description
-            blocking: true
-          - check: sdd_spec_if_applicable
-            condition: if_sdd_project_spec_exists_and_approved
-            on_fail: guide_to_sdd
-            blocking: false
-
-      - phase: green
-        prerequisites:
-          - check: failing_test_exists
-            command: "npm test 2>&1 | grep -E 'FAIL|failing'"
-            condition: at_least_one_test_failing
-            on_fail: guide_to_red_phase
-            blocking: true
-
-      - phase: refactor
-        prerequisites:
-          - check: all_tests_passing
-            command: "npm test"
-            condition: zero_test_failures
-            on_fail: guide_to_green_phase
-            blocking: true
-
-  bdd:
-    description: Behavior-Driven Development phase gates
-    phases:
-      - phase: discovery
-        prerequisites:
-          - check: behavior_identified
-            condition: user_has_identified_behavior
-            on_fail: ask_for_behavior
-            blocking: true
-
-      - phase: formulation
-        prerequisites:
-          - check: examples_collected
-            condition: discovery_produced_examples
-            on_fail: guide_to_discovery
-            blocking: true
-
-      - phase: automation
-        prerequisites:
-          - check: feature_file_exists
-            command: "ls tests/features/*.feature 2>/dev/null"
-            condition: at_least_one_feature_file
-            on_fail: guide_to_formulation
-            blocking: true
-          - check: gherkin_format
-            condition: scenarios_use_given_when_then
-            on_fail: fix_scenario_format
-            blocking: true
-
-      - phase: living_docs
-        prerequisites:
-          - check: steps_implemented
-            condition: step_definitions_exist
-            on_fail: guide_to_automation
-            blocking: true
-          - check: scenarios_passing
-            condition: all_scenarios_pass
-            on_fail: fix_failing_scenarios
-            blocking: true
-
-  commit:
-    description: Commit workflow gates
-    phases:
-      - phase: commit
-        prerequisites:
-          - check: staged_changes
-            command: "git diff --cached --stat"
-            condition: has_staged_changes
-            on_fail: guide_to_git_add
-            blocking: true
-          - check: no_merge_conflicts
-            condition: no_conflict_markers_in_staged
-            on_fail: resolve_conflicts
-            blocking: true
-          - check: tests_pass
-            condition: tests_passing_for_feat_fix
-            on_fail: fix_tests
-            blocking: true
-          - check: spec_reference
-            condition: feat_fix_should_reference_spec
-            on_fail: suggest_spec_reference
-            blocking: false
+  description: >
+    DEPRECATED: This standard has moved to DevAP (flow orchestration layer).
+    Install DevAP and load standards/flow/workflow-enforcement.ai.yaml instead.
 
 rules:
-  - id: enforce-phase-order
-    trigger: AI assistant receives a workflow phase command
+  - id: deprecation-notice
+    trigger: any workflow enforcement check
     instruction: >
-      Before executing any workflow phase (SDD, TDD, BDD), check the
-      phase gate prerequisites defined in this standard. If any blocking
-      prerequisite fails, STOP execution, explain what is missing, and
-      guide the user to the correct prerequisite phase. Non-blocking
-      prerequisites generate warnings but allow proceeding.
-    priority: required
+      This standard (workflow-enforcement.ai.yaml) has been migrated to DevAP.
+      For the canonical executable definition, load:
+        dev-autopilot/standards/flow/workflow-enforcement.ai.yaml
 
-  - id: respect-enforcement-mode
-    trigger: checking workflow gates
-    instruction: >
-      Read the project's enforcement mode from .uds/config.yaml
-      (workflow.enforcement_mode). If 'enforce' (default), block on
-      failed prerequisites. If 'suggest', warn but allow override.
-      If 'off', skip all checks.
-    priority: required
+      The human-readable standard remains at:
+        universal-dev-standards/core/workflow-enforcement.md
 
-  - id: guide-dont-block
-    trigger: prerequisite check fails
-    instruction: >
-      When a prerequisite fails, provide actionable guidance:
-      1. Explain WHAT is missing (e.g., "No approved spec found")
-      2. Explain WHY it matters (e.g., "SDD requires approved specs before implementation")
-      3. Show HOW to fix it (e.g., "Run /sdd approve SPEC-XXX.md first")
-      Never just say "blocked" — always provide the path forward.
+      To install DevAP: npm install -g @devap/cli
+      See: https://github.com/AsiaOstrich/dev-autopilot
     priority: required
 
-  - id: resume-existing-workflow
-    trigger: workflow command invoked with existing state
-    instruction: >
-      Before starting a fresh workflow, check .workflow-state/ for
-      existing state files. If an active workflow exists for the same
-      spec or feature, offer to resume instead of starting fresh.
-    priority: required
-
-  - id: feat-commit-spec-suggestion
-    trigger: committing a feat or fix type change
+  - id: enforce-phase-order
+    trigger: AI assistant receives a workflow phase command
     instruction: >
-      When generating a feat or fix commit message, check if active
-      specs exist in docs/specs/. If yes, suggest adding Refs: SPEC-XXX
-      to the commit footer. If no specs exist and the change is
-      significant (>3 files changed or new API), suggest creating a
-      spec via /sdd. This is advisory, not blocking.
-    priority: recommended
-
-quick_reference:
-  enforcement_modes:
-    columns: [Mode, Behavior, Config Value]
-    rows:
-      - [Enforce, "Block + Guide", "enforce"]
-      - [Suggest, "Warn + Allow", "suggest"]
-      - [Off, "No checks", "off"]
+      DEPRECATED — load dev-autopilot/standards/flow/workflow-enforcement.ai.yaml
+      for the current executable gate definitions.
 
-  phase_gates:
-    columns: [Workflow, Phase, Key Prerequisite]
-    rows:
-      - [SDD, implement, "Spec must be Approved"]
-      - [SDD, verify, "All ACs must have code + tests"]
-      - [TDD, green, "At least one failing test"]
-      - [TDD, refactor, "All tests passing"]
-      - [BDD, automation, ".feature file must exist"]
-      - [Commit, feat/fix, "Suggest spec reference"]
+      Minimal fallback: Before executing any workflow phase, check that
+      prerequisites for the phase are met. If not, stop and guide the user
+      to the correct prerequisite phase.
+    priority: required

package/bundled/ai/standards/workflow-state-protocol.ai.yaml

@@ -1,121 +1,45 @@
-# Workflow State Protocol - AI Optimized
-# Source: core/workflow-state-protocol.md
+# Workflow State Protocol - DEPRECATED STUB
+# This file has been migrated to DevAP per DEC-049 (UDS/DevAP responsibility split).
+# Canonical location: dev-autopilot/standards/flow/workflow-state-protocol.ai.yaml
+# Migration: XSPEC-086 Phase 2 (2026-04-27)
+#
+# Human-readable standard: core/workflow-state-protocol.md (remains in UDS)
+# Deprecation schedule: UDS 5.4.0 deprecated → UDS 6.0.0 removed
 
 id: workflow-state-protocol
 meta:
-  version: "1.0.0"
-  updated: "2026-03-17"
+  version: "1.0.1"
+  updated: "2026-04-27"
+  deprecated: true
+  deprecated_since: "5.4.0"
+  removal_version: "6.0.0"
+  canonical_owner: devap
+  canonical_path: "dev-autopilot/standards/flow/workflow-state-protocol.ai.yaml"
   source: core/workflow-state-protocol.md
-  description: Protocol for persisting and restoring workflow state across AI sessions
-
-principles:
-  state_persistence:
-    rule: Multi-phase workflows must save state at phase transitions
-    rationale: Enables resumption after session boundaries without state loss
-
-  event_sourcing:
-    rule: Important decisions and transitions are logged in append-only event log
-    rationale: Provides audit trail and enables understanding of workflow history
-
-  session_independence:
-    rule: Each AI session should be able to resume any workflow from saved state
-    rationale: Context window limits make single-session completion unreliable
-
-state_file:
-  location: ".workflow-state/{workflow}-{id}.yaml"
-  required_fields:
-    - workflow      # Workflow type (sdd, feature-dev, etc.)
-    - spec_id       # Spec or task identifier
-    - current_phase # Active phase ID
-    - status        # in-progress | paused | blocked | completed | abandoned
-    - updated       # Last update timestamp (ISO 8601)
-    - phases_completed  # Ordered list of completed phase IDs
-  optional_fields:
-    - title
-    - iteration_count
-    - created
-    - artifacts
-    - progress_summary
-    - completed_steps
-    - next_steps
-    - open_questions
-    - decisions
-
-event_log:
-  location: ".workflow-state/{workflow}-{id}.log.yaml"
-  format: append-only YAML list
-  event_types:
-    - phase_enter    # Workflow enters a new phase
-    - phase_exit     # Workflow exits a phase
-    - checkpoint     # Notable milestone
-    - decision       # Important decision made
-    - error          # Error or failure
-    - interruption   # Workflow paused (HITL or context limit)
-    - resumption     # Workflow resumed from saved state
-  required_event_fields:
-    - timestamp
-    - event_type
-    - phase
-    - summary
+  description: >
+    DEPRECATED: This standard has moved to DevAP (flow orchestration layer).
+    Install DevAP and load standards/flow/workflow-state-protocol.ai.yaml instead.
 
 rules:
-  - id: state-save-on-phase-transition
-    trigger: workflow phase changes
+  - id: deprecation-notice
+    trigger: any workflow state operation
     instruction: >
-      When a workflow transitions between phases, update the state file
-      with new current_phase, add the completed phase to phases_completed,
-      and update the timestamp. Also append a phase_exit and phase_enter
-      event to the event log.
+      This standard (workflow-state-protocol.ai.yaml) has been migrated to DevAP.
+      For the canonical executable definition, load:
+        dev-autopilot/standards/flow/workflow-state-protocol.ai.yaml
+
+      The human-readable standard remains at:
+        universal-dev-standards/core/workflow-state-protocol.md
+
+      To install DevAP: npm install -g @devap/cli
     priority: required
 
   - id: state-load-on-resume
     trigger: session start or workflow command invocation
     instruction: >
-      At session start, check .workflow-state/ for any files with
-      status 'in-progress' or 'paused'. If found, inform the user
-      of active workflows and offer to resume. When a workflow command
-      is invoked (e.g., /sdd implement SPEC-042), check for existing
-      state before starting fresh.
-    priority: required
+      DEPRECATED — load dev-autopilot/standards/flow/workflow-state-protocol.ai.yaml
+      for the current executable state protocol.
 
-  - id: state-save-on-session-end
-    trigger: AI session ending with active workflow
-    instruction: >
-      Before ending a session during an active workflow, save current
-      progress to the state file. Update progress_summary, next_steps,
-      and open_questions to enable seamless resumption.
+      Minimal fallback: At session start, check .workflow-state/ for active workflows
+      and offer to resume if found.
     priority: required
-
-  - id: event-log-on-decision
-    trigger: important design or scope decision made
-    instruction: >
-      When a significant decision is made during a workflow (design choice,
-      scope change, technology selection), append a 'decision' event to the
-      event log with the decision summary and reasoning.
-    priority: recommended
-
-  - id: state-staleness-warning
-    trigger: loading state file older than 7 days
-    instruction: >
-      If a state file's 'updated' timestamp is more than 7 days old,
-      warn the user that the workflow state may be stale and suggest
-      reviewing it before continuing.
-    priority: recommended
-
-  - id: gitignore-workflow-state
-    trigger: creating .workflow-state/ directory
-    instruction: >
-      Recommend adding .workflow-state/ to .gitignore as workflow state
-      is session-specific. Exception: teams sharing state across developers
-      may version-control it but should clean up completed workflows.
-    priority: recommended
-
-quick_reference:
-  state_lifecycle:
-    columns: [Event, Action]
-    rows:
-      - [Phase transition, Update state file + append event log]
-      - [Important decision, Record in state decisions + event log]
-      - [Session ending, Save progress_summary and next_steps]
-      - [Session starting, Check .workflow-state/ for active workflows]
-      - [Workflow complete, Set status to completed]