atdd 0.1.0__py3-none-any.whl

atdd/planner/conventions/wagon.convention.yaml

@@ -0,0 +1,275 @@
+version: "1.0"
+name: "Wagon Convention"
+description: "Semantic refinement patterns for converting ambiguous input to structured wagon definitions"
+
+# Wagon structure defined in schema
+structure:
+  $ref: "schemas:planner:wagon"
+
+# URN naming pattern
+urn_naming:
+  pattern: "wagon:{kebab-case-name}"
+  description: "Unique identifier for wagon using verb-object pattern"
+  utility: "utils.graph.URNBuilder.wagon(wagon_id)"
+
+  format:
+    pattern: "kebab-case (lowercase, alphanumeric with hyphens)"
+    preference: "verb-object (e.g., resolve-dilemmas, commit-state)"
+
+  examples:
+    - urn: "wagon:resolve-dilemmas"
+      name: "Resolve Dilemmas"
+      slug: "resolve-dilemmas"
+
+    - urn: "wagon:burn-timebank"
+      name: "Burn Timebank"
+      slug: "burn-timebank"
+
+    - urn: "wagon:manage-users"
+      name: "Manage Users"
+      slug: "manage-users"
+
+  validation:
+    pattern: "^wagon:[a-z][a-z0-9-]*$"
+    must_start_with: "lowercase letter"
+    allowed_chars: "lowercase letters, digits, hyphens"
+
+# Naming conventions (SPEC-COACH-UTILS-0281)
+naming:
+  slug_derivation:
+    pattern: "kebab-case from name"
+    preference: "verb-object pattern (e.g., resolve-dilemmas, commit-state)"
+    transformation: "lowercase, replace spaces/underscores with hyphens"
+
+  filesystem_naming:
+    description: "Filesystem uses snake_case, logical identifiers use kebab-case"
+    rules:
+      urns_and_slugs:
+        format: "kebab-case"
+        examples:
+          - "wagon:maintain-ux"
+          - "maintain-ux"
+          - "resolve-dilemmas"
+          - "feature:authenticate-identity:verify-session"
+        usage: "URNs, slug fields in YAML, references"
+
+      directories:
+        format: "snake_case"
+        pattern: "plan/{wagon_dirname}/"
+        examples:
+          - "plan/maintain_design/"
+          - "plan/resolve_dilemmas/"
+          - "plan/commit_state/"
+          - "plan/authenticate_identity/"
+        derivation: "slug.replace('-', '_')"
+
+      manifest_files:
+        format: "_{dirname}.yaml"
+        pattern: "plan/{dirname}/_{dirname}.yaml"
+        examples:
+          - "plan/maintain_design/_maintain_design.yaml"
+          - "plan/resolve_dilemmas/_resolve_dilemmas.yaml"
+          - "plan/authenticate_identity/_authenticate_identity.yaml"
+        note: "File name matches directory name, NOT slug"
+
+      feature_files:
+        format: "snake_case"
+        pattern: "plan/{wagon_dirname}/features/{feature_name}.yaml"
+        examples:
+          - "plan/authenticate_identity/features/verify_session.yaml"
+          - "plan/authenticate_identity/features/link_match_user.yaml"
+          - "plan/burn_timebank/features/track_remaining.yaml"
+          - "plan/setup_match/features/configure_match.yaml"
+        derivation: "feature_slug.replace('-', '_')"
+        note: "Feature file names use underscores, even though URNs use hyphens"
+
+    conversion:
+      slug_to_dirname: "slug.replace('-', '_')"
+      dirname_to_slug: "dirname.replace('_', '-')"
+      feature_slug_to_filename: "feature_slug.replace('-', '_') + '.yaml'"
+      feature_filename_to_slug: "filename.replace('_', '-').replace('.yaml', '')"
+
+    rationale: "Consistent filesystem naming reduces conversion complexity; clear separation between logical (kebab) and physical (snake) identifiers"
+
+    summary:
+      logical_identifiers: "kebab-case with hyphens (-) - used in URNs, slugs, YAML references"
+      filesystem: "snake_case with underscores (_) - used in directories, manifest files, feature files"
+      examples:
+        - logical: "feature:authenticate-identity:verify-session"
+          directory: "plan/authenticate_identity/"
+          manifest: "plan/authenticate_identity/_authenticate_identity.yaml"
+          feature_file: "plan/authenticate_identity/features/verify_session.yaml"
+
+# Refinement process for converting ambiguous input to structured wagon
+refinement:
+  # How to extract semantic fields from name + requirements
+  extraction:
+    subject:
+      prompt: "From '${inputs.requirements}', identify WHO or WHAT performs the main action (single actor, e.g., 'player:active', 'engine:orchestrator')"
+      pattern: "actor:role or entity:state format preferred"
+      images:
+        - ".claude/docs/examples/wagon-subjects-good.png"
+        - ".claude/docs/examples/wagon-subjects-bad.png"
+
+    action:
+      prompt: "Extract the core ACTION verb from '${inputs.requirements}' as present-tense phrase (e.g., 'applies the chosen option')"
+      pattern: "single present-tense verb phrase"
+      image: ".claude/docs/examples/action-verbs-reference.png"
+
+    goal:
+      prompt: "Identify the WHY/motivation behind this action from '${inputs.requirements}' (e.g., 'advance toward stable trajectory')"
+      pattern: "single intent statement"
+
+    context:
+      prompt: "Determine WHEN/WHERE this action occurs from '${inputs.requirements}' (e.g., 'in-match, timebank-active')"
+      pattern: "situational phrase, comma-separated conditions"
+
+    outcome:
+      prompt: "Define the measurable result from '${inputs.requirements}' (e.g., 'choice applied and state updated')"
+      pattern: "single measurable progress statement"
+
+    produce:
+      $ref: "conventions:planner:artifact#/naming_patterns/produce"
+
+    consume:
+      $ref: "conventions:planner:artifact#/naming_patterns/consume"
+
+    theme:
+      prompt: "Select most appropriate theme category for this wagon"
+      options:
+        mechanic: "Core game rules, decision systems, and immediate feedback loops"
+        scenario: "Content ingestion, entity extraction, and narrative structure processing"
+        match: "Session orchestration, state management, and lifecycle control, Multi-player coordination, turn management"
+        sensory: "UI rendering, audio mixing, gesture capture, and player interaction"
+        player: "Individual lifecycle, onboarding, progression, and session management"
+        league: "Competitive organization, bracket management, and tournament operations"
+        audience: "Spectator engagement, streaming infrastructure, and viewer participation"
+        monetization: "Token economy, wallet operations, and transaction processing"
+        partnership: "Sponsor/partner onboarding, delegation, and commercial integration"
+        commons: "Shared infrastructure, cross-cutting utilities, and platform services"
+
+    description:
+      template: "Generate concise one-liner from refined understanding of subject, action, goal, and context"
+      min_length: 10
+
+    wmbt:
+      default: {}
+      note: "Placeholder - WMBTs will be generated via handoff to wmbt.action"
+
+    total:
+      default: 0
+      note: "Placeholder - count will be updated when WMBTs are added via wmbt.action"
+
+# Validation rules for semantic coherence
+validation:
+  coherence_checks:
+    - "subject and action must align (subject can perform the action)"
+    - "action and goal must align (action serves the goal)"
+    - "outcome must be measurable result of action"
+    - "all produce artifacts must be owned by this wagon"
+    - "all consume artifacts must be owned by different wagons"
+    - "context must make sense for when/where action occurs"
+    - "at least one produce artifact must be external (scope: 'external')"
+
+# Artifact conventions (see artifact.convention.yaml for full details)
+artifact_contracts:
+  $ref: "conventions:planner:artifact#/artifact_contracts"
+  note: "Full artifact contract conventions defined in artifact.convention.yaml"
+
+  urn_format:
+    contract_urn: "contract:domain:resource (e.g., contract:ux:foundations, contract:match:result)"
+    telemetry_urn: "telemetry:domain:resource[.category] (e.g., telemetry:ux:foundations, telemetry:ux:foundations.colors)"
+
+    telemetry_filesystem:
+      description: "Telemetry URN maps to filesystem directory containing signal files"
+      pattern: "telemetry/{domain}/{resource}[/{category}]/{signal-type}.{plane}[.{measure}].json"
+      urn_to_path: "telemetry:{domain}:{resource}[.{category}] → telemetry/{domain}/{resource}[/{category}]/"
+
+      examples:
+        - urn: "telemetry:mechanic:decision.choice"
+          path: "telemetry/decision/choice/"
+          files:
+            - "metric.db.count.json"
+            - "metric.be.duration.json"
+            - "event.be.json"
+
+        - urn: "telemetry:ux:foundations"
+          path: "telemetry/ux/foundations/"
+          files:
+            - "metric.ui.render_latency.json"
+            - "event.ui.json"
+
+        - urn: "telemetry:ux:foundations.colors"
+          path: "telemetry/ux/foundations/colors/"
+          files:
+            - "metric.ui.render_latency.json"
+            - "event.ui.json"
+
+      signal_types:
+        metric: "Observability metrics (OpenTelemetry) - requires measure suffix"
+        event: "Analytics events (Segment/Mixpanel) - no measure suffix"
+
+      planes: ["ui", "ux", "be", "nw", "db", "st", "tm", "sc", "au", "fn", "if"]
+
+      measures:
+        metrics_only: ["count", "duration", "latency", "size", "rate", "percentage"]
+        not_for_events: "Events use pattern {signal-type}.{plane}.json (no measure)"
+
+      manifest_generation:
+        description: "Manifest generated from telemetry/ source files"
+        source: "telemetry/{domain}/{resource}/*.json"
+        output: "Generated manifest aggregates all signal definitions"
+
+  produce_artifacts:
+    required_fields:
+      - name: "Artifact name (e.g., ux:foundations)"
+      - contract: "Contract URN or null (e.g., contract:ux:foundations)"
+      - telemetry: "Telemetry URN for observability and analytics or null (e.g., telemetry:ux:foundations)"
+    optional_fields:
+      - to: "Visibility (internal|external), defaults to external"
+      - urn: "Legacy artifact URN"
+      - version: "Version string (e.g., v1)"
+
+    example:
+      - name: ux:foundations
+        contract: contract:ux:foundations
+        telemetry: telemetry:ux:foundations
+      - name: internal:cache
+        contract: null
+        telemetry: null
+        to: internal
+
+  consume_artifacts:
+    required_fields:
+      - name: "Artifact name (e.g., appendix:mockup)"
+    optional_fields:
+      - from: "Source (wagon:slug|system:service|appendix:type|internal)"
+      - contract: "Contract URN or null"
+      - telemetry: "Telemetry URN or null"
+      - urn: "Legacy artifact URN"
+      - version: "Version requirement"
+
+    example:
+      - name: appendix:mockup
+      - name: match:config
+        from: wagon:setup-match
+        contract: contract:match:config
+        telemetry: telemetry:match:config
+
+  features_format:
+    legacy_format:
+      type: "object"
+      example:
+        provide-foundations: "Provide foundation design tokens"
+        compose-primitives: "Compose UI primitives"
+
+    urn_format:
+      type: "array of URN objects"
+      example:
+        - urn: feature:maintain-ux:provide-foundations
+        - urn: feature:maintain-ux:compose-primitives
+      pattern: "feature:{wagon-slug}:{feature-name}"
+
+artifact_transformation:
+  $ref: "conventions:planner:artifact#/artifact_transformation"
+  note: "Full artifact transformation patterns defined in artifact.convention.yaml"

