feat: session management extended — complete interview requirements

.gitignore

@@ -176,3 +176,10 @@ AGENTS.md
 .opencode/
 
 # Trigger CI run to verify linting fixes
+
+# smith managed source:url:https://github.com/nullhack/temple8/archive/refs/tags/v8.0.0+20260501.tar.gz
+AGENTS.md
+.opencode/
+.templates/
+.flowr/
+# end smith managed

CHANGELOG.md

@@ -21,15 +21,15 @@ All notable changes to this project will be documented in this file.
 - **Mermaid converter**: stateDiagram-v2 export with resolved conditions on transition labels
 - **Validation engine**: MUST/SHOULD conformance levels, ambiguous target detection, cross-flow cycle detection, condition reference checks
 - **6 ADRs**: evidence type system, fuzzy match algorithm, validation result, CLI I/O convention, subflow resolution, condition inlining, image rendering deferral
-- **`docs/spec/flow-definition-spec.md`**: authoritative YAML format specification
-- **`docs/product-definition.md`**: product boundaries, users, and scope
+- **`docs/spec/flow_definition_spec.md`**: authoritative YAML format specification
+- **`docs/spec/product_definition.md`**: product boundaries, users, and scope
 - **Completed features**: `flow-definition-spec`, `flowr-cli`, `named-condition-groups`
 - **Test suite**: feature tests and unit tests for all domain operations
 
 ### Changed
 
 - **README.md**: removed redundant Flow Definition Format and Library Usage sections; added Documentation links to spec, system overview, and product definition
-- **`docs/product-definition.md`**: slimmed from 254 to 49 lines — removed duplicated technical reference content, kept only IS/IS NOT, Why, Users, Out of Scope, Delivery Order
+- **`docs/spec/product_definition.md`**: slimmed from 254 to 49 lines — removed duplicated technical reference content, kept only IS/IS NOT, Why, Users, Out of Scope, Delivery Order
 - **Document cleanup**: removed `docs/discovery.md`, `FLOW.md`, `WORK.md`, `template-config.yaml`; consolidated provenance into `.feature` file `## Changes` sections
 - **Version format**: switched to calver (`major.minor.YYYYMMDD`)
 
@@ -42,19 +42,19 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - **`flowr/__main__.py`**: CLI entrypoint — `python -m flowr --help` and `python -m flowr --version`; zero new dependencies (argparse + importlib.metadata are stdlib)
-- **`docs/adr/ADR-2026-04-22-cli-parser-library.md`**: decision record for choosing `argparse` over click/typer
-- **`docs/adr/ADR-2026-04-22-version-source.md`**: decision record for reading version from `importlib.metadata` at runtime
+- **`docs/adr/ADR_20260422_cli_parser_library.md`**: decision record for choosing `argparse` over click/typer
+- **`docs/adr/ADR_20260422_version_source.md`**: decision record for reading version from `importlib.metadata` at runtime
 - **`docs/features/completed/cli-entrypoint.feature`**: completed feature file for CLI entrypoint
-- **`docs/branding.md`**: project identity, colour palette, release naming convention, and wording guidelines
-- **`docs/glossary.md`**: living glossary with domain terms
-- **`docs/scope_journal.md`**: raw Q&A from discovery sessions
-- **`docs/system.md`**: current-state architecture snapshot with domain model, C4 diagrams, and ADR index
+- **`docs/branding/branding.md`**: project identity, colour palette, release naming convention, and wording guidelines
+- **`docs/spec/glossary.md`**: living glossary with domain terms
+- **`docs/interview-notes/`**: interview notes from discovery sessions (replaces scope_journal.md)
+- **`docs/spec/system.md`**: current-state architecture snapshot with domain model, C4 diagrams, and ADR index
 - **`docs/index.html`**: documentation portal with branding palette, doc cards, tabbed features, ADR list, and research library
 - **`scripts/`**: 10 validation and automation scripts (`assign_ids.py`, `check_adrs.py`, `check_commit_messages.py`, `check_feature_file.py`, `check_oc.py`, `check_stubs.py`, `check_version.py`, `check_work_md.py`, `detect_state.py`, `score_features.py`, `update_index_html.py`)
 - **`.opencode/`**: agents, skills, and knowledge files for AI-assisted development workflow (product-owner, system-architect, software-engineer, designer, setup-project)
 - **CI workflows**: `.github/workflows/ci.yml` (quality, test, build, publish-docs) and `.github/workflows/pypi-publish.yml` (PyPI release via OIDC)
 - **`docs/research/`**: 11 scientific research files covering AI agents, architecture, cognitive science, documentation, domain modeling, OOP design, refactoring, requirements elicitation, software economics, testing, and version control
