From 423360e72c48ba13d5db0949eff6b94c9dfbb33b Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 18 May 2026 10:31:24 -0400 Subject: [PATCH 1/2] =?UTF-8?q?release:=20bump=20version=209.0.0=20?= =?UTF-8?q?=E2=86=92=209.0.1=20(derive=20delivery=20order=20from=20context?= =?UTF-8?q?=20map)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .flowr/flows/develop-flow.yaml | 2 +- .flowr/flows/discovery-flow.yaml | 1 - .../requirements/feature-boundaries.md | 20 +- .../requirements/feature-discovery.md | 7 +- .opencode/skills/create-domain-spec/SKILL.md | 4 +- .opencode/skills/refine-features/SKILL.md | 7 +- .opencode/skills/select-feature/SKILL.md | 39 +- .../features/.feature.template | 2 +- .../.md.template} | 0 .templates/docs/spec/domain_spec.md.template | 12 - .templates/docs/spec/glossary.md.template | 75 +--- .../docs/spec/product_definition.md.template | 14 - CHANGELOG.md | 2 +- docs/audit/document-landscape-audit.md | 6 +- .../CONTRACT_spec_simulation_redesign.md | 376 ------------------ pyproject.toml | 2 +- 16 files changed, 53 insertions(+), 516 deletions(-) rename .templates/docs/research/{TEMPLATE.md.template => //.md.template} (100%) delete mode 100644 docs/research/CONTRACT_spec_simulation_redesign.md diff --git a/.flowr/flows/develop-flow.yaml b/.flowr/flows/develop-flow.yaml index 8b30a9ec..03d51c89 100644 --- a/.flowr/flows/develop-flow.yaml +++ b/.flowr/flows/develop-flow.yaml @@ -9,7 +9,7 @@ exits: states: - id: feature-selection attrs: - description: "PO selects the next feature — by delivery order for first feature, by WSJF for subsequent features" + description: "PO selects the next feature — by dependency count then WSJF" owner: PO git: dev skills: diff --git a/.flowr/flows/discovery-flow.yaml b/.flowr/flows/discovery-flow.yaml index 50740f85..93660855 100644 --- a/.flowr/flows/discovery-flow.yaml +++ b/.flowr/flows/discovery-flow.yaml @@ -41,7 +41,6 @@ states: - why - users - out_of_scope - - delivery_order - quality_attributes - domain_spec.md: - context_map diff --git a/.opencode/knowledge/requirements/feature-boundaries.md b/.opencode/knowledge/requirements/feature-boundaries.md index db0c62a9..fca599b9 100644 --- a/.opencode/knowledge/requirements/feature-boundaries.md +++ b/.opencode/knowledge/requirements/feature-boundaries.md @@ -1,6 +1,6 @@ --- domain: requirements -tags: [feature-boundaries, story-mapping, delivery-order, bounded-contexts, feature-naming] +tags: [feature-boundaries, bounded-contexts, feature-naming] last-updated: 2026-05-08 --- @@ -8,21 +8,21 @@ last-updated: 2026-05-08 ## Key Takeaways -- Feature boundaries are derived from simulation-created .feature files, validated against the delivery order in product_definition.md, the context map, and aggregate boundaries from the domain spec. Each .feature file from simulation is a feature candidate; candidates may be split, renamed, or merged. -- A feature should belong to primarily one bounded context. If a delivery step spans two or more contexts, split it along context boundaries. +- Feature boundaries are derived from simulation-created .feature files, validated against the context map and aggregate boundaries from the domain spec. Each .feature file from simulation is a feature candidate; candidates may be split, renamed, or merged. +- A feature should belong to primarily one bounded context. If a feature spans two or more contexts, split it along context boundaries. - A feature should not span multiple aggregate transactional consistency boundaries. If it does, split along aggregate lines. -- Feature names follow the `[Capability]` pattern from the delivery step. Descriptions answer: what it provides, which context it serves, why it exists, and key entities. +- Feature names follow the `[Capability]` pattern. Descriptions answer: what it provides, which context it serves, why it exists, and key entities. - Cross-cutting concerns (risk management, error handling, observability) are not separate features — they appear as Constraints in the features that implement them. ## Concepts -**Delivery Order as Backbone**: Patton (2014) recommends mapping the user's narrative flow as a backbone, then slicing vertically into releasable increments. The .feature files created during simulation capture the discovered behavior — the delivery order in product_definition.md validates the dependency graph. .feature files are refined into independently deliverable features that follow the validated delivery order. +**Context Map as Backbone**: Patton (2014) recommends mapping the user's narrative flow as a backbone, then slicing vertically into releasable increments. The .feature files created during simulation capture the discovered behavior — the context map from domain_spec.md validates the dependency graph. .feature files are refined into independently deliverable features whose delivery order is derived at selection time via dependency count and WSJF. **Context Alignment Validation**: Each feature candidate must be checked against the domain spec's bounded context table. A feature that touches entities from two or more contexts has a boundary problem. Split it: each context gets its own feature. The domain spec's "Why Separate" column explains why the contexts were split — the feature split must respect the same reasoning. -**Aggregate Boundary Validation**: Aggregates define transactional consistency boundaries. A feature that modifies data across two aggregates in one transaction violates aggregate design. If a delivery step spans multiple aggregates, split the feature so each aggregate's invariants are tested within one feature. +**Aggregate Boundary Validation**: Aggregates define transactional consistency boundaries. A feature that modifies data across two aggregates in one transaction violates aggregate design. If a feature spans multiple aggregates, split the feature so each aggregate's invariants are tested within one feature. -**Naming and Description Convention**: Feature names come from the delivery step name, validated for clarity. Good names are specific enough that a developer knows what to build and a tester knows what to verify. Descriptions follow a four-part pattern: (1) what the feature provides, (2) which bounded context it serves, (3) why it exists — the business need, (4) key entities from the domain spec that belong to this feature. +**Naming and Description Convention**: Feature names are noun phrases validated for clarity. Good names are specific enough that a developer knows what to build and a tester knows what to verify. Descriptions follow a four-part pattern: (1) what the feature provides, (2) which bounded context it serves, (3) why it exists — the business need, (4) key entities from the domain spec that belong to this feature. **Cross-Cutting Concerns**: Risk management, error handling, logging, and observability span multiple contexts. These are not separate features. Instead, they appear as Constraints in the features where they are implemented. The domain spec's context map shows which contexts have safety or error-handling responsibilities. Map those responsibilities to Constraints, not to separate features. @@ -32,7 +32,7 @@ last-updated: 2026-05-08 ### Feature Boundary Derivation Process -1. **List delivery steps as feature candidates**: Read product_definition.md delivery order. Each numbered step is a feature candidate. Record: step number, name, module, and summary. +1. **List feature candidates**: Each bounded context's simulation-created .feature file is a feature candidate. Record: context name, entities, and summary. 2. **Map each candidate to bounded contexts**: For each candidate, identify which bounded contexts its entities belong to using the domain spec's entity table. If a candidate spans multiple contexts, split it. @@ -44,13 +44,13 @@ last-updated: 2026-05-08 ### Splitting Criteria -When a delivery step spans multiple contexts or aggregates: +When a feature spans multiple contexts or aggregates: | Signal | Split | Keep together | |--------|-------|---------------| | Spans 2+ bounded contexts | Split along context boundaries | Shared-kernel types (Domain shared), Orchestrator, Tightly coupled co-deployed | | Spans 2+ aggregates | Split along aggregate boundaries | If aggregates must be transactionally consistent | -| Delivery step name contains "and" | Likely two features | If "and" joins inseparable aspects | +| Feature name contains "and" | Likely two features | If "and" joins inseparable aspects | ### Cross-Cutting Concern Mapping diff --git a/.opencode/knowledge/requirements/feature-discovery.md b/.opencode/knowledge/requirements/feature-discovery.md index db81996e..d24a2beb 100644 --- a/.opencode/knowledge/requirements/feature-discovery.md +++ b/.opencode/knowledge/requirements/feature-discovery.md @@ -14,6 +14,7 @@ last-updated: 2026-05-14 - Rules are written directly to .feature files during simulation. Refine-features (in define-flow) splits, renames, adds descriptions, and validates rules. After define-flow, Feature titles, Rule titles, and Constraints are FROZEN. - Gaps discovered during feature refinement (a bounded context with no feature, a quality attribute with no enforcing feature) are flagged, not silently filled. - Features progress through a lifecycle: Rule blocks from simulation → feature boundaries and descriptions from refine-features → Example blocks from feature-examples. +- Feature selection order is derived at selection time from the context map dependency graph and WSJF scoring — not from a pre-authored delivery order. ## Concepts @@ -27,7 +28,7 @@ last-updated: 2026-05-14 **Feature Lifecycle**: Features follow a lifecycle of increasing specificity across phases: 1. **Simulation** (define-flow): Rules written directly to .feature files during simulation, grouped by bounded context. Technology constraints written as `# Constraints:`. -2. **Refinement** (define-flow, refine-features): Feature boundaries identified from simulation-created .feature files. Features are split/renamed based on Delivery Order and context map. Rule blocks redistributed (content unchanged). Quality attributes mapped to `# Constraints:`. Rule titles validated for INVEST. Feature titles and descriptions finalized. +2. **Refinement** (define-flow, refine-features): Feature boundaries identified from simulation-created .feature files. Features are split/renamed based on context map and aggregate boundaries. Rule blocks redistributed (content unchanged). Quality attributes mapped to `# Constraints:`. Rule titles validated for INVEST. Feature titles and descriptions finalized. 3. **Example Writing** (develop-flow, feature-examples): Rules converted to Gherkin Example/Scenario Outline blocks with pre-mortem analysis. ## Content @@ -36,7 +37,7 @@ last-updated: 2026-05-14 Feature discovery is two sequential activities: -1. **Boundary identification** (refine-features skill): Use the delivery order from product_definition.md as backbone. Map each step to bounded contexts and aggregates from the domain spec. Split candidates that span contexts or aggregates. Name features and write descriptions per [[requirements/feature-boundaries]]. +1. **Boundary identification** (refine-features skill): Use the context map from domain_spec.md as backbone. Map each bounded context to feature candidates from simulation-created .feature files. Split candidates that span contexts or aggregates. Name features and write descriptions per [[requirements/feature-boundaries]]. 2. **Rule organization** (refine-features skill): For each feature, organize the Rule blocks already written to .feature files during simulation. Split/rename Rules per context boundaries. Map quality attributes to constraints. Write `# Constraints:` into each .feature file. Validate INVEST criteria. @@ -53,7 +54,7 @@ Gaps are recorded in the relevant interview notes. Do NOT silently fill gaps wit ## Related -- [[requirements/feature-boundaries]]: deriving feature boundaries from delivery order and domain spec +- [[requirements/feature-boundaries]]: deriving feature boundaries from context map and domain spec - [[requirements/spec-simulation]]: how rules are discovered during simulation - [[requirements/invest]]: INVEST criteria applied to Rule blocks - [[requirements/wsjf]]: feature prioritization applied to BASELINED features diff --git a/.opencode/skills/create-domain-spec/SKILL.md b/.opencode/skills/create-domain-spec/SKILL.md index 8b344a16..8ab1c4c4 100644 --- a/.opencode/skills/create-domain-spec/SKILL.md +++ b/.opencode/skills/create-domain-spec/SKILL.md @@ -9,7 +9,7 @@ Available knowledge: [[domain-modeling/event-storming#concepts]], [[domain-model 1. Read all interview notes from `in` artifacts. 2. Identify bounded contexts from interview data: scan for clusters of related terminology, distinct lifecycles, and independent business capabilities per [[domain-modeling/event-storming#concepts]]. Record each context with a name, responsibility, and rough boundary. -3. Write `product_definition.md` from the trimmed template: What IS/IS NOT, Why, Users, Quality Attributes, Out of Scope, Delivery Order. Use the interview data to fill every section. The delivery order drives which context gets specified and simulated first. +3. Write `product_definition.md` from the trimmed template: What IS/IS NOT, Why, Users, Quality Attributes, Out of Scope. Use the interview data to fill every section. 4. Write `domain_spec.md` from the template at `.templates/docs/spec/domain_spec.md.template`. This is a single monolithic file — one `## ` section per bounded context. Fill in iteration-0 content for each context: - **Context Map**: leave the top-level section empty — architecture-flow context-mapping state refines it. - **Context**: 2-3 sentences about what this context does and why it exists. @@ -21,4 +21,4 @@ Available knowledge: [[domain-modeling/event-storming#concepts]], [[domain-model - **External Contracts**: actor, trigger, input shape, output shape, known error conditions, side effects, and preconditions. Details may have `?` for unknowns. - Leave **State Machines**, **Error Handling**, and **Invariants** empty — simulation discovers these. 5. Write `glossary.md` from the template at `.templates/docs/spec/glossary.md.template`. Extract domain terms from interview notes per [[requirements/ubiquitous-language#key-takeaways]]. Define each in genus-differentia format. Cross-reference against domain spec. -6. Verify: every bounded context has a `## ` section in domain_spec.md. Every delivery order entry maps to at least one context. Every quality attribute is noted for simulation targeting. Every external contract has at least one input/output pair defined. +6. Verify: every bounded context has a `## ` section in domain_spec.md. Every quality attribute is noted for simulation targeting. Every external contract has at least one input/output pair defined. diff --git a/.opencode/skills/refine-features/SKILL.md b/.opencode/skills/refine-features/SKILL.md index 05b94479..8853b698 100644 --- a/.opencode/skills/refine-features/SKILL.md +++ b/.opencode/skills/refine-features/SKILL.md @@ -10,12 +10,11 @@ Available knowledge: [[requirements/feature-boundaries]], [[requirements/feature This state transforms the output of spec-validation (context-level .feature files) into the final feature-level structure that develop-flow will use. After this state, .feature file structure (Feature titles, Rule titles, Constraints) is FROZEN. Only Examples/Outlines may be added during develop-flow. 1. Read `product_definition.md`, `domain_spec.md`, `glossary.md`, and `features/*.feature` from `in` artifacts. The .feature files are simulation-created (one per bounded context, named by context). -2. Read `product_definition.md` delivery order. This determines feature priority and grouping. -3. For each bounded context in `domain_spec.md`, identify feature candidates per [[requirements/feature-boundaries#key-takeaways]]: +2. For each bounded context in `domain_spec.md`, identify feature candidates per [[requirements/feature-boundaries#key-takeaways]]: - Map candidates to bounded contexts. IF a candidate spans multiple contexts → flag for splitting. - Map candidates to entities and aggregate boundaries. IF a candidate requires cross-aggregate transactions → flag for splitting. -4. Create feature-level .feature files by splitting context-level files per [[requirements/feature-discovery#concepts]]: - - Name each feature per [[requirements/feature-boundaries#content]]: use the delivery step name, validated for clarity and specificity. +3. Create feature-level .feature files by splitting context-level files per [[requirements/feature-discovery#concepts]]: + - Name each feature per [[requirements/feature-boundaries#content]]: use a noun phrase that names a cohesive capability, validated for clarity and specificity. - The Feature title slug MUST match the .feature filename stem per [[requirements/gherkin#concepts]]. - Redistribute Rule blocks across split features. When a context .feature file is split into multiple features, move Rule blocks to the appropriate feature file. Do NOT edit Rule block content — only redistribute. IF a rule spans multiple features → flag for cross-cutting handling. - Delete the original context-level .feature files after all their Rules have been redistributed to feature-level files. diff --git a/.opencode/skills/select-feature/SKILL.md b/.opencode/skills/select-feature/SKILL.md index 9e4c04a0..45c73860 100644 --- a/.opencode/skills/select-feature/SKILL.md +++ b/.opencode/skills/select-feature/SKILL.md @@ -1,6 +1,6 @@ --- name: select-feature -description: "Select the next feature to develop by detecting delivery status from disk evidence, following delivery order" +description: "Select the next feature to develop by detecting delivery status from disk evidence, deriving priority from dependency count and WSJF" --- # Select Feature @@ -9,27 +9,28 @@ Available knowledge: [[requirements/wsjf#key-takeaways]]. `in` artifacts: read a 1. List available feature files in `docs/features/`. 2. IF no feature files exist → exit via `no-features`; features need discovery first. -3. Read `product_definition.md` to obtain the delivery order (ordered list of feature slugs). Validate against `domain_spec.md` context map to ensure dependency order is respected. -4. For each feature slug in delivery order, determine delivery status with a single pipeline - — do NOT open or read individual feature or test files: +3. For each feature, determine delivery status — do NOT open or read individual feature or test files: - a. Check if the feature file has Example blocks (any line starting with `Example:`). - If none, the feature has not been broken down into BDD examples yet → feature is incomplete (select it). + a. Check if the feature file has Example blocks (any line starting with `Example:`). + If none, the feature has not been broken down into BDD examples yet → feature is incomplete. - b. Run `beehave check ` to verify structural traceability: - - Any output (errors) → some Examples lack matching test functions or there are orphan tests → feature is incomplete (select it). - - No output (clean) → all Examples have matching test functions. + b. Run `beehave check ` to verify structural traceability: + - Any output (errors) → some Examples lack matching test functions or there are orphan tests → feature is incomplete. + - No output (clean) → all Examples have matching test functions. - c. If beehave check is clean, run the tests scoped to that feature's test directory - using the project's test runner (see Project Commands table). - - Any failures → feature is incomplete (select it). + c. If beehave check is clean, run `task test-fast` scoped to that feature's test directory. + - Any failures → feature is incomplete. - All pass → feature is delivered (skip). - d. If the test directory does not exist, beehave check will report errors - → feature is incomplete (select it). - -5. Collect all incomplete features. IF this is the first feature (no features have been delivered yet) → select the first incomplete feature by delivery order. Skip to step 7. -6. IF subsequent features: score each incomplete feature per [[requirements/wsjf#key-takeaways]]. For each, estimate Value (1-5, mapped to Kano categories) and Effort (1-5, mapped to complexity). Compute WSJF = Value / Effort. Eliminate Dependency=1 features. Select the highest WSJF score; ties broken by Value. -7. IF every feature in the delivery order is delivered (diff clean + tests pass for all) → - exit via `no-features`. + d. If the test directory does not exist, beehave check will report errors → feature is incomplete. + +4. IF every feature is delivered → exit via `no-features`. +5. Collect all incomplete features. Derive dependency count for each from `domain_spec.md` context map: + - Count how many other incomplete features this feature depends on (via integration points and entity relationships in the context map). + - Filter: select features with the **lowest dependency count** first (0 = no dependencies). +6. IF only one feature has the lowest dependency count → select it. Skip to step 8. +7. IF multiple features tie on dependency count → score each tied feature per [[requirements/wsjf#key-takeaways]]: + - Estimate Value (1-5, mapped to Kano categories) and Effort (1-5, mapped to complexity). + - Compute WSJF = Value / Effort. + - Select the highest WSJF score; ties broken by Value. 8. Set the `feature_id` session param to the selected feature's filename stem (without `.feature` extension). diff --git a/.templates/docs/features/.feature.template b/.templates/docs/features/.feature.template index bcde60ff..86ad3954 100644 --- a/.templates/docs/features/.feature.template +++ b/.templates/docs/features/.feature.template @@ -5,4 +5,4 @@ Feature: Discovered rules are written as Rule blocks during simulation, then refined into feature boundaries by refine-features. Examples and - Scenario Outline blocks are added during feature-examples.> \ No newline at end of file + Scenario Outline blocks are added later during feature-examples flow.> diff --git a/.templates/docs/research/TEMPLATE.md.template b/.templates/docs/research///.md.template similarity index 100% rename from .templates/docs/research/TEMPLATE.md.template rename to .templates/docs/research///.md.template diff --git a/.templates/docs/spec/domain_spec.md.template b/.templates/docs/spec/domain_spec.md.template index ed7a73b2..ff9cff54 100644 --- a/.templates/docs/spec/domain_spec.md.template +++ b/.templates/docs/spec/domain_spec.md.template @@ -1,17 +1,5 @@ # Domain Specification -> **Status:** DRAFT | VALIDATED (YYYY-MM-DD) -> Monolithic: all bounded contexts in one file. -> Each `## ` section is a context boundary. -> Contains structural domain information: entities, relationships, aggregates, -> context map, data shapes, integration points, and external contracts. -> Behavioral content (walkthroughs, rules, pain points) is discovered during -> simulation and written to `.feature` files. -> State Machines, Error Handling, and Invariants are derived summaries that -> reference `.feature` file rules — the `.feature` files are the authoritative -> source for behavioral specification. -> NO Given/When/Then here — that belongs in `.feature` files. - --- ## Context Map diff --git a/.templates/docs/spec/glossary.md.template b/.templates/docs/spec/glossary.md.template index 6fe9290f..8cdf2686 100644 --- a/.templates/docs/spec/glossary.md.template +++ b/.templates/docs/spec/glossary.md.template @@ -7,73 +7,12 @@ --- -## Artifact Terms +## + + **Definition:** -### walkthrough - **Definition:** A mental path (happy, edge, or error) that the System Architect walks through the domain spec during simulation to surface discovered rules and pain points. - **Aliases:** simulation scenario (deprecated) - **Source:** discovery-flow + **Aliases:** + + **Example:** -### discovered rule - **Definition:** A plain-language behavioral statement surfaced by a walkthrough during spec simulation. Written as a Rule block in the .feature file. - **Aliases:** business rule, coarse rule, rule discovered (deprecated) - **Source:** spec-validation-flow - -### Rule - **Definition:** A behavioral requirement subject to INVEST validation. Represented as a `Rule:` block in a .feature file consisting of a 2-6 word title followed by a behavioral description paragraph. - **Aliases:** user story (deprecated), story (deprecated) - **Source:** planning-flow - -### Rule block - **Definition:** The Gherkin `Rule:` section in a .feature file: a 2-6 word title followed by a behavioral description paragraph. The authoritative form of a behavioral requirement. - **Source:** planning-flow - -### behavior hint - **Definition:** A one-line behaviorally-distinct outcome description written under a Rule block during feature-breakdown. Format: `- → `. Converted to Example or Scenario Outline blocks during feature-examples. - **Aliases:** scenario hint, Scenarios:, # Business rules: (deprecated) - **Source:** planning-flow - -### Example block - **Definition:** The Gherkin `Example:` section in a .feature file: a 2-6 word title followed by Given/When/Then steps describing a single behavioral outcome. - **Aliases:** BDD scenario, BDD example, acceptance criterion (deprecated) - **Source:** planning-flow - -### Scenario Outline block - **Definition:** The Gherkin `Scenario Outline:` section in a .feature file: a title with `` syntax and an `Examples:` data table. Used when the same behavioral outcome must be verified across 3+ input/output value combinations. - **Source:** planning-flow - -### pain point - **Definition:** A gap, contradiction, ambiguity, or edge case found during spec simulation. Classified as ambiguous, contradictory, missing, or edge-case. Tracked in `.cache/sim/simulation_results_.md`. - **Source:** spec-validation-flow - ---- - -## Specification Architecture - -### domain_spec.md - **Definition:** Monolithic structural domain specification. Contains context map, entities, relationships, aggregate boundaries, data shapes, integration points, and external contracts. Behavioral sections (State Machines, Error Handling, Invariants) are derived summaries that reference .feature file rules. - **Source:** discovery-flow - -### simulation_results_.md - **Definition:** Per-iteration simulation environment artifact in `.cache/sim/`. Contains walkthroughs performed (with Discovered Rule column referencing .feature Rule titles), pain points, resolution status, and reviewer PASS/FAIL decision. Rules themselves live in .feature files. Not a persistent specification — domain knowledge migrates to domain_spec.md and .feature files during the spec-validation loop. - **Source:** spec-validation-flow - -### .feature file - **Definition:** BDD specification for a single feature. The single source of truth for behavioral requirements: contains Feature title, description, Constraints, Rule blocks, and Example/Scenario Outline blocks. Progressively refined across simulation → discovery → breakdown → examples. - **Source:** spec-validation-flow, planning-flow - ---- - -## Deprecated Terms - -These terms are retired. Do not use in new artifacts. - -| Term | Replaced By | Retired | -|------|-------------|---------| -| scenario (simulation) | walkthrough | 2026-05-15 | -| business rules | Rule block, discovered rule | 2026-05-15 | -| # Business rules: | (removed — rules are Rule blocks) | 2026-05-15 | -| story, user story | Rule, Rule block | 2026-05-15 | -| BDD scenario | Example block | 2026-05-15 | -| Scenario: keyword | Example: keyword | 2026-05-15 | -| As a/I want/So that | Behavioral description paragraph | 2026-05-15 | + **Source:** diff --git a/.templates/docs/spec/product_definition.md.template b/.templates/docs/spec/product_definition.md.template index 35921cce..b3256395 100644 --- a/.templates/docs/spec/product_definition.md.template +++ b/.templates/docs/spec/product_definition.md.template @@ -1,8 +1,5 @@ # Product Definition: -> **Status:** ELICITING | BASELINED (YYYY-MM-DD) -> Fill in each section during Discovery. Replace placeholders with project-specific content. - --- ## What IS @@ -38,14 +35,3 @@ - ---- - -## Delivery Order - -< Stakeholder-prioritized delivery sequence. Each step is a feature candidate. - feature-discovery validates this order against the context map dependency graph - but does not replace it — business priority is a stakeholder decision. > - -1. -2. -3. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b4cf7e8..798442b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ All notable changes to this template will be documented in this file. ### Added - **Decomposition decision tree**: replaced 5 stale triggers (">8 candidate Examples", ">2 concerns", undefined "concerns") with behavioral decision tree: group by Then-outcome → collapse Scenario Outlines → count Must behaviors → >8 Musts splits Rule. Structural triggers: >1 bounded context, "and" joining independently testable outcomes, no beneficiary, duplicate Rule. -- **WSJF scoring wired**: `select-feature` now scores subsequent features by WSJF (Value/Effort/Dependency) per `[[requirements/wsjf#key-takeaways]]`. First feature still selected by delivery order. +- **WSJF scoring wired**: `select-feature` now scores all features by dependency count (lowest first), then WSJF (Value/Effort) per `[[requirements/wsjf#key-takeaways]]`. Delivery order derived at selection time from context map dependency graph. - **AI language markers expanded**: Tier 1 +25 words (navigate, harness, seamless, boilerplate, etc.), Tier 4 +4 phrases, new Tier 7 Claude-Specific Structural Patterns (8 patterns), Claude detection dimension in scoring table. - **Domain spec template**: Integration Points section now requires Mechanism, Error handling, Ownership fields (synced with context-mapping knowledge). diff --git a/docs/audit/document-landscape-audit.md b/docs/audit/document-landscape-audit.md index b2c3eeff..a951650b 100644 --- a/docs/audit/document-landscape-audit.md +++ b/docs/audit/document-landscape-audit.md @@ -56,7 +56,7 @@ How many states READ each document. Higher consumption = higher system value. | `domain_model.md` | The WHAT. Bounded contexts, entities, relationships, aggregates. Without it, no agent knows what the system models. Consumed by 14 states. | | `glossary.md` | The WORDS. Shared language that keeps code, specs, and tests coherent. Without it, agents generate inconsistent naming. Consumed by 14 states. | | `technical_design.md` | The HOW. Stack, API contracts, event contracts, interfaces, module structure. The blueprint agents need to generate code structure. Consumed by 10 states. | -| `product_definition.md` | The WHY & WHO. Scope boundaries, users, delivery order, quality attributes, definition of done. Prevents scope creep and prioritizes work. Consumed by 15 states. | +| `product_definition.md` | The WHY & WHO. Scope boundaries, users, quality attributes. Prevents scope creep and drives architecture. Consumed by 15 states. | | `features/.feature` | The BEHAVIOR. Rules + BDD examples are the executable specification. These ARE the tests. Without them, no agent knows what correct behavior looks like. Consumed by 12 states. | | `system.md` | The TRUTH. Current-state system overview, key decisions, active constraints. Evolves with the system. The only document that reflects what IS (vs what was planned). Consumed by 5 states. | @@ -113,7 +113,7 @@ How many states READ each document. Higher consumption = higher system value. | `Users` | **MUST** | Personas. Determines who features serve. | | `Quality Attributes` | **MUST** | Measurable scenarios that drive architecture. Referenced by architecture-assessment, technical-design, definition-of-done, review-gate. Written by scope-boundary, updated by architecture-assessment. | | `Out of Scope` | **MUST** | Explicit non-goals. Boundary enforcement. | -| `Delivery Order` | **MUST** | Feature dependency chain. Drives feature-selection state. | +| `Delivery Order` | **REMOVED** | Feature selection order is now derived at selection time from the context map dependency graph and WSJF scoring. | | `Definition of Done` | **MUST** | Quality gates per feature. Written by definition-of-done state. Consumed implicitly by review and acceptance. | | `Deployment` | **MUST** | Deployment type and checklist. Written by scope-boundary, updated by architecture-assessment. | | `Branch Strategy` | **COULD** | Conventions. Could live in AGENTS.md or CONTRIBUTING.md instead. | @@ -338,7 +338,7 @@ Each layer consumes the one below it. No document can be eliminated without losi | 1 | `domain_model.md` | Bounded contexts, entities, value objects, relationships, aggregate boundaries with invariants | Summary, Bounded Contexts, Entities, Relationships, Aggregate Boundaries (4 of 8 sections) | | 2 | `glossary.md` | Consistent naming across all generated code | All entries | | 3 | `technical_design.md` | Stack choice, module layout, API contracts, event contracts, port interfaces, dependencies, config keys | All 10 sections (C4 Diagrams optional) | -| 4 | `product_definition.md` | Scope boundaries, users, delivery order, quality attributes, definition of done, deployment checklist | 8 of 9+ sections (Why optional, Branch Strategy not needed) | +| 4 | `product_definition.md` | Scope boundaries, users, quality attributes, definition of done, deployment checklist | 7 of 8+ sections (Why optional, Branch Strategy not needed) | | 5 | `features/*.feature` | Per-feature: rules (user stories) and examples (BDD Given/When/Then with @id tags) | title, description, Rules, Examples, Constraints (5 of 6+ sections) | | 6 | `system.md` | Current-state architecture, key decisions, active constraints | Summary, Delivery, Context, Container, Module Structure, Domain Model Documentation, Active Constraints, Key Decisions (8 of 9+ sections) | diff --git a/docs/research/CONTRACT_spec_simulation_redesign.md b/docs/research/CONTRACT_spec_simulation_redesign.md deleted file mode 100644 index 9c06dc14..00000000 --- a/docs/research/CONTRACT_spec_simulation_redesign.md +++ /dev/null @@ -1,376 +0,0 @@ -# Contract: Spec Simulation Redesign - -> Status: IN PROGRESS — adversarial audit findings being fixed -> Date: 2026-05-14 -> Replaces: classical discovery->architecture->feature->TDD flow with simulation-first approach - ---- - -## 1. Problem Statement - -Classical discovery->feature->TDD flow produces specs that are never tested before code is written. This causes 3-5 restart cycles when end-to-end integration reveals fundamental spec issues. The root cause: specs describe structure (entities, events) but not behavior (state transitions, error handling, edge cases). By the time code is written against these specs, gaps are expensive to fix. - -## 2. Solution: Simulate Before Code - -Spec simulation is a tabletop exercise: the agent mentally walks through the system described in the spec, creates I/O pairs as evidence in /tmp, and discovers rules, pain points, and E2E test candidates. The spec is rewritten to address findings. This loop repeats until the spec is clean. Only THEN do features, code, and tests get created. - -**Key principles**: -- Rules are DISCOVERED through simulation, not pre-written. -- Given/When/Then is the LAST step (in .feature files), not the first (in spec documents). -- No user stories (As a/I want/So that). Rules are descriptive statements with unique titles that map directly to Example titles. -- No numbered prefixes (R001, SIM-001). Use descriptive text; beehave already provides unique IDs via titles. -- External contracts define how users/systems interact with the solution — these are the primary simulation target. - -## 3. Behavioral Spec Evolution - -The behavioral spec starts as a minimal structural skeleton and evolves through simulation: - -**Iteration 0** (from spec-creation): -- Context description (what this bounded context does) -- Entities and their purpose -- Data shapes (field names, types — constraints may be `?`) -- Integration points (inter-context communication) -- External contracts (how users/systems interact with this context — actor, trigger, input, output, errors) -- No rules, no state machines, no Given/When/Then - -**Simulation N** adds: -- Rules discovered (descriptive statements, no numbered prefixes) -- Pain points resolved (descriptive statements, no numbered prefixes) -- Data constraints refined (`?` -> concrete constraints) -- State machines emerge from accumulated rules -- Error handling paths discovered -- External contract details refined (error cases, preconditions, side effects) - -**Final spec** (after validation loop): -- Complete state machines -- All rules discovered (descriptive statements) -- All data constraints concrete -- All integration contracts defined -- All external contracts fully specified -- All error paths specified -- Zero unresolved pain points - -## 4. New Flow Structure - -``` -main-flow - |-- discovery-flow (2 states) - | |-- stakeholder-interview (PO: conduct-interview) - | '-- spec-creation (SA+DE: create-behavioral-spec + define-ubiquitous-language) - | - |-- spec-validation-flow (NEW, 3 states, iterative loop) - | |-- simulate-spec (SA: simulate-spec) - | |-- review-simulation (R: review-simulation) - | '-- fix-spec (SA+DE: fix-spec, loops to simulate-spec or exits) - | [cap: 5 iterations -> escalate root causes to stakeholder] - | - |-- architecture-flow (4 states, same structure) - | |-- architecture-assessment - | |-- context-mapping - | |-- technical-design - | '-- review-signoff - | - '-- feature-development-flow (same structure) - |-- planning-flow - | |-- feature-selection (rules from simulation_results) - | |-- feature-breakdown (verify rules, write Rule blocks, INVEST validation) - | |-- feature-examples (Given/When/Then written HERE) - | |-- spec-review - | '-- create-py-stubs (beehave generate) - |-- development-flow (TDD cycle) - '-- delivery-flow (acceptance, merge, publish) -``` - -## 5. Git Branch Strategy - -**dev branch model**: All project-level commits go to `dev`, not `main`. - -- `main`: production-ready, stable. Only receives changes via PR from dev. -- `dev`: integration branch. Discovery, architecture, spec validation commits go here. -- Feature branches: `feat/` branched from `dev`, merged back to `dev`. -- PRs: created from `dev` -> `main` when stakeholder decides to publish. - -Changes from current model: -- All `git: main` in flows -> `git: dev` -- `committed-to-main-locally` condition -> `committed-to-dev-locally` -- `merge-local` skill: squash-merges feature -> `dev` (was feature -> main) -- `create-pr` skill: pushes `dev` to remote, creates PR dev -> main -- `publish-decision`: decides whether to PR dev -> main - -## 6. Template Changes - -### product_definition.md (TRIM: ~50 lines from 119) - -Remove: DoD checklist, Deployment checklist, Scope Changes table. Those belong in AGENTS.md. - -Keep: Vision, Why, Users, IS/IS NOT, Quality Attributes, Out of Scope, Delivery Order. - -### domain_model.md (KEEP, trimmed) - -Keep `domain_model.md.template` for the structural domain model (entities, relationships, bounded contexts, aggregates, context map). This is the project-wide WHAT EXISTS view. Remove events/commands tables (those concepts feed into domain_spec). Updated template removes: -- Events and Commands section (behavioral -> domain_spec) -- Changes table (use git log) - -### domain_spec.md (NEW) - -Per bounded context. Starts minimal (iteration 0), evolves through simulation. Template sections: - -1. **Context**: what this bounded context does (2-3 sentences) -2. **Entities**: name, purpose, rough lifecycle -3. **Data Shapes**: field name, type, constraints (may be `?` initially) -4. **Integration Points**: inter-context communication, trigger, payload/response shape -5. **External Contracts**: how users/external systems interact — actor, trigger, input, output, errors, side effects, preconditions. PRIMARY simulation target. -6. **State Machines**: emerge from simulation (empty at iteration 0) -7. **Error Handling**: discovered during simulation (empty at iteration 0) -8. **Invariants**: discovered during simulation (empty at iteration 0) -9. **Rules Discovered**: descriptive statements from simulation (empty at iteration 0) -10. **Pain Points**: unresolved issues from simulation (empty at iteration 0) - -NO Given/When/Then. NO As a/I want/So that. NO numbered prefixes. - -### simulation_results.md (NEW) - -Per simulation iteration. Contains: -1. Iteration number and context being simulated -2. Scenarios walked (happy path, edge cases, error paths) -3. I/O pairs created in /tmp/sim// -4. Pain points found (descriptive statements, no prefixes) -5. Rules discovered (descriptive statements, no prefixes) -6. E2E test candidates (descriptive titles suitable for Example: titles) -7. Resolution status per pain point - -### glossary.md (UNCHANGED) - -### feature.template (UNCHANGED) - -## 7. Skill Changes - -### NEW Skills (4) - -**create-behavioral-spec** (owner: SA+DE): -- Reads interview notes -- Identifies bounded contexts from interview data -- Creates product_definition.md (trimmed template) -- Creates domain_model.md (structural: entities, relationships, aggregates, contexts) -- Creates domain_spec.md per bounded context (structural skeleton + external contracts only) -- Creates glossary.md with initial terms -- NO rules, NO state machines, NO Given/When/Then - -**simulate-spec** (owner: SA): -- Reads domain_spec.md for a bounded context -- Primary simulation against external contracts: walk each contract's input -> output -- Walks through scenarios mentally: happy paths, edge cases, error paths -- Creates I/O pairs in /tmp/sim// as evidence -- Discovers rules and pain points -- Writes simulation_results.md - -**review-simulation** (owner: R): -- Adversarial review of simulation_results.md -- Adds missed scenarios -- Validates pain points are real -- Decides: PASS (spec clean enough) or FAIL (needs more work) -- Exit criteria: zero unresolved pain points, all external contracts covered, all state transitions covered, all error paths specified - -**fix-spec** (owner: SA+DE): -- Rewrites domain_spec.md addressing all pain points from simulation -- Full rewrite for coherence, not patches -- Incorporates discovered rules -- Fills in `?` constraints -- State machines emerge from accumulated rules - -### MODIFIED Skills (8) - -**discover-features**: -- Rules source: simulation_results.md (was domain_model.md) -- Still reads product_definition.md for delivery order and domain_model.md for entity/context mapping -- Still creates .feature files with title + description + # Business rules: + # Constraints: -- Rules come FROM simulation results, not from event-storming derivation - -**discover-rules**: -- Rules source: simulation_results.md discovered rules (was domain_model events/invariants/commands) -- Writes `# Business rules:` and `# Constraints:` into .feature files from simulation findings -- Traceability: every simulation rule -> at least one feature rule - -**break-down-feature**: -- No user stories (As a/I want/So that removed) -- Rules from simulation are already validated — skill verifies they're specific enough -- Writes Rule: blocks using rule text directly as title -- INVEST validation stays - -**write-bdd-features**: -- No user stories reference -- Writes Given/When/Then Examples under Rule: blocks -- Same Example quality criteria (observable, declarative, distinct, pre-mortem coverage) - -**conduct-interview**: -- `domain_model.md` references -> `domain_spec.md` + `domain_model.md` - -**map-contexts** (architecture-flow): -- in: domain_spec.md + domain_model.md (was domain_model.md only) - -**define-ubiquitous-language**: -- References change from domain_model.md to domain_model.md + domain_spec.md - -**merge-local**: -- Squash-merges feature -> `dev` (was feature -> main) - -**create-pr**: -- Pushes `dev` to remote, creates PR dev -> main (was push main) - -### REMOVED Skills (3) - -- **facilitate-event-storming**: folded into create-behavioral-spec (event storming concepts absorbed into behavioral-contracts knowledge) -- **domain-discovery**: folded into create-behavioral-spec -- **define-product-scope**: folded into create-behavioral-spec (product_definition written there) - -## 8. Knowledge Changes - -### NEW Knowledge (2) - -**requirements/spec-simulation.md**: Simulation technique, I/O file format (/tmp/sim//), pain point classification (ambiguous / contradictory / missing / edge-case), rules as descriptive statements (no numbered prefixes), external contract simulation priority, exit criteria (zero unresolved pain points). - -**domain-modeling/behavioral-contracts.md**: How to write state machines, data shapes, integration contracts, external contracts. Event storming concepts (events, commands, aggregates) absorbed here as background knowledge for spec creation, not as separate workshop step. - -### MODIFIED Knowledge (5) - -**requirements/feature-discovery.md**: Rules come from simulation_results.md, not from event-storming derivation. Lifecycle updated: discovery creates structural spec + external contracts -> simulation discovers rules -> planning groups rules into features. - -**requirements/rule-derivation.md**: Sources change from domain model events/invariants/commands -> simulation discovered rules. Traceability: simulation rule -> feature rule -> Example. - -**architecture/reconciliation.md**: domain_model.md references stay (structural model is kept). Add domain_spec.md to cross-document checks. Cross-document checks updated. - -**software-craft/git-conventions.md**: main -> dev branch model. Squash-merge to dev. PR from dev -> main. Local dev as staging area (was local main). - -**architecture/adr.md**: Example criteria references stay the same (title-based, not @id). - -### DEPRECATED Knowledge (1) - -**domain-modeling/event-storming.md**: Concepts absorbed into behavioral-contracts.md. File kept for reference but no skills reference it. - -## 9. Flow YAML Changes - -### discovery-flow.yaml (REWORK: 4 states -> 2) [DONE] - -States: -1. stakeholder-interview (PO, conduct-interview) -> git: dev -2. spec-creation (SA, skills: create-behavioral-spec, define-ubiquitous-language) -> git: dev - -Exits: complete -Out: product_definition.md, domain_model.md, domain_spec.md, glossary.md - -### spec-validation-flow.yaml (NEW: 3 states + loop) [DONE] - -States: -1. simulate-spec (SA, skill: simulate-spec) -> git: dev -2. review-simulation (R, skill: review-simulation) -> git: dev -3. fix-spec (SA, skill: fix-spec) -> git: dev -> loops to simulate-spec or exits -4. validated (exit state, committed-to-dev-locally) - -Exits: validated, needs-reinterview -Conditions: max 5 iterations, escalation to stakeholder at cap - -### main-flow.yaml (UPDATE) [DONE] - -States: discovery -> spec-validation -> architecture -> feature-development -All git: dev (except feature-development which is git: feature) - -### architecture-flow.yaml (UPDATE) [DONE] - -All git: dev. domain_model.md references stay. domain_spec.md added to in. simulation_results.md added to in. committed-to-dev-locally. - -### planning-flow.yaml (UPDATE) [DONE] - -All git: dev. domain_model.md -> domain_spec.md + simulation_results.md. committed-to-dev-locally. - -### feature-development-flow.yaml (UPDATE) [PENDING] - -git: main -> git: dev on planning state. flow-version: "^13". - -### delivery-flow.yaml (UPDATE) [PENDING] - -git: main -> git: dev on local-merge, publish-decision, pr-creation. -committed-to-main-locally -> committed-to-dev-locally. -Description updates: merge to dev, PR dev -> main. - -### branding-flow.yaml (UPDATE) [PENDING] - -git: main -> git: dev. committed-to-main-locally -> committed-to-dev-locally. - -### setup-project-flow.yaml (UPDATE) [PENDING] - -git: main -> git: dev. committed-to-main-locally -> committed-to-dev-locally. - -### post-mortem-flow.yaml (UPDATE) [PENDING] - -git: main -> git: dev. - -### development-flow.yaml, tdd-cycle-flow.yaml (UNCHANGED) - -These operate on feature branches. git: feature stays. - -## 10. Files Summary - -### Create (9 files) -- `.templates/docs/spec/domain_spec.md.template` [DONE] -- `.templates/docs/spec/simulation_results.md.template` [DONE] -- `.flowr/flows/spec-validation-flow.yaml` [DONE] -- `.opencode/skills/create-behavioral-spec/SKILL.md` [DONE] -- `.opencode/skills/simulate-spec/SKILL.md` [DONE] -- `.opencode/skills/review-simulation/SKILL.md` [DONE] -- `.opencode/skills/fix-spec/SKILL.md` [DONE] -- `.opencode/knowledge/requirements/spec-simulation.md` [PENDING] -- `.opencode/knowledge/domain-modeling/behavioral-contracts.md` [PENDING] - -### Modify (20 files) -- `.templates/docs/spec/product_definition.md.template` (trim) [DONE] -- `.flowr/flows/main-flow.yaml` [DONE] -- `.flowr/flows/discovery-flow.yaml` (rework) [DONE] -- `.flowr/flows/architecture-flow.yaml` [DONE] -- `.flowr/flows/planning-flow.yaml` [DONE] -- `.flowr/flows/feature-development-flow.yaml` [PENDING] -- `.flowr/flows/delivery-flow.yaml` [PENDING] -- `.flowr/flows/branding-flow.yaml` [PENDING] -- `.flowr/flows/setup-project-flow.yaml` [PENDING] -- `.flowr/flows/post-mortem-flow.yaml` [PENDING] -- `.opencode/skills/discover-features/SKILL.md` [DONE] -- `.opencode/skills/discover-rules/SKILL.md` [DONE] -- `.opencode/skills/break-down-feature/SKILL.md` [DONE] -- `.opencode/skills/write-bdd-features/SKILL.md` [DONE] -- `.opencode/skills/conduct-interview/SKILL.md` [PENDING] -- `.opencode/skills/map-contexts/SKILL.md` [PENDING] -- `.opencode/skills/define-ubiquitous-language/SKILL.md` [PENDING] -- `.opencode/skills/merge-local/SKILL.md` [PENDING] -- `.opencode/skills/create-pr/SKILL.md` [PENDING] -- `.opencode/knowledge/requirements/feature-discovery.md` [PENDING] -- `.opencode/knowledge/requirements/rule-derivation.md` [PENDING] -- `.opencode/knowledge/architecture/reconciliation.md` [PENDING] -- `.opencode/knowledge/software-craft/git-conventions.md` [PENDING] - -### Delete (3 files) [DONE] -- `.opencode/skills/facilitate-event-storming/SKILL.md` [DONE] -- `.opencode/skills/domain-discovery/SKILL.md` [DONE] -- `.opencode/skills/define-product-scope/SKILL.md` [DONE] - -### Keep unchanged -- `.templates/docs/spec/glossary.md.template` -- `.templates/docs/spec/domain_model.md.template` (restored, trimmed) -- `.templates/docs/features/.feature.template` -- `.opencode/knowledge/domain-modeling/event-storming.md` (kept for reference) -- All development/TDD skills -- All software-craft knowledge (except git-conventions) - -## 11. Rules - -1. No "scaffold" word anywhere — use "create", "generate", "build", "set up". -2. No Given/When/Then in domain_spec.md — it belongs only in .feature files. -3. No As a/I want/So that anywhere — rules are descriptive statements with unique titles. -4. No @id tags — title-based mapping via pytest-beehave. -5. No numbered prefixes for rules/pain points (R001, SIM-001) — use descriptive text. -6. All `git: main` -> `git: dev` across all flows. -7. All `committed-to-main-locally` -> `committed-to-dev-locally`. -8. Feature branches branch from `dev`, merge to `dev`. -9. Simulation loop capped at 5 iterations; escalation to stakeholder at cap. -10. Spec starts minimal (structural skeleton + external contracts), rules discovered through simulation. -11. Full spec rewrite in fix-spec (not patches) for coherence. -12. `beehave generate ` for test stubs, `beehave check` for traceability. -13. External contracts are the primary simulation target — simulate inputs/outputs first. diff --git a/pyproject.toml b/pyproject.toml index 25fe132b..7bf3e252 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "temple8" -version = "9.0.0" +version = "9.0.1" description = "Spec-driven agent orchestration template with YAML flow definitions, multi-agent dispatch, and BDD traceability" readme = "README.md" requires-python = ">=3.14" From 01d8583f209ff136bb256a6492e570d17bdb73fe Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 18 May 2026 10:35:28 -0400 Subject: [PATCH 2/2] fix: sync uv.lock after version bump --- uv.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uv.lock b/uv.lock index 1d49b7ba..3b6a673f 100644 --- a/uv.lock +++ b/uv.lock @@ -955,7 +955,7 @@ wheels = [ [[package]] name = "temple8" -version = "9.0.0" +version = "9.0.1" source = { virtual = "." } [package.optional-dependencies]