atdd/planner/conventions/wmbt.convention.yaml

@@ -0,0 +1,258 @@
+version: "1.0"
+name: "WMBT Convention"
+description: "Convention for What Must Be True (WMBT) decomposition"
+
+
+# WMBT structure defined in schema
+structure:
+  $ref: "schemas:planner:wmbt"
+
+# URN naming pattern
+urn_naming:
+  pattern: "wmbt:{wagon}:{STEP_CODE}{NNN}"
+  description: "Unique identifier for WMBT using step-coded sequence"
+  utility: "utils.graph.URNBuilder.wmbt(wagon_id, sequence)"
+
+  parts:
+    wagon: "Parent wagon identifier (kebab-case)"
+    STEP_CODE: "Single letter step code (D|L|P|C|E|M|Y|R|K)"
+    NNN: "Three-digit zero-padded sequence (001-999)"
+
+  step_codes:
+    D: "define - Define requirements, criteria, or constraints"
+    L: "locate - Locate, discover, or find resources"
+    P: "prepare - Prepare, setup, or configure prerequisites"
+    C: "confirm - Confirm, verify, or validate conditions"
+    E: "execute - Execute, perform, or run the main action"
+    M: "monitor - Monitor, observe, or track progress"
+    Y: "modify - Modify, update, or adjust state"
+    R: "resolve - Resolve, fix, or handle issues"
+    K: "conclude - Conclude, complete, or finalize"
+
+  examples:
+    - urn: "wmbt:resolve-dilemmas:E001"
+      wagon: "resolve-dilemmas"
+      step_code: "E"
+      step_name: "execute"
+      sequence: "001"
+
+    - urn: "wmbt:burn-timebank:M045"
+      wagon: "burn-timebank"
+      step_code: "M"
+      step_name: "monitor"
+      sequence: "045"
+
+    - urn: "wmbt:user-mgmt:C023"
+      wagon: "user-mgmt"
+      step_code: "C"
+      step_name: "confirm"
+      sequence: "023"
+
+  validation:
+    pattern: "^wmbt:[a-z][a-z0-9-]*:[DLPCEMYRK][0-9]{3}$"
+    step_codes: "Must be one of: D, L, P, C, E, M, Y, R, K"
+    sequence_range: "001-999"
+
+# External data sources
+steps:
+  $ref: "conventions:planner:steps:steps"
+
+dimension_instructions:
+  - "Analyze the user requirement to identify the core metric the user wants to optimize."
+  - "Use the 'keywords' to match the user's intent to one of the dimensions below."
+  - "Decompose the requirement into a structured format specifying the 'dimension', the 'actor' (e.g., employee, manager), the 'action' (e.g., minimize, increase, reduce), and the 'object' of the action."
+  - "Use the 'description' and 'rationale' to understand the purpose of each dimension."
+
+dimensions:
+  generator: &dimension_generator
+    prompt: "From '${inputs.description}', identify the primary dimension being worked on"
+    pattern: "single dimension keyword"
+    source: "conventions:planner:wmbt:dimensions.options"
+  options:
+    - name: "Time"
+      keywords: ["time", "duration", "fast", "slow", "quick", "speed", "delay", "wait", "rework", "onboard", "productive"]
+      description: "Measures the duration associated with executing a job or any of its steps. It encompasses speed, waiting, delays, and the time spent on rework and corrections. It's a measure of the job performer's most finite resource."
+      rationale: "Minimizing the time it takes to achieve a goal is a primary driver of value. Solutions that give the job performer their time back are highly valued, as that time can be reallocated to other tasks."
+      examples:
+        - "(Employee): Minimize the time it takes for a new employee to be fully onboarded and productive."
+        - "(Surgeon): Minimize the time it takes to complete a specific surgical procedure safely."
+
+    - name: "Effort"
+      keywords: ["effort", "physical", "mental", "cognitive", "easy", "intuitive", "concentration", "load", "force", "fatigue", "bug"]
+      description: "Measures the physical or cognitive load the job performer must endure to get a job done. Physical effort is muscular force; mental effort is the amount of concentration, learning, memory, and decision-making required."
+      rationale: "All actors are wired to conserve energy. Solutions that feel 'easy,' 'intuitive,' or 'effortless' are superior. High effort leads to frustration, errors, fatigue, and potential abandonment of the task."
+      examples:
+        - "(Nurse): Minimize the physical effort required to move a patient from a bed to a wheelchair."
+        - "(Software Developer): Reduce the mental effort required to find a specific bug in the code."
+
+    - name: "Likelihood"
+      keywords: ["likelihood", "probability", "chance", "risk", "error", "failure", "success", "predictability", "control", "reliability", "reject", "usable"]
+      description: "Measures the probability of a specific outcome occurring. It's used to articulate the desire for predictability, control, and success. It can be about increasing the probability of a desired outcome or decreasing the probability of an undesired one."
+      rationale: "Uncertainty creates stress, inefficiency, and risk. Increasing the likelihood of success and reducing the likelihood of errors builds trust and confidence."
+      examples:
+        - "(Scientist): Increase the likelihood that an experiment will produce a usable result."
+        - "(Citizen): Decrease the likelihood that a submitted application form will be rejected due to an error."
+
+    - name: "Frequency"
+      keywords: ["frequency", "often", "repetitive", "manual", "number of times", "switch", "resets"]
+      description: "Measures the rate of occurrence of an event or action within the execution of a job. It is most often used to reduce how often the job performer must perform an undesirable, repetitive, or non-value-added task."
+      rationale: "Repetitive tasks are a major source of frustration and wasted effort. Reducing the frequency of these annoyances frees the job performer to focus on what truly matters."
+      examples:
+        - "(System Admin): Reduce the frequency with which manual server resets are required."
+        - "(Call Center Agent): Minimize the number of times they have to switch between different software applications to resolve one issue."
+
+    - name: "Quantity / Amount"
+      keywords: ["quantity", "amount", "volume", "number", "resource", "consumed", "produced", "scrap", "leads", "spent"]
+      description: "Measures the volume, number, or amount of a resource that is either consumed or produced. It's about optimizing the tangible inputs and outputs of a job to improve efficiency."
+      rationale: "Every job performer operates with finite resources. Using fewer resources (inputs) translates directly into higher efficiency. Conversely, increasing the output from the same input is a universal measure of productivity."
+      examples:
+        - "(Factory Manager): Minimize the amount of scrap material generated per production run."
+        - "(Marketing Manager): Increase the number of qualified leads generated per dollar spent."
+
+    - name: "Financial Value"
+      keywords: ["financial", "value", "cost", "revenue", "money", "budget", "expense", "profit", "earnings", "currency", "fleet"]
+      description: "Measures the monetary impact of getting the job done from the job performer's perspective. It includes direct costs, operational expenses, opportunity costs, revenue lost, or revenue gained."
+      rationale: "Financial impact is a primary consideration in almost any organized system. A solution that helps an organization operate more profitably or a public institution to work more efficiently provides clear, quantifiable value."
+      examples:
+        - "(CFO): Minimize the financial impact of currency fluctuations on the company's earnings."
+        - "(Fleet Manager): Minimize the annual cost of maintaining the vehicle fleet."
+
+directions:
+  generator: &direction_generator
+    prompt: "From '${inputs.description}', pick the most suitable direction verb for the optimization goal"
+    pattern: "single action verb matching schema enum"
+    source: "conventions:planner:wmbt:directions.palette"
+  palette:
+    minimize: [reduce, decrease, lower, shrink]
+    maximize: [increase, boost, raise, grow]
+    increase: [improve, elevate, accelerate]
+    decrease: [cut, dampen, slow, limit]
+
+# Lenses for viewing the work
+lenses:
+  generator: &lens_generator
+    prompt: "From '${inputs.description}', determine the quality lens most relevant to this work"
+    pattern: "single quality attribute"
+    source: "conventions:planner:wmbt:lenses.catalog"
+  catalog:
+    social:
+      - id: belong
+        definition: "The drive to be accepted by a group and align with its norms—finding community and connection."
+        example: "Using the same communication tool as teammates to stay included in shared conversations."
+      - id: stand_out
+        definition: "The drive to differentiate oneself positively—signaling uniqueness, status, taste, or expertise."
+        example: "Choosing a distinctive design or advanced configuration to showcase personal style or mastery."
+      - id: affirm
+        definition: "The drive to reinforce an existing identity—expressing and validating a role one already holds."
+        example: "Selecting professional-grade tools consistent with one’s established expertise."
+      - id: aspire
+        definition: "The drive to become a better future self—signaling progress toward a desired identity."
+        example: "Enrolling in a skills program to move toward a new career path."
+
+    functional:
+      - id: efficiency
+        definition: "Minimizing time, effort, or resources required to complete a task."
+        example: "Completing a routine workflow in fewer steps or less time."
+      - id: effectiveness
+        definition: "Improving the quality, accuracy, or impact of outcomes."
+        example: "Raising the percentage of correct results produced by a process."
+      - id: availability
+        definition: "Ensuring a system or resource is accessible and operational when needed."
+        example: "Keeping a service reliably reachable during expected usage periods."
+      - id: adaptability
+        definition: "Enabling a process or system to handle new or changing requirements."
+        example: "Allowing users to add new data inputs without custom engineering work."
+      - id: sustainability
+        definition: "Maintaining performance over time without degradation or undue negative impact."
+        example: "Automating repetitive tasks to reduce manual effort and error over the long term."
+
+    emotional:
+      - id: joy
+        definition: "Pleasure or happiness when a product exceeds expectations or removes friction."
+        example: "Feeling satisfied when a task completes smoothly without extra effort."
+      - id: trust
+        definition: "Confidence that a product is reliable and safe, performing as promised."
+        example: "Feeling secure because progress is auto-saved and data is protected."
+      - id: fear
+        definition: "Anxiety about a potential negative outcome."
+        example: "Hesitating before confirming an irreversible action."
+      - id: surprise
+        definition: "A reaction to the unexpected—positive (delight) or negative (confusion)."
+        example: "Encountering a helpful hint unexpectedly—or an unexplained interface change."
+      - id: sadness
+        definition: "Unhappiness triggered by loss or a blocked goal."
+        example: "Feeling disappointed when informed a task cannot be completed right now."
+      - id: disgust
+        definition: "Aversion caused by unethical design, clutter, or offensive elements."
+        example: "Reacting negatively to an interface overloaded with intrusive prompts."
+      - id: anger
+        definition: "Frustration or hostility when things fail to work as expected."
+        example: "Feeling upset when a critical function fails at a key moment."
+      - id: anticipation
+        definition: "Hopeful expectation while awaiting a desired outcome."
+        example: "Watching a progress indicator while a process nears completion."
+
+object_of_control:
+  generator: &object_of_control_generator
+    prompt: "From '${inputs.description}' and '${inputs.step}', synthesize what specific thing is being controlled or manipulated"
+    pattern: "kebab-case noun phrase (e.g., 'user-profile', 'payment-flow')"
+
+context_clarifier:
+  generator: &context_clarifier_generator
+    prompt: "From '${inputs.description}', extract any contextual clarifier that specifies when/where/how this applies"
+    pattern: "detailed situational phrase, one line maximum"
+    required: true
+
+statement:
+  generator: &statement_generator
+    pattern: "${direction} ${dimension} of ${object_of_control}${context_clarifier ? ' ' + context_clarifier : ''}"
+
+generators:
+  direction: *direction_generator
+  dimension: *dimension_generator
+  lens: *lens_generator
+  object_of_control: *object_of_control_generator
+  context_clarifier: *context_clarifier_generator
+  statement: *statement_generator
+
+# Splitting rules for WMBT decomposition
+splitting_rules:
+  acceptance_cap:
+    maximum: 5
+    rationale: "Beyond 5 acceptances indicates mixed concerns that should be separate WMBTs"
+    enforcement: "schemas:planner:wmbt enforces via acceptance array maxItems"
+
+  when_to_split:
+    mixed_dimensions:
+      indicator: "Statement mentions multiple dimensions (e.g., 'fast AND reliable')"
+      action: "Create separate WMBTs: one for time dimension, one for likelihood"
+      example: "Split 'Minimize time while maximizing reliability' into two WMBTs"
+
+    multiple_actors:
+      indicator: "Different actors performing different actions"
+      action: "One WMBT per actor-action pair"
+      example: "Split 'Manager approves and employee submits' into separate WMBTs"
+
+    divergent_gates:
+      indicator: "Different acceptances need different gate modes (ALL vs ANY)"
+      action: "Group acceptances by gate requirements into separate WMBTs"
+
+  when_to_keep_together:
+    single_truth_multiple_layers:
+      indicator: "Same outcome verified at UI, API, and DB layers"
+      example: "Latency measured at presentation, application, integration"
+      gate_mode: "ALL - all layers must meet the requirement"
+
+    coherent_sequence:
+      indicator: "Sequential steps of a single process"
+      example: "Upload → Validate → Store → Confirm"
+      note: "Each acceptance tests one step, all must pass"
+
+  consistency_with_acceptances:
+    reference: "conventions:planner:acceptance:rules.acceptance_cap"
+    note: "This rule aligns with acceptance convention cap of ≤5 per WMBT"
+
+# Filename pattern (step-coded, no prefix)
+filename:
+- pattern: "{STEP_CODE}{NNN}.yaml"
+- examples: ["E001.yaml", "L045.yaml", "K023.yaml"]