-- **`docs/adr/ADR-2026-04-22-version-source.md`**: ADR template with interview Q&A and stakeholder validation gate
+- **`docs/adr/ADR_20260422_version_source.md`**: ADR template with interview Q&A and stakeholder validation gate
 - **`tests/features/cli_entrypoint/`**: 3 test files covering 6 acceptance criteria via subprocess
 - **`tests/unit/main_test.py`**: 5 in-process unit tests for 100% coverage
 

README.md

@@ -98,9 +98,9 @@ Evidence can be passed with `--evidence key=value` (repeatable) or `--evidence-j
 ## Documentation
 
 - **[flowr docs](https://nullhack.github.io/flowr/)** — hosted documentation
-- **[Flow Definition Specification](docs/spec/flow-definition-spec.md)** — authoritative YAML format reference (fields, conditions, subflows, validation rules)
-- **[System Overview](docs/system.md)** — architecture, domain model, module structure, and API
-- **[Product Definition](docs/product-definition.md)** — product boundaries, users, and scope
+- **[Flow Definition Specification](docs/spec/flow_definition_spec.md)** — authoritative YAML format reference (fields, conditions, subflows, validation rules)
+- **[System Overview](docs/spec/system.md)** — architecture, domain model, module structure, and API
+- **[Product Definition](docs/spec/product_definition.md)** — product boundaries, users, and scope
 
 ## Development
 

docs/adr/ADR-2026-04-22-cli-parser-library.md → docs/adr/ADR_20260422_cli_parser_library.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-22-cli-parser-library
+# ADR_20260422_cli_parser_library
 
 ## Status
 
@@ -35,3 +35,9 @@ The zero-dependency constraint is non-negotiable for a template that must instal
 - (+) `argparse` `action="version"` handles exit-0 and version string format natively
 - (+) `build_parser()` is independently testable without subprocess overhead
 - (-) `argparse` API is more verbose than click/typer for complex CLIs — acceptable for a 2-flag demonstration skeleton
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Using argparse limits future CLI ergonomics | Low | Low | Revisit in a new ADR if CLI complexity grows | Yes |

docs/adr/ADR-2026-04-22-version-source.md → docs/adr/ADR_20260422_version_source.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-22-version-source
+# ADR_20260422_version_source
 
 ## Status
 
@@ -36,3 +36,9 @@ Use `importlib.metadata.version("flowr")` at runtime.
 - (+) Works correctly in editable installs (`uv sync`) and wheel installs
 - (+) Zero additional imports beyond stdlib
 - (-) Requires the package to be installed (not just on `sys.path` as a raw directory) — acceptable since the feature's Given step is "the application package is installed"
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Package must be installed for version to work | Low | Medium | Editable installs via `uv sync` cover dev; wheel installs cover production | Yes |

docs/adr/ADR-2026-04-26-cli-io-convention.md → docs/adr/ADR_20260426_cli_io_convention.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-cli-io-convention
+# ADR_20260426_cli_io_convention
 
 ## Status
 
@@ -42,3 +42,9 @@ Simplest consistent UX across all subcommands; follows Unix conventions; enables
 - (+) --json flag covers all machine-readable use cases
 - (+) --evidence-json supports complex/nested evidence values
 - (-) Flat evidence via --evidence is limited to key=value pairs (mitigated: --evidence-json for complex cases)
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Flat key=value evidence limits complex inputs | Low | Low | --evidence-json flag mitigates for complex cases | Yes |

docs/adr/ADR-2026-04-26-condition-inlining.md → docs/adr/ADR_20260426_condition_inlining.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-condition-inlining
+# ADR_20260426_condition_inlining
 
 ## Status
 
@@ -44,4 +44,10 @@ Keeping `GuardCondition` unchanged preserves backward compatibility and simplici
 - (+) Early error detection — unknown refs fail at load time, not at validation time
 - (+) Consistent validation — unused-group warnings follow the same SHOULD pattern as unused exits
 - (-) `Transition` dataclass gains a field — minimal increase in memory per transition
-- (-) Loader complexity increases — three `when` forms must be parsed and resolved
+- (-) Loader complexity increases — three `when` forms must be parsed and resolved
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Loader complexity increases with three when forms | Medium | Low | Well-tested with comprehensive BDD scenarios | Yes |

docs/adr/ADR-2026-04-26-evidence-type-system.md → docs/adr/ADR_20260426_evidence_type_system.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-evidence-type-system
+# ADR_20260426_evidence_type_system
 
 ## Status
 
@@ -36,4 +36,10 @@ Eliminates type confusion from YAML's automatic coercion; conditions are pattern
 - (+) Users reason about conditions as string patterns
 - (+) No YAML type coercion surprises
 - (-) Users must remember YAML `true`/`false`/`yes`/`no` become strings
-- (-) Numeric extraction still applies for `>=`, `<=`, `>`, `<` operators (on string representations)
+- (-) Numeric extraction still applies for `>=`, `<=`, `>`, `<` operators (on string representations)
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Users may forget YAML type coercion rules (true/false/yes/no) | Medium | Low | Document in glossary and CLI help; numeric extraction applies to string representations | Yes |

docs/adr/ADR-2026-04-26-fuzzy-match-algorithm.md → docs/adr/ADR_20260426_fuzzy_match_algorithm.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-fuzzy-match-algorithm
+# ADR_20260426_fuzzy_match_algorithm
 
 ## Status
 
@@ -36,4 +36,10 @@ Eliminates the complexity and ambiguity of string fuzzy matching; numeric 5% tol
 - (+) No external dependencies needed
 - (+) No ambiguity about what "small typo tolerance" means
 - (-) No string fuzzy matching capability (strings must use `==` or `!=`)
-- (-) Two existing Examples (`@id:bdd51f94`, `@id:7711a3c7`) need deprecation and replacement with numeric Examples
+- (-) Two existing Examples (`@id:bdd51f94`, `@id:7711a3c7`) need deprecation and replacement with numeric Examples
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| No string fuzzy matching capability; users must use == or != | Low | Low | ~= for strings was never implemented; explicit == and != are clearer | Yes |

docs/adr/ADR-2026-04-26-image-rendering-deferral.md → docs/adr/ADR_20260426_image_rendering_deferral.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-image-rendering-deferral
+# ADR_20260426_image_rendering_deferral
 
 ## Status
 
@@ -34,3 +34,9 @@ No lightweight Python-native rendering option exists; mmdc requires Node.js; Pla
 - (+) 6 clean subcommands for v1 (validate, states, check, next, transition, mermaid)
 - (-) Users cannot generate images from the CLI in v1 (mitigated: mermaid output can be pasted into mermaid.live)
 - (-) Two Examples in the feature file need to be marked @deprecated
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Users cannot generate images from CLI in v1 | High | Low | Mermaid output can be pasted into mermaid.live; image subcommand deferred to v2 | Yes |

docs/adr/ADR-2026-04-26-subflow-resolution.md → docs/adr/ADR_20260426_subflow_resolution.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-subflow-resolution
+# ADR_20260426_subflow_resolution
 
 ## Status
 
@@ -38,3 +38,9 @@ Convention-over-configuration with path flexibility; matches project layout; sup
 - (+) Clear, unambiguous output showing subflow name + entry state
 - (-) Flow field must include `.yaml` extension — existing reference YAML files need updating
 - (-) Flow field has dual meaning (lookup path vs canonical flow name from loaded YAML)
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Flow field has dual meaning (lookup path vs canonical flow name) | Low | Medium | Ambiguity is mitigated by convention; loader extracts canonical name from loaded YAML | Yes |

docs/adr/ADR-2026-04-26-validation-result.md → docs/adr/ADR_20260426_validation_result.md

@@ -1,4 +1,4 @@
-# ADR-2026-04-26-validation-result
+# ADR_20260426_validation_result
 
 ## Status
 
@@ -36,4 +36,10 @@ Collecting all violations gives users a complete picture; a result type with con
 - (+) Clear, self-documenting types with named fields
 - (+) Easy to filter by severity (errors vs warnings)
 - (-) Slightly more types to define (ValidationResult, Violation, ConformanceLevel)
-- (-) Callers must check `is_valid` rather than catching an exception
+- (-) Callers must check `is_valid` rather than catching an exception
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Accepted? |
+|------|------------|--------|------------|-----------|
+| Callers must check is_valid rather than catching an exception | Low | Low | is_valid is more explicit and self-documenting than exception handling | Yes |

docs/branding.md → docs/branding/branding.md

@@ -2,9 +2,9 @@
 
 > *Non-deterministic state machine specification to knead workflows.*
 
-Agents read this file before generating release names, diagrams, README banners, or any document with visual or copy identity. All fields are optional; absent or blank fields fall back to defaults (adjective-grain release names, Mermaid default colors, no wording constraints).
+Agents read this file before generating release names, C4 diagrams, README banners, or any document with visual or copy identity. All fields are optional; absent or blank fields fall back to defaults (adjective-grain release names, Mermaid default colours, no wording constraints).
 
-**Ownership**: The stakeholder owns this file. The designer proposes changes (color palettes, visual assets, wording updates); the stakeholder approves them. No other agent edits this file.
+**Ownership**: The stakeholder owns this file. The design agent proposes changes (colour palettes, visual assets, wording updates); the stakeholder approves them. No other agent edits this file.
 
 ---
 
@@ -18,13 +18,13 @@ Agents read this file before generating release names, diagrams, README banners,
 
 ## Visual
 
-The palette is drawn from flour, wheat, and crust — the transformation from raw grain to structured form. Every colour choice serves legibility first.
+The palette is drawn from flour, wheat, and crust — the transformation from raw grain to structured form. Every colour choice serves legibility first; decoration is secondary.
 
-- **Background/flour:** `#faf8f3` → `#f0ebe3`  — flour white, the canvas for state diagrams
-- **Primary text:** `#3d2b1f` → `#2a1a10`           — dark bran, the grain that carries weight
-- **Accent/crust:** `#c49a3c` → `#daa840`            — golden crust, used for borders, arrows, structural lines — never body text
-- **Secondary/malt:** `#6b8f71` → `#4a7a50`            — malt green, for states, labels, secondary hierarchy
-- **Stone/bran:** `#e8e2d8` → `#c4baa8`               — the structural colour; table borders, diagram dividers
+- **Background/flour:** `#faf8f3` → `#f0ebe3` — flour white, the canvas for state diagrams
+- **Primary text:** `#3d2b1f` → `#2a1a10` — dark bran, the grain that carries weight
+- **Accent/crust:** `#c49a3c` → `#daa840` — golden crust, used for borders, arrows, structural lines — never body text
+- **Secondary/malt:** `#6b8f71` → `#4a7a50` — malt green, for states, labels, secondary hierarchy
+- **Stone/bran:** `#e8e2d8` → `#c4baa8` — the structural colour; table borders, diagram dividers
 - **Logo:** `docs/assets/logo.svg`
 - **Banner:** `docs/assets/banner.svg`