From df4344eda44ee587e2b94a3bcd87c159d15a36e7 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 11:05:19 -0400 Subject: [PATCH 01/28] refactor: clean-slate rebuild of methodology and flow layer Replaces the removed spec-driven/beehave orchestration layer on the refactor/clean-slate branch (old layer preserved in .backup/, recoverable from origin/main). Flow set (.flowr/flows/): - pipeline-flow orchestrates discover -> explore -> plan -> build -> deliver -> shipped - 5 subflows; 21 inner states; one owner and one skill per state - staged-contract surface: test .pyi -> test .py (@pending) -> source .pyi -> simulate - @pytest.mark.pending is the backlog signal and skip mechanism - stubtest (mypy.stubtest) drift-checks source and test .pyi at every gate Methodology (.opencode/): - knowledge/methodology/: separation-of-concerns, agent-files, skill-files, knowledge-files - agents/: 11-agent roster (5 primary owners, 4 specialist doers, 2 consult-only) - skills/: 21 lean per-state procedures (Load step, numbered, IF-THEN/wikilink cues) - knowledge/requirements/interview-techniques.md authored (shared funnel technique) Tooling and CI: - pyproject: PYI added to ruff select; D/pydocstyle dropped (no-docstrings policy); mypy + vcrpy/pytest-vcr dev deps; pending marker registered; stubtest task - .github/workflows/ci.yml: ruff + flowr validate always-on; pyright/stubtest/pytest guarded on package+tests presence (evidence vs enforcement) - conftest.py: pending-marker skip hook - .templates/docs/glossary.md.template: ubiquitous-language glossary skeleton Docs: AGENTS.md rewritten for the new lifecycle; TODO.md tracks open work. --- .flowr/.gitignore | 2 - .flowr/flows/architecture-flow.yaml | 108 --- .flowr/flows/branding-flow.yaml | 78 -- .flowr/flows/define-flow.yaml | 67 -- .flowr/flows/deliver-flow.yaml | 84 +- .flowr/flows/develop-flow.yaml | 140 ---- .flowr/flows/development-flow.yaml | 116 --- .flowr/flows/discovery-flow.yaml | 116 +-- .flowr/flows/explore-flow.yaml | 76 ++ .flowr/flows/pipeline-flow.yaml | 62 ++ .flowr/flows/plan-flow.yaml | 123 +++ .flowr/flows/post-mortem-flow.yaml | 70 -- .flowr/flows/setup-project-flow.yaml | 97 --- .flowr/flows/spec-validation-flow.yaml | 74 -- .flowr/flows/tdd-cycle-flow.yaml | 61 -- .flowr/flows/tdd-flow.yaml | 138 ++++ .github/dependabot.yml | 66 -- .github/workflows/ci.yml | 251 ++---- .github/workflows/dependency-review.yml | 82 -- .github/workflows/pypi-publish.yml | 115 --- .github/workflows/tag-release.yml | 77 -- .gitignore | 6 + .opencode/agents/data-architect.md | 26 + .opencode/agents/design-agent.md | 10 - .opencode/agents/domain-expert.md | 24 +- .opencode/agents/integration-engineer.md | 26 + .opencode/agents/product-owner.md | 24 +- .opencode/agents/release-engineer.md | 26 + .opencode/agents/reviewer.md | 22 +- .opencode/agents/security-engineer.md | 26 + .opencode/agents/setup-agent.md | 10 - .opencode/agents/software-engineer.md | 25 +- .opencode/agents/system-architect.md | 24 +- .opencode/agents/test-architect.md | 26 + .opencode/agents/ux-engineer.md | 26 + .../knowledge/agent-design/principles.md | 95 --- .opencode/knowledge/architecture/adr.md | 80 -- .../knowledge/architecture/assessment.md | 64 -- .../knowledge/architecture/contract-design.md | 72 -- .../architecture/quality-attributes.md | 59 -- .../knowledge/architecture/reconciliation.md | 58 -- .../architecture/technical-design.md | 55 -- .opencode/knowledge/design/color-systems.md | 116 --- .opencode/knowledge/design/identity-design.md | 36 - .opencode/knowledge/design/project-assets.md | 67 -- .opencode/knowledge/design/visual-harmony.md | 81 -- .../domain-modeling/behavioral-contracts.md | 58 -- .../domain-modeling/context-mapping.md | 64 -- .../domain-modeling/event-storming.md | 149 ---- .../knowledge/knowledge-design/principles.md | 123 --- .../knowledge/methodology/agent-files.md | 71 ++ .../knowledge/methodology/knowledge-files.md | 96 +++ .../methodology/separation-of-concerns.md | 71 ++ .../knowledge/methodology/skill-files.md | 67 ++ .../knowledge/requirements/decomposition.md | 86 -- .../requirements/feature-boundaries.md | 69 -- .../requirements/feature-discovery.md | 64 -- .opencode/knowledge/requirements/gherkin.md | 199 ----- .../requirements/interview-techniques.md | 80 +- .opencode/knowledge/requirements/invest.md | 58 -- .opencode/knowledge/requirements/moscow.md | 47 -- .../knowledge/requirements/post-mortem.md | 58 -- .../knowledge/requirements/pre-mortem.md | 79 -- .../requirements/property-patterns.md | 107 --- .../knowledge/requirements/spec-simulation.md | 63 -- .../requirements/ubiquitous-language.md | 79 -- .opencode/knowledge/requirements/wsjf.md | 86 -- .../knowledge/skill-design/principles.md | 110 --- .../knowledge/software-craft/code-review.md | 78 -- .../software-craft/design-patterns.md | 106 --- .../software-craft/external-fixtures.md | 108 --- .../software-craft/git-conventions.md | 93 --- .../software-craft/object-calisthenics.md | 50 -- .../software-craft/refactoring-techniques.md | 137 ---- .../knowledge/software-craft/refactoring.md | 73 -- .../software-craft/smell-catalogue.md | 87 -- .opencode/knowledge/software-craft/solid.md | 57 -- .../knowledge/software-craft/source-stubs.md | 36 - .opencode/knowledge/software-craft/tdd.md | 95 --- .../knowledge/software-craft/test-design.md | 77 -- .../knowledge/software-craft/test-stubs.md | 83 -- .../knowledge/software-craft/versioning.md | 44 -- .../knowledge/workflow/flowr-operations.md | 119 --- .opencode/knowledge/workflow/flowr-spec.md | 221 ------ .../workflow/todo-anchor-protocol.md | 86 -- .../knowledge/writing/ai-language-markers.md | 198 ----- .opencode/skills/accept-feature/SKILL.md | 21 - .opencode/skills/analyze-root-cause/SKILL.md | 11 - .opencode/skills/assess-architecture/SKILL.md | 15 - .opencode/skills/author-test-stubs/SKILL.md | 14 + .../skills/commit-implementation/SKILL.md | 12 - .opencode/skills/conduct-interview/SKILL.md | 17 - .opencode/skills/confirm-red-failure/SKILL.md | 12 + .../skills/consolidate-interview/SKILL.md | 12 + .opencode/skills/create-domain-spec/SKILL.md | 24 - .opencode/skills/create-pr/SKILL.md | 19 - .opencode/skills/create-py-stubs/SKILL.md | 19 - .opencode/skills/decide-batch-action/SKILL.md | 12 - .../define-ubiquitous-language/SKILL.md | 17 - .opencode/skills/derive-source-stubs/SKILL.md | 12 + .opencode/skills/design-assets/SKILL.md | 31 - .opencode/skills/design-colors/SKILL.md | 20 - .../skills/design-technical-solution/SKILL.md | 16 - .../skills/determine-action-items/SKILL.md | 11 - .../skills/document-post-mortem/SKILL.md | 10 - .opencode/skills/draft-adr/SKILL.md | 12 - .opencode/skills/extract-lessons/SKILL.md | 11 - .opencode/skills/fix-spec/SKILL.md | 19 - .opencode/skills/implement-from-stub/SKILL.md | 13 + .opencode/skills/implement-minimum/SKILL.md | 12 - .../skills/interview-cross-cutting/SKILL.md | 11 + .opencode/skills/interview-features/SKILL.md | 12 + .opencode/skills/interview-general/SKILL.md | 12 + .opencode/skills/map-contexts/SKILL.md | 14 - .opencode/skills/merge-local/SKILL.md | 21 - .opencode/skills/merge-to-dev/SKILL.md | 11 + .opencode/skills/polish-code/SKILL.md | 19 - .opencode/skills/publish-release/SKILL.md | 9 + .opencode/skills/record-cassette/SKILL.md | 14 + .opencode/skills/refactor-green/SKILL.md | 12 + .opencode/skills/refactor/SKILL.md | 19 - .opencode/skills/refine-features/SKILL.md | 29 - .opencode/skills/research-provider/SKILL.md | 14 + .opencode/skills/review-architecture/SKILL.md | 22 - .opencode/skills/review-gate/SKILL.md | 35 - .../skills/review-implementation/SKILL.md | 14 + .opencode/skills/review-simulation/SKILL.md | 23 - .opencode/skills/review-spec/SKILL.md | 18 - .opencode/skills/review-test-stubs/SKILL.md | 12 + .opencode/skills/select-build-target/SKILL.md | 13 + .../skills/select-external-target/SKILL.md | 10 + .opencode/skills/select-feature/SKILL.md | 28 - .opencode/skills/setup-apply/SKILL.md | 25 - .opencode/skills/setup-assess/SKILL.md | 30 - .opencode/skills/setup-branding/SKILL.md | 18 - .opencode/skills/setup-configure/SKILL.md | 43 - .opencode/skills/setup-verify/SKILL.md | 24 - .opencode/skills/ship-unit/SKILL.md | 11 + .opencode/skills/simulate-contracts/SKILL.md | 14 + .opencode/skills/simulate-spec/SKILL.md | 29 - .opencode/skills/structure-feature/SKILL.md | 11 - .opencode/skills/verify-traceability/SKILL.md | 11 - .opencode/skills/write-bdd-features/SKILL.md | 32 - .opencode/skills/write-probe/SKILL.md | 12 + .opencode/skills/write-test-py/SKILL.md | 14 + .opencode/skills/write-test/SKILL.md | 16 - .templates/CHANGELOG.md.template | 9 - .templates/TODO.md.template | 21 - .../adr/ADR_YYYYMMDD_.md.template | 41 - .templates/docs/assets/banner.svg.template | 4 - .templates/docs/assets/logo.svg.template | 4 - .templates/docs/branding.md.template | 52 -- .../features/.feature.template | 8 - .templates/docs/glossary.md.template | 14 + .../PM_YYYYMMDD_.md.template | 21 - .../.md.template | 49 -- .templates/docs/spec/domain_spec.md.template | 130 --- .templates/docs/spec/glossary.md.template | 18 - .../docs/spec/product_definition.md.template | 37 - .../features/_test.py.template | 12 - AGENTS.md | 324 +++----- CHANGELOG.md | 287 ------- README.md | 147 ---- TODO.md | 281 +++++++ app/__init__.py | 1 - app/__main__.py | 28 - conftest.py | 7 + docs/adr/.gitkeep | 0 docs/assets/banner.svg | 118 --- docs/assets/logo.svg | 78 -- docs/audit/document-landscape-audit.md | 461 ----------- docs/branding/branding.md | 56 -- docs/features/.gitkeep | 0 docs/features/cli_entrypoint.feature | 32 - docs/index.html | 267 ------- docs/interview-notes/.gitkeep | 0 docs/post-mortem/.gitkeep | 0 ..._20260501_missing-feature-test-template.md | 25 - .../PM_20260501_reviewer-fixing-code.md | 35 - .../ai_writing_markers_community.md | 51 -- .../artificial-intelligence/liu_et_al_2023.md | 45 -- .../pangram_labs_ngrams.md | 46 -- .../scientometrics_delve_2024.md | 46 -- .../textvisualization_corpus.md | 48 -- .../writehuman_2026.md | 49 -- .../design/accessibility/w3c_wcag21_2018.md | 48 -- docs/research/design/visual/airey_2010.md | 48 -- docs/research/design/visual/albers_1963.md | 48 -- docs/research/design/visual/arnheim_1954.md | 48 -- docs/research/design/visual/biederman_1987.md | 48 -- docs/research/design/visual/hicks_2011.md | 47 -- docs/research/design/visual/itten_1961.md | 48 -- docs/research/design/visual/kare_1984.md | 47 -- docs/research/design/visual/lupton_2010.md | 47 -- .../design/visual/muller_brockmann_1981.md | 47 -- docs/research/design/visual/rand_1985.md | 46 -- .../research/design/visual/wertheimer_1923.md | 48 -- .../documentation/procida_2021.md | 45 -- .../domain-modeling/brandolini_2012.md | 45 -- .../domain-modeling/evans_2003.md | 45 -- .../domain-modeling/vernon_2013.md | 45 -- .../cognitive/craik_lockhart_1972.md | 48 -- .../cognitive/fisher_geiselman_1987.md | 47 -- .../psychology/cognitive/flanagan_1954.md | 47 -- .../psychology/cognitive/gollwitzer_1999.md | 48 -- .../cognitive/hattie_timperley_2007.md | 48 -- .../psychology/cognitive/kahneman_2011.md | 47 -- .../psychology/cognitive/klein_1998.md | 47 -- .../cognitive/mcdaniel_einstein_2000.md | 47 -- .../psychology/cognitive/miller_1956.md | 48 -- .../cognitive/reynolds_gutman_1988.md | 46 -- .../cognitive/tversky_kahneman_1974.md | 46 -- .../psychology/social/cialdini_2001.md | 47 -- .../psychology/social/mellers_et_al_2001.md | 46 -- .../psychology/social/rogers_farson_1957.md | 46 -- .../psychology/social/tetlock_1985.md | 45 -- .../architecture/bass_et_al_2021.md | 48 -- .../architecture/boehm_1991.md | 47 -- .../architecture/brown_2018.md | 48 -- .../architecture/cockburn_2005.md | 47 -- .../architecture/conway_1968.md | 47 -- .../architecture/fielding_2000.md | 47 -- .../architecture/fowler_2003.md | 47 -- .../architecture/hohpe_woolf_2003.md | 47 -- .../kazman_klein_clements_2000.md | 47 -- .../architecture/kruchten_1995.md | 47 -- .../architecture/martin_2012_clean.md | 48 -- .../architecture/nygard_2011.md | 48 -- .../architecture/parnas_1972.md | 47 -- .../architecture/skelton_pais_2019.md | 48 -- .../process/beck_1999_yagni.md | 45 -- .../process/beyer_et_al_2016.md | 45 -- .../process/calver_2020.md | 45 -- .../process/clegg_barker_1994.md | 45 -- .../process/fagan_1976.md | 45 -- .../process/nullhack_flowr_1.0.0.md | 63 -- .../process/preston-werner_2013.md | 45 -- .../procedural_checklists_synthesis.md | 52 -- .../process/reinertsen_2009.md | 45 -- .../software-engineering/quality/bay_2008.md | 46 -- .../software-engineering/quality/beck_2002.md | 48 -- .../quality/boehm_1981.md | 48 -- .../quality/demillo_lipton_sayward_1978.md | 45 -- .../quality/feathers_2004.md | 46 -- .../quality/fowler_1999.md | 46 -- .../quality/freeman_pryce_2009.md | 45 -- .../quality/gamma_et_al_1994.md | 46 -- .../quality/google_testing_2013.md | 45 -- .../quality/maciver_2016.md | 47 -- .../quality/martin_2000_solid.md | 47 -- .../quality/martin_2017_first_class_tests.md | 45 -- .../quality/meszaros_2007.md | 46 -- .../quality/north_2006.md | 45 -- .../quality/shvets_2014.md | 46 -- .../quality/wlaschin_2014.md | 50 -- .../requirements/christel_kang_1992.md | 45 -- .../requirements/cohn_2004.md | 45 -- .../requirements/kano_et_al_1984.md | 45 -- .../requirements/patton_2014.md | 46 -- .../requirements/wake_2003.md | 45 -- .../requirements/wynne_2015.md | 45 -- docs/spec/.gitkeep | 0 pyproject.toml | 16 +- template-config.yaml | 113 --- tests/__init__.py | 1 - tests/conftest.py | 35 - tests/features/cli_entrypoint/__init__.py | 1 - tests/unit/__init__.py | 1 - tests/unit/main_test.py | 44 -- uv.lock | 745 ++++++++++-------- 270 files changed, 2248 insertions(+), 12871 deletions(-) delete mode 100644 .flowr/.gitignore delete mode 100644 .flowr/flows/architecture-flow.yaml delete mode 100644 .flowr/flows/branding-flow.yaml delete mode 100644 .flowr/flows/define-flow.yaml delete mode 100644 .flowr/flows/develop-flow.yaml delete mode 100644 .flowr/flows/development-flow.yaml create mode 100644 .flowr/flows/explore-flow.yaml create mode 100644 .flowr/flows/pipeline-flow.yaml create mode 100644 .flowr/flows/plan-flow.yaml delete mode 100644 .flowr/flows/post-mortem-flow.yaml delete mode 100644 .flowr/flows/setup-project-flow.yaml delete mode 100644 .flowr/flows/spec-validation-flow.yaml delete mode 100644 .flowr/flows/tdd-cycle-flow.yaml create mode 100644 .flowr/flows/tdd-flow.yaml delete mode 100644 .github/dependabot.yml delete mode 100644 .github/workflows/dependency-review.yml delete mode 100644 .github/workflows/pypi-publish.yml delete mode 100644 .github/workflows/tag-release.yml create mode 100644 .opencode/agents/data-architect.md delete mode 100644 .opencode/agents/design-agent.md create mode 100644 .opencode/agents/integration-engineer.md create mode 100644 .opencode/agents/release-engineer.md create mode 100644 .opencode/agents/security-engineer.md delete mode 100644 .opencode/agents/setup-agent.md create mode 100644 .opencode/agents/test-architect.md create mode 100644 .opencode/agents/ux-engineer.md delete mode 100644 .opencode/knowledge/agent-design/principles.md delete mode 100644 .opencode/knowledge/architecture/adr.md delete mode 100644 .opencode/knowledge/architecture/assessment.md delete mode 100644 .opencode/knowledge/architecture/contract-design.md delete mode 100644 .opencode/knowledge/architecture/quality-attributes.md delete mode 100644 .opencode/knowledge/architecture/reconciliation.md delete mode 100644 .opencode/knowledge/architecture/technical-design.md delete mode 100644 .opencode/knowledge/design/color-systems.md delete mode 100644 .opencode/knowledge/design/identity-design.md delete mode 100644 .opencode/knowledge/design/project-assets.md delete mode 100644 .opencode/knowledge/design/visual-harmony.md delete mode 100644 .opencode/knowledge/domain-modeling/behavioral-contracts.md delete mode 100644 .opencode/knowledge/domain-modeling/context-mapping.md delete mode 100644 .opencode/knowledge/domain-modeling/event-storming.md delete mode 100644 .opencode/knowledge/knowledge-design/principles.md create mode 100644 .opencode/knowledge/methodology/agent-files.md create mode 100644 .opencode/knowledge/methodology/knowledge-files.md create mode 100644 .opencode/knowledge/methodology/separation-of-concerns.md create mode 100644 .opencode/knowledge/methodology/skill-files.md delete mode 100644 .opencode/knowledge/requirements/decomposition.md delete mode 100644 .opencode/knowledge/requirements/feature-boundaries.md delete mode 100644 .opencode/knowledge/requirements/feature-discovery.md delete mode 100644 .opencode/knowledge/requirements/gherkin.md delete mode 100644 .opencode/knowledge/requirements/invest.md delete mode 100644 .opencode/knowledge/requirements/moscow.md delete mode 100644 .opencode/knowledge/requirements/post-mortem.md delete mode 100644 .opencode/knowledge/requirements/pre-mortem.md delete mode 100644 .opencode/knowledge/requirements/property-patterns.md delete mode 100644 .opencode/knowledge/requirements/spec-simulation.md delete mode 100644 .opencode/knowledge/requirements/ubiquitous-language.md delete mode 100644 .opencode/knowledge/requirements/wsjf.md delete mode 100644 .opencode/knowledge/skill-design/principles.md delete mode 100644 .opencode/knowledge/software-craft/code-review.md delete mode 100644 .opencode/knowledge/software-craft/design-patterns.md delete mode 100644 .opencode/knowledge/software-craft/external-fixtures.md delete mode 100644 .opencode/knowledge/software-craft/git-conventions.md delete mode 100644 .opencode/knowledge/software-craft/object-calisthenics.md delete mode 100644 .opencode/knowledge/software-craft/refactoring-techniques.md delete mode 100644 .opencode/knowledge/software-craft/refactoring.md delete mode 100644 .opencode/knowledge/software-craft/smell-catalogue.md delete mode 100644 .opencode/knowledge/software-craft/solid.md delete mode 100644 .opencode/knowledge/software-craft/source-stubs.md delete mode 100644 .opencode/knowledge/software-craft/tdd.md delete mode 100644 .opencode/knowledge/software-craft/test-design.md delete mode 100644 .opencode/knowledge/software-craft/test-stubs.md delete mode 100644 .opencode/knowledge/software-craft/versioning.md delete mode 100644 .opencode/knowledge/workflow/flowr-operations.md delete mode 100644 .opencode/knowledge/workflow/flowr-spec.md delete mode 100644 .opencode/knowledge/workflow/todo-anchor-protocol.md delete mode 100644 .opencode/knowledge/writing/ai-language-markers.md delete mode 100644 .opencode/skills/accept-feature/SKILL.md delete mode 100644 .opencode/skills/analyze-root-cause/SKILL.md delete mode 100644 .opencode/skills/assess-architecture/SKILL.md create mode 100644 .opencode/skills/author-test-stubs/SKILL.md delete mode 100644 .opencode/skills/commit-implementation/SKILL.md delete mode 100644 .opencode/skills/conduct-interview/SKILL.md create mode 100644 .opencode/skills/confirm-red-failure/SKILL.md create mode 100644 .opencode/skills/consolidate-interview/SKILL.md delete mode 100644 .opencode/skills/create-domain-spec/SKILL.md delete mode 100644 .opencode/skills/create-pr/SKILL.md delete mode 100644 .opencode/skills/create-py-stubs/SKILL.md delete mode 100644 .opencode/skills/decide-batch-action/SKILL.md delete mode 100644 .opencode/skills/define-ubiquitous-language/SKILL.md create mode 100644 .opencode/skills/derive-source-stubs/SKILL.md delete mode 100644 .opencode/skills/design-assets/SKILL.md delete mode 100644 .opencode/skills/design-colors/SKILL.md delete mode 100644 .opencode/skills/design-technical-solution/SKILL.md delete mode 100644 .opencode/skills/determine-action-items/SKILL.md delete mode 100644 .opencode/skills/document-post-mortem/SKILL.md delete mode 100644 .opencode/skills/draft-adr/SKILL.md delete mode 100644 .opencode/skills/extract-lessons/SKILL.md delete mode 100644 .opencode/skills/fix-spec/SKILL.md create mode 100644 .opencode/skills/implement-from-stub/SKILL.md delete mode 100644 .opencode/skills/implement-minimum/SKILL.md create mode 100644 .opencode/skills/interview-cross-cutting/SKILL.md create mode 100644 .opencode/skills/interview-features/SKILL.md create mode 100644 .opencode/skills/interview-general/SKILL.md delete mode 100644 .opencode/skills/map-contexts/SKILL.md delete mode 100644 .opencode/skills/merge-local/SKILL.md create mode 100644 .opencode/skills/merge-to-dev/SKILL.md delete mode 100644 .opencode/skills/polish-code/SKILL.md create mode 100644 .opencode/skills/publish-release/SKILL.md create mode 100644 .opencode/skills/record-cassette/SKILL.md create mode 100644 .opencode/skills/refactor-green/SKILL.md delete mode 100644 .opencode/skills/refactor/SKILL.md delete mode 100644 .opencode/skills/refine-features/SKILL.md create mode 100644 .opencode/skills/research-provider/SKILL.md delete mode 100644 .opencode/skills/review-architecture/SKILL.md delete mode 100644 .opencode/skills/review-gate/SKILL.md create mode 100644 .opencode/skills/review-implementation/SKILL.md delete mode 100644 .opencode/skills/review-simulation/SKILL.md delete mode 100644 .opencode/skills/review-spec/SKILL.md create mode 100644 .opencode/skills/review-test-stubs/SKILL.md create mode 100644 .opencode/skills/select-build-target/SKILL.md create mode 100644 .opencode/skills/select-external-target/SKILL.md delete mode 100644 .opencode/skills/select-feature/SKILL.md delete mode 100644 .opencode/skills/setup-apply/SKILL.md delete mode 100644 .opencode/skills/setup-assess/SKILL.md delete mode 100644 .opencode/skills/setup-branding/SKILL.md delete mode 100644 .opencode/skills/setup-configure/SKILL.md delete mode 100644 .opencode/skills/setup-verify/SKILL.md create mode 100644 .opencode/skills/ship-unit/SKILL.md create mode 100644 .opencode/skills/simulate-contracts/SKILL.md delete mode 100644 .opencode/skills/simulate-spec/SKILL.md delete mode 100644 .opencode/skills/structure-feature/SKILL.md delete mode 100644 .opencode/skills/verify-traceability/SKILL.md delete mode 100644 .opencode/skills/write-bdd-features/SKILL.md create mode 100644 .opencode/skills/write-probe/SKILL.md create mode 100644 .opencode/skills/write-test-py/SKILL.md delete mode 100644 .opencode/skills/write-test/SKILL.md delete mode 100644 .templates/CHANGELOG.md.template delete mode 100644 .templates/TODO.md.template delete mode 100644 .templates/docs/adr/ADR_YYYYMMDD_.md.template delete mode 100644 .templates/docs/assets/banner.svg.template delete mode 100644 .templates/docs/assets/logo.svg.template delete mode 100644 .templates/docs/branding.md.template delete mode 100644 .templates/docs/features/.feature.template create mode 100644 .templates/docs/glossary.md.template delete mode 100644 .templates/docs/post-mortem/PM_YYYYMMDD_.md.template delete mode 100644 .templates/docs/research///.md.template delete mode 100644 .templates/docs/spec/domain_spec.md.template delete mode 100644 .templates/docs/spec/glossary.md.template delete mode 100644 .templates/docs/spec/product_definition.md.template delete mode 100644 .templates/tests/features/_test.py.template delete mode 100644 CHANGELOG.md delete mode 100644 README.md create mode 100644 TODO.md delete mode 100644 app/__init__.py delete mode 100644 app/__main__.py create mode 100644 conftest.py delete mode 100644 docs/adr/.gitkeep delete mode 100644 docs/assets/banner.svg delete mode 100644 docs/assets/logo.svg delete mode 100644 docs/audit/document-landscape-audit.md delete mode 100644 docs/branding/branding.md delete mode 100644 docs/features/.gitkeep delete mode 100644 docs/features/cli_entrypoint.feature delete mode 100644 docs/index.html delete mode 100644 docs/interview-notes/.gitkeep delete mode 100644 docs/post-mortem/.gitkeep delete mode 100644 docs/post-mortem/PM_20260501_missing-feature-test-template.md delete mode 100644 docs/post-mortem/PM_20260501_reviewer-fixing-code.md delete mode 100644 docs/research/computer-science/artificial-intelligence/ai_writing_markers_community.md delete mode 100644 docs/research/computer-science/artificial-intelligence/liu_et_al_2023.md delete mode 100644 docs/research/computer-science/artificial-intelligence/pangram_labs_ngrams.md delete mode 100644 docs/research/computer-science/artificial-intelligence/scientometrics_delve_2024.md delete mode 100644 docs/research/computer-science/artificial-intelligence/textvisualization_corpus.md delete mode 100644 docs/research/computer-science/artificial-intelligence/writehuman_2026.md delete mode 100644 docs/research/design/accessibility/w3c_wcag21_2018.md delete mode 100644 docs/research/design/visual/airey_2010.md delete mode 100644 docs/research/design/visual/albers_1963.md delete mode 100644 docs/research/design/visual/arnheim_1954.md delete mode 100644 docs/research/design/visual/biederman_1987.md delete mode 100644 docs/research/design/visual/hicks_2011.md delete mode 100644 docs/research/design/visual/itten_1961.md delete mode 100644 docs/research/design/visual/kare_1984.md delete mode 100644 docs/research/design/visual/lupton_2010.md delete mode 100644 docs/research/design/visual/muller_brockmann_1981.md delete mode 100644 docs/research/design/visual/rand_1985.md delete mode 100644 docs/research/design/visual/wertheimer_1923.md delete mode 100644 docs/research/information-science/documentation/procida_2021.md delete mode 100644 docs/research/information-science/domain-modeling/brandolini_2012.md delete mode 100644 docs/research/information-science/domain-modeling/evans_2003.md delete mode 100644 docs/research/information-science/domain-modeling/vernon_2013.md delete mode 100644 docs/research/psychology/cognitive/craik_lockhart_1972.md delete mode 100644 docs/research/psychology/cognitive/fisher_geiselman_1987.md delete mode 100644 docs/research/psychology/cognitive/flanagan_1954.md delete mode 100644 docs/research/psychology/cognitive/gollwitzer_1999.md delete mode 100644 docs/research/psychology/cognitive/hattie_timperley_2007.md delete mode 100644 docs/research/psychology/cognitive/kahneman_2011.md delete mode 100644 docs/research/psychology/cognitive/klein_1998.md delete mode 100644 docs/research/psychology/cognitive/mcdaniel_einstein_2000.md delete mode 100644 docs/research/psychology/cognitive/miller_1956.md delete mode 100644 docs/research/psychology/cognitive/reynolds_gutman_1988.md delete mode 100644 docs/research/psychology/cognitive/tversky_kahneman_1974.md delete mode 100644 docs/research/psychology/social/cialdini_2001.md delete mode 100644 docs/research/psychology/social/mellers_et_al_2001.md delete mode 100644 docs/research/psychology/social/rogers_farson_1957.md delete mode 100644 docs/research/psychology/social/tetlock_1985.md delete mode 100644 docs/research/software-engineering/architecture/bass_et_al_2021.md delete mode 100644 docs/research/software-engineering/architecture/boehm_1991.md delete mode 100644 docs/research/software-engineering/architecture/brown_2018.md delete mode 100644 docs/research/software-engineering/architecture/cockburn_2005.md delete mode 100644 docs/research/software-engineering/architecture/conway_1968.md delete mode 100644 docs/research/software-engineering/architecture/fielding_2000.md delete mode 100644 docs/research/software-engineering/architecture/fowler_2003.md delete mode 100644 docs/research/software-engineering/architecture/hohpe_woolf_2003.md delete mode 100644 docs/research/software-engineering/architecture/kazman_klein_clements_2000.md delete mode 100644 docs/research/software-engineering/architecture/kruchten_1995.md delete mode 100644 docs/research/software-engineering/architecture/martin_2012_clean.md delete mode 100644 docs/research/software-engineering/architecture/nygard_2011.md delete mode 100644 docs/research/software-engineering/architecture/parnas_1972.md delete mode 100644 docs/research/software-engineering/architecture/skelton_pais_2019.md delete mode 100644 docs/research/software-engineering/process/beck_1999_yagni.md delete mode 100644 docs/research/software-engineering/process/beyer_et_al_2016.md delete mode 100644 docs/research/software-engineering/process/calver_2020.md delete mode 100644 docs/research/software-engineering/process/clegg_barker_1994.md delete mode 100644 docs/research/software-engineering/process/fagan_1976.md delete mode 100644 docs/research/software-engineering/process/nullhack_flowr_1.0.0.md delete mode 100644 docs/research/software-engineering/process/preston-werner_2013.md delete mode 100644 docs/research/software-engineering/process/procedural_checklists_synthesis.md delete mode 100644 docs/research/software-engineering/process/reinertsen_2009.md delete mode 100644 docs/research/software-engineering/quality/bay_2008.md delete mode 100644 docs/research/software-engineering/quality/beck_2002.md delete mode 100644 docs/research/software-engineering/quality/boehm_1981.md delete mode 100644 docs/research/software-engineering/quality/demillo_lipton_sayward_1978.md delete mode 100644 docs/research/software-engineering/quality/feathers_2004.md delete mode 100644 docs/research/software-engineering/quality/fowler_1999.md delete mode 100644 docs/research/software-engineering/quality/freeman_pryce_2009.md delete mode 100644 docs/research/software-engineering/quality/gamma_et_al_1994.md delete mode 100644 docs/research/software-engineering/quality/google_testing_2013.md delete mode 100644 docs/research/software-engineering/quality/maciver_2016.md delete mode 100644 docs/research/software-engineering/quality/martin_2000_solid.md delete mode 100644 docs/research/software-engineering/quality/martin_2017_first_class_tests.md delete mode 100644 docs/research/software-engineering/quality/meszaros_2007.md delete mode 100644 docs/research/software-engineering/quality/north_2006.md delete mode 100644 docs/research/software-engineering/quality/shvets_2014.md delete mode 100644 docs/research/software-engineering/quality/wlaschin_2014.md delete mode 100644 docs/research/software-engineering/requirements/christel_kang_1992.md delete mode 100644 docs/research/software-engineering/requirements/cohn_2004.md delete mode 100644 docs/research/software-engineering/requirements/kano_et_al_1984.md delete mode 100644 docs/research/software-engineering/requirements/patton_2014.md delete mode 100644 docs/research/software-engineering/requirements/wake_2003.md delete mode 100644 docs/research/software-engineering/requirements/wynne_2015.md delete mode 100644 docs/spec/.gitkeep delete mode 100644 template-config.yaml delete mode 100644 tests/__init__.py delete mode 100644 tests/conftest.py delete mode 100644 tests/features/cli_entrypoint/__init__.py delete mode 100644 tests/unit/__init__.py delete mode 100644 tests/unit/main_test.py diff --git a/.flowr/.gitignore b/.flowr/.gitignore deleted file mode 100644 index 7275442a..00000000 --- a/.flowr/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# Ignore SVG files (regeneratable from mermaid) -*.svg \ No newline at end of file diff --git a/.flowr/flows/architecture-flow.yaml b/.flowr/flows/architecture-flow.yaml deleted file mode 100644 index fb7432e5..00000000 --- a/.flowr/flows/architecture-flow.yaml +++ /dev/null @@ -1,108 +0,0 @@ -flow: architecture-flow -version: 10.0.0 -exits: - - complete - - needs-discovery - -states: - - id: architecture-assessment - attrs: - description: "SA evaluates whether the feature requires new architecture or fits the existing system, potentially overriding deployment decisions" - owner: SA - git: dev - skills: - - assess-architecture - in: - - product_definition.md - - domain_spec.md - out: - - product_definition.md: - - deployment - - quality_attributes - conditions: - architecture-complete: - architecture-complete: ==verified - architecture-exists: - domain-spec-md: ==exists - no-architecture-exists: - domain-spec-md: ==missing - next: - no-architecture-needed: - to: complete - when: architecture-complete - needs-context-update: - to: context-mapping - when: architecture-exists - greenfield: - to: context-mapping - when: no-architecture-exists - delivery-mismatch-unresolvable: needs-discovery - needs-discovery: needs-discovery - - - id: context-mapping - attrs: - description: "SA maps bounded context relationships, Vernon patterns, and anti-corruption layers" - owner: SA - git: dev - skills: - - map-contexts - in: - - domain_spec.md - - product_definition.md - - glossary.md - out: - - domain_spec.md: - - context_map - - integration_points - next: - done: technical-design - needs-discovery: needs-discovery - - - id: technical-design - attrs: - description: "SA selects technology stack, documents dependencies, and drafts ADRs for architectural decisions" - owner: SA - git: dev - skills: - - design-technical-solution - - draft-adr - in: - - domain_spec.md - - glossary.md - - product_definition.md - - "adr/*.md" # optional — visibility into prior ADRs before creating new ones - out: - - product_definition.md: - - technology_stack - - dependencies - - adr/.md - next: - done: review-signoff - - - id: review-signoff - attrs: - description: "R independently verifies architecture alignment with domain spec and requirements, and cross-document consistency, before implementation begins" - owner: R - git: dev - skills: - - review-architecture - in: - - "adr/.md" # optional - - product_definition.md - - domain_spec.md - - glossary.md - out: [] - conditions: - architecture-approved: - alignment: ==domain-spec-verified - adr-compliance: ==adrs-respected - committed-to-dev-locally: - committed-to-dev-locally: ==verified - next: - approved: - to: complete - when: - - architecture-approved - - committed-to-dev-locally - inconsistent: architecture-assessment - needs-discovery: needs-discovery diff --git a/.flowr/flows/branding-flow.yaml b/.flowr/flows/branding-flow.yaml deleted file mode 100644 index 52338da8..00000000 --- a/.flowr/flows/branding-flow.yaml +++ /dev/null @@ -1,78 +0,0 @@ -flow: branding-flow -version: 4.0.0 -exits: - - branded - - cancelled - -states: - - id: setup-branding - attrs: - description: "Interview stakeholder to establish brand identity: personality, visual metaphor, wording, and release naming" - owner: Design Agent - git: dev - skills: - - setup-branding - in: [] - out: - - branding.md: - - identity - - release_naming - - wording - next: - confirmed: design-colors - cancelled: cancelled - - - id: design-colors - attrs: - description: "Select and validate a colour palette with WCAG contrast, dark-mode counterparts, and hue semantics" - owner: Design Agent - git: dev - skills: - - design-colors - in: - - branding.md - out: - - branding.md: - - visual - next: - approved: design-assets - revise: design-colors - cancelled: cancelled - - - id: design-assets - attrs: - description: "Create logo and banner using favicon-first, monochrome-first, progressive-simplification process" - owner: Design Agent - git: dev - skills: - - design-assets - in: - - branding.md - out: - - docs/assets/logo.svg - - docs/assets/logo-dark.svg - - docs/assets/banner.svg - - docs/assets/favicon.ico - - docs/assets/icon.svg - - docs/assets/apple-touch-icon.png - - docs/assets/icon-192.png - - docs/assets/icon-512.png - conditions: - monochrome-passed: - logo-monochrome: ==passes - scalability-passed: - logo-scalability: ==passes - blur-passed: - logo-blur-test: ==passes - assets-committed: - committed-to-dev-locally: ==verified - next: - approved: - to: branded - when: - - monochrome-passed - - scalability-passed - - blur-passed - - assets-committed - revise: design-assets - cancelled: cancelled diff --git a/.flowr/flows/define-flow.yaml b/.flowr/flows/define-flow.yaml deleted file mode 100644 index 612f26d0..00000000 --- a/.flowr/flows/define-flow.yaml +++ /dev/null @@ -1,67 +0,0 @@ -flow: define-flow -version: 2.0.0 -params: [feature_title] -exits: - - validated - -states: - - id: discovery - attrs: - description: "Interview stakeholders and create structural domain specification" - git: dev - flow: discovery-flow - flow-version: "^12" - next: - complete: spec-validation - - - id: spec-validation - attrs: - description: "Iteratively simulate domain spec, discover rules and pain points, fix until clean" - git: dev - flow: spec-validation-flow - flow-version: "^2" - next: - validated: architecture - needs-reinterview: discovery - - - id: refine-features - attrs: - description: "PO transforms simulation-created context-level .feature files into final feature-level files with stable titles, descriptions, rules, and constraints" - owner: PO - git: dev - skills: - - refine-features - in: - - product_definition.md - - domain_spec.md - - glossary.md - - "features/*.feature" - out: - - "features/.feature": - - feature_header - - constraints - - rules - conditions: - features-refined: - features-discovered: ==verified - invest-validated: - invest-passed: ==verified - committed-to-dev-locally: - committed-to-dev-locally: ==verified - next: - done: - to: validated - when: - - features-refined - - invest-validated - - committed-to-dev-locally - - - id: architecture - attrs: - description: "Design technical architecture, context boundaries, and API contracts — skippable if no architecture changes are needed" - git: dev - flow: architecture-flow - flow-version: "^10" - next: - complete: refine-features - needs-discovery: discovery \ No newline at end of file diff --git a/.flowr/flows/deliver-flow.yaml b/.flowr/flows/deliver-flow.yaml index d6f791e2..13b97fea 100644 --- a/.flowr/flows/deliver-flow.yaml +++ b/.flowr/flows/deliver-flow.yaml @@ -1,61 +1,39 @@ flow: deliver-flow -version: 1.0.0 -params: [feature_title] +version: 1.3.0 exits: - - published - - accumulate - - cancelled - - needs-development - + - delivered states: - - id: local-merge - attrs: - description: "SE squash-merges feature commits into local dev branch and resolves any conflicts" - owner: SE - git: dev - skills: - - merge-local - in: - - ".cache/acceptance/.md" - - features/.feature - out: - - merged-commits - next: - merged: publish-decision - conflict: needs-development - - - id: publish-decision + - id: merge attrs: - description: "PO decides whether to publish the accumulated batch as a PR or continue accumulating features on local dev" - owner: PO - git: dev - skills: - - decide-batch-action - in: - - merged-commits - out: [] - next: - accumulate: accumulate - publish: pr-creation - - - id: pr-creation - attrs: - description: "SE creates an administrative PR for changes already on local dev" - owner: SE - git: dev - skills: - - create-pr - in: - - merged-commits - - features/.feature - out: [] + description: > + Squash-merge the feature commits into dev with the full suite and + whole-suite stubtest green on dev. + dispatch_to: release-engineer + git branch: dev + skills: [merge-to-dev] + input artifacts: + - "feature-commits" + output artifacts: + - "dev" conditions: merged: - ci-passes: ==verified - no-changes-requested: ==verified + tests-green-on-dev: "==true" + stubtest-clean-on-dev: "==true" next: - approved: - to: published + merged: + to: publish when: merged - changes-requested: needs-development - cancelled: cancelled + + - id: publish + attrs: + description: > + Publish the batch as release notes, a PR to main, or a tagged release. + dispatch_to: release-engineer + git branch: dev + skills: [publish-release] + input artifacts: + - "dev" + output artifacts: + - "release" + next: + published: delivered diff --git a/.flowr/flows/develop-flow.yaml b/.flowr/flows/develop-flow.yaml deleted file mode 100644 index 0c8d6986..00000000 --- a/.flowr/flows/develop-flow.yaml +++ /dev/null @@ -1,140 +0,0 @@ -flow: develop-flow -version: 2.0.0 -params: [feature_title] -exits: - - completed - - needs-architecture - -states: - - id: feature-selection - attrs: - description: "PO selects the next feature — by dependency count then WSJF" - owner: PO - git: dev - skills: - - select-feature - in: - - product_definition.md - - domain_spec.md - - "features/.feature" - out: [] - next: - selected: feature-examples - needs-architecture: needs-architecture - no-features: completed - - - id: feature-examples - attrs: - description: "PO converts rules to Example and Scenario Outline blocks with pre-mortem analysis" - owner: PO - git: dev - skills: - - write-bdd-features - in: - - features/.feature - - product_definition.md - - domain_spec.md - - glossary.md - out: - - features/.feature: - - examples - conditions: - examples-complete: - examples-complete: ==verified - next: - done: - to: spec-review - when: examples-complete - - - id: spec-review - attrs: - description: "R independently verifies the feature spec for cross-document consistency, domain alignment, BDD quality, and pre-mortem coverage" - owner: R - git: dev - skills: - - review-spec - in: - - features/.feature - - product_definition.md - - domain_spec.md - - glossary.md - out: [] - conditions: - spec-verified: - spec-verified: ==verified - next: - done: - to: development - when: spec-verified - fail: feature-examples - - - id: development - attrs: - description: "Implement the feature through TDD cycles, review, and commit" - git: feature - flow: development-flow - flow-version: "^13" - next: - done: acceptance - - - id: acceptance - attrs: - description: "PO validates business behavior against BDD examples and quality attributes" - owner: PO - git: feature - skills: - - accept-feature - - verify-traceability - in: - - features/.feature - - product_definition.md - - domain_spec.md - - glossary.md - - ".cache/interview-notes/*.md" - out: - - ".cache/acceptance/.md" - conditions: - feature-accepted: - acceptance-verified: ==verified - next: - approved: - to: polish - when: feature-accepted - rejected: development - - - id: polish - attrs: - description: "SE applies full project conventions — naming, docstrings, formatting, type annotations — after feature acceptance" - owner: SE - git: feature - skills: - - polish-code - in: - - source-implementations - - test-implementations - - features/.feature - out: - - polished-source - next: - polished: commit-polished - - - id: commit-polished - attrs: - description: "SE commits polished code to the feature branch with traceability" - owner: SE - git: feature - skills: - - commit-implementation - in: - - polished-source - - test-implementations - - features/.feature - out: - - feature-commits - conditions: - committed: - committed: ==verified - next: - done: - to: completed - when: committed \ No newline at end of file diff --git a/.flowr/flows/development-flow.yaml b/.flowr/flows/development-flow.yaml deleted file mode 100644 index e2e960ed..00000000 --- a/.flowr/flows/development-flow.yaml +++ /dev/null @@ -1,116 +0,0 @@ -flow: development-flow -version: 13.0.0 -params: [feature_title] -exits: - - done - -states: - - id: feature-structuring - attrs: - description: "SA creates the feature branch and feature-level structure — package directories, port interfaces, aggregate root signatures — before stubs are generated" - owner: SA - git: feature - skills: - - structure-feature - in: - - features/.feature - - domain_spec.md - - glossary.md - - product_definition.md - out: - - git_branch - next: - ready: create-py-stubs - - - id: create-py-stubs - attrs: - description: "SA creates typed source stubs and generates test stubs via pytest-beehave, then verifies all planning artifacts are complete for baseline" - owner: SA - git: feature - skills: - - create-py-stubs - in: - - features/.feature - - domain_spec.md - - glossary.md - - product_definition.md - out: - - typed-source-stubs - - test-skeletons - conditions: - stubs-traceable: - beehave-check-passes: ==verified - baseline-confirmed: - baseline-confirmed: ==verified - committed: - committed: ==verified - next: - done: - to: tdd-cycle - when: - - stubs-traceable - - baseline-confirmed - - committed - - - id: tdd-cycle - attrs: - description: "SE implements the feature through repeated RED-GREEN-REFACTOR cycles until all BDD examples pass" - git: feature - flow: tdd-cycle-flow - flow-version: "^8" - conditions: - design-declared: - yagni: ==no-premature-abstractions - kiss: ==simplest-solution - dry: ==no-duplicated-logic - objcal: ==calisthenics-followed - smells: ==all-smells-addressed - solid: ==principles-applied - patterns: ==patterns-justified - traceability-verified: - beehave-check: ==passed - next: - all-green: - to: review-gate - when: - - design-declared - - traceability-verified - - - id: review-gate - attrs: - description: "R independently verifies implementation across two tiers — design, structure — with traceability verified by beehave check" - owner: R - git: feature - skills: - - review-gate - in: - - test-implementations - - source-implementations - - features/.feature - - domain_spec.md - - "adr/*.md" # optional - out: [] - next: - pass: commit-reviewed - fail: tdd-cycle - - - id: commit-reviewed - attrs: - description: "SE commits the passing implementation with traceability to Example titles" - owner: SE - git: feature - skills: - - commit-implementation - in: - - source-implementations - - test-implementations - - features/.feature - out: - - feature-commits - conditions: - committed: - committed: ==verified - next: - done: - to: done - when: committed \ No newline at end of file diff --git a/.flowr/flows/discovery-flow.yaml b/.flowr/flows/discovery-flow.yaml index 93660855..01fb64cd 100644 --- a/.flowr/flows/discovery-flow.yaml +++ b/.flowr/flows/discovery-flow.yaml @@ -1,62 +1,70 @@ flow: discovery-flow -version: 12.0.0 +version: 2.1.0 exits: - - complete - + - interview-ready states: - - id: stakeholder-interview + - id: interview-general + attrs: + description: > + Funnel level 1 - General. Establish the big picture with the seven broad + questions; begin the running interview-notes artifact. + dispatch_to: product-owner + specialists: [domain-expert] + git branch: dev + skills: [interview-general] + output artifacts: + - ".cache//interview-notes.md" + next: + general-done: interview-cross-cutting + + - id: interview-cross-cutting + attrs: + description: > + Funnel level 2 - Cross-cutting. Structure the domain (behaviour groups, + bounded contexts, integration points, lifecycle); append to the + interview-notes. + dispatch_to: product-owner + specialists: [domain-expert] + git branch: dev + skills: [interview-cross-cutting] + input artifacts: + - ".cache//interview-notes.md" + output artifacts: + - ".cache//interview-notes.md" + next: + cross-cutting-done: interview-features + + - id: interview-features attrs: - description: "PO interviews stakeholders to understand pain points, business goals, and domain terms" - owner: PO - git: dev - skills: - - conduct-interview - in: - - ".cache/interview-notes/*.md" # optional - - "domain_spec.md" # optional — for re-interview context - - "product_definition.md" # optional — for re-interview context - out: - - ".cache/interview-notes/.md" + description: > + Funnel level 3 - Feature identification. Capture feature NAMES and rough + boundaries only; run gap analysis; append to the interview-notes. + dispatch_to: product-owner + specialists: [domain-expert] + git branch: dev + skills: [interview-features] + input artifacts: + - ".cache//interview-notes.md" + output artifacts: + - ".cache//interview-notes.md" next: - needs-spec: spec-creation - already-known: complete + features-identified: consolidate-interview - - id: spec-creation + - id: consolidate-interview attrs: - description: "SA and DE create a structural domain specification per bounded context from interview notes" - owner: SA - git: dev - skills: - - create-domain-spec - - define-ubiquitous-language - in: - - .cache/interview-notes/*.md - - "domain_spec.md" # optional — cumulative edit across iterations - - "glossary.md" # optional — cumulative edit across iterations - - "product_definition.md" # optional — cumulative edit across iterations - out: - - product_definition.md: - - what_is - - what_is_not - - why - - users - - out_of_scope - - quality_attributes - - domain_spec.md: - - context_map - - context - - entities - - relationships - - aggregate_boundaries - - data_shapes - - integration_points - - external_contracts - - glossary.md - conditions: - committed-to-dev-locally: - committed-to-dev-locally: ==verified + description: > + Active listening L3. Synthesize all three levels into the final notes + for stakeholder approval and author the glossary; the accuracy gate for + plan. + dispatch_to: product-owner + specialists: [domain-expert] + git branch: dev + skills: [consolidate-interview] + input artifacts: + - ".cache//interview-notes.md" + output artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" next: - done: - to: complete - when: committed-to-dev-locally - needs-reinterview: stakeholder-interview + consolidated: interview-ready + needs-more-elicitation: interview-general diff --git a/.flowr/flows/explore-flow.yaml b/.flowr/flows/explore-flow.yaml new file mode 100644 index 00000000..b6cba00e --- /dev/null +++ b/.flowr/flows/explore-flow.yaml @@ -0,0 +1,76 @@ +flow: explore-flow +version: 1.4.0 +exits: + - explored-ready + - needs-elicitation +states: + - id: select-external-target + attrs: + description: > + Pick the next un-probed external service (one per pass) and record it as + the handoff; pass through when none remain. + dispatch_to: integration-engineer + git branch: dev + skills: [select-external-target] + input artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" + - "tests/cassettes/**" + output artifacts: + - ".cache//probe-target.md" + next: + next-selected: research-provider + all-probed: explored-ready + + - id: research-provider + attrs: + description: > + Ground the one selected service in its real behaviour by reading the + provider's docs and determining its access shape, before any probe code. + dispatch_to: integration-engineer + specialists: [data-architect, security-engineer, ux-engineer, domain-expert] + git branch: dev + skills: [research-provider] + input artifacts: + - ".cache//probe-target.md" + - ".cache//interview-notes.md" + - "docs/glossary.md" + output artifacts: + - ".cache//probe-research.md" + next: + researched: write-probe + mismatch: needs-elicitation + + - id: write-probe + attrs: + description: > + Author the minimal throwaway probe script (one success + one error + path) from the researched access shape; do not execute it. + dispatch_to: integration-engineer + git branch: dev + skills: [write-probe] + input artifacts: + - ".cache//probe-research.md" + output artifacts: + - "explore/**" + next: + probe-written: record-cassette + + - id: record-cassette + attrs: + description: > + Execute the probe, record the real exchange as a scrubbed committed + cassette, and append the external-contracts notes. + dispatch_to: integration-engineer + specialists: [security-engineer] + git branch: dev + skills: [record-cassette] + input artifacts: + - ".cache//probe-research.md" + - "explore/**" + output artifacts: + - "tests/cassettes/**" + - ".cache//external-contracts.md" + next: + captured: select-external-target + mismatch: needs-elicitation diff --git a/.flowr/flows/pipeline-flow.yaml b/.flowr/flows/pipeline-flow.yaml new file mode 100644 index 00000000..556efd35 --- /dev/null +++ b/.flowr/flows/pipeline-flow.yaml @@ -0,0 +1,62 @@ +flow: pipeline-flow +version: 2.1.0 +exits: + - shipped +states: + - id: discover + attrs: + description: > + Run the interview funnel (general -> cross-cutting -> features -> + consolidate) to elicit requirements and author the glossary. Emits + interview notes and glossary only - no tests, source, or external + contracts. + flow: discovery-flow + flow-version: "^2" + next: + interview-ready: explore + + - id: explore + attrs: + description: > + Ground every external service named in the interview in reality: read + docs, run minimal probes, record real exchanges as committed cassettes. + Passes through when there are no external services. + flow: explore-flow + flow-version: "^1" + next: + explored-ready: plan + needs-elicitation: discover + + - id: plan + attrs: + description: > + Turn the interview and captured reality into the gated contract + surface: test .pyi -> test .py (@pending) -> source .pyi -> simulate. + No source .py written here. + flow: plan-flow + flow-version: "^1" + next: + contracts-ready: build + needs-elicitation: discover + + - id: build + attrs: + description: > + Turn the pending-test backlog into shipped code, one source contract per + cycle (select -> red -> green -> refactor -> review -> ship). Tests are + already written by plan. + flow: tdd-flow + flow-version: "^2" + next: + all-built: deliver + needs-contracts: plan + + - id: deliver + attrs: + description: > + Squash-merge the feature commits into dev with the full suite green, + then publish (notes / PR / tag). + flow: deliver-flow + flow-version: "^1" + next: + delivered: shipped diff --git a/.flowr/flows/plan-flow.yaml b/.flowr/flows/plan-flow.yaml new file mode 100644 index 00000000..0eb300db --- /dev/null +++ b/.flowr/flows/plan-flow.yaml @@ -0,0 +1,123 @@ +flow: plan-flow +version: 1.4.0 +exits: + - contracts-ready + - needs-elicitation +states: + - id: author-test-stubs + attrs: + description: > + Author the test .pyi (integration + E2E only) from the interview and + captured reality - the first contract surface. + dispatch_to: test-architect + specialists: [integration-engineer, data-architect, ux-engineer, domain-expert, security-engineer] + git branch: dev + skills: [author-test-stubs] + input artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" + - "tests/cassettes/**" + - ".cache//external-contracts.md" + output artifacts: + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + - "docs/glossary.md" + next: + test-stubs-authored: review-test-stubs + + - id: review-test-stubs + attrs: + description: > + Gate. Review the test stubs for consistency, scope (integration/E2E + only), and happy-path completeness against the interview. + dispatch_to: reviewer + git branch: dev + skills: [review-test-stubs] + input artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" + - "tests/cassettes/**" + - ".cache//external-contracts.md" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: [] + conditions: + accepted: + interview-consistent: "==true" + scope-integration-e2e-only: "==true" + happy-paths-complete: "==true" + next: + accepted: + to: write-test-py + when: accepted + needs-stubs-rework: author-test-stubs + + - id: write-test-py + attrs: + description: > + Write the test .py bodies under the code-quality gate; mark each + @pytest.mark.pending so the suite stays green-with-skips. + dispatch_to: test-architect + specialists: [integration-engineer, data-architect, ux-engineer] + git branch: dev + skills: [write-test-py] + input artifacts: + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + - "tests/cassettes/**" + - ".cache//external-contracts.md" + output artifacts: + - "tests/integration/**/*_test.py" + - "tests/e2e/**/*_test.py" + next: + test-py-written: derive-source-stubs + + - id: derive-source-stubs + attrs: + description: > + Derive /**/*.pyi from the reviewed test .py - every type the + tests reference gets a definition. + dispatch_to: system-architect + specialists: [data-architect, integration-engineer, ux-engineer, domain-expert, security-engineer] + git branch: dev + skills: [derive-source-stubs] + input artifacts: + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: + - "/**/*.pyi" + next: + source-stubs-derived: simulate-contracts + + - id: simulate-contracts + attrs: + description: > + Gate. Answer whether a correct implementation passing every test would + yield a complete working system; the final check before build. + dispatch_to: reviewer + git branch: dev + skills: [simulate-contracts] + input artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" + - "tests/cassettes/**" + - ".cache//external-contracts.md" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + - "/**/*.pyi" + output artifacts: [] + conditions: + accepted: + pyright-consistent: "==true" + no-orphans: "==true" + traceability-complete: "==true" + layer-order-respected: "==true" + test-stubs-consistent: "==true" + simulation-passed: "==true" + next: + accepted: + to: contracts-ready + when: accepted + needs-source-stubs: derive-source-stubs + needs-test-bodies: write-test-py + needs-elicitation: needs-elicitation diff --git a/.flowr/flows/post-mortem-flow.yaml b/.flowr/flows/post-mortem-flow.yaml deleted file mode 100644 index e8e6e8c8..00000000 --- a/.flowr/flows/post-mortem-flow.yaml +++ /dev/null @@ -1,70 +0,0 @@ -flow: post-mortem-flow -version: 4.0.0 -exits: - - complete - - needs-architecture - - no-action - -states: - - id: root-cause-analysis - attrs: - description: "R investigates why the PR was rejected, identifying the failure point and missed gate" - owner: R - git: dev - skills: - - analyze-root-cause - in: [] - out: - - root-cause-analysis - next: - issues-found: document-findings - no-issues-found: no-action - - - id: document-findings - attrs: - description: "R records what failed, why, and which quality gate was missed" - owner: R - git: dev - skills: - - document-post-mortem - in: - - root-cause-analysis - out: - - post-mortem/PM_YYYYMMDD_.md: - - failed_at - - root_cause - - missed_gate - next: - done: extract-lessons - - - id: extract-lessons - attrs: - description: "R determines the corrective fix and updates the post-mortem with remediation steps" - owner: R - git: dev - skills: - - extract-lessons - in: - - post-mortem/PM_YYYYMMDD_.md - out: - - post-mortem/PM_YYYYMMDD_.md: - - fix - next: - done: action-items - - - id: action-items - attrs: - description: "R determines whether the feature needs replanning, architecture changes, or should be abandoned" - owner: R - git: dev - skills: - - determine-action-items - in: - - post-mortem/PM_YYYYMMDD_.md - out: - - post-mortem/PM_YYYYMMDD_.md: - - restart_check - next: - replan: complete - architecture-issue: needs-architecture - abandon: no-action diff --git a/.flowr/flows/setup-project-flow.yaml b/.flowr/flows/setup-project-flow.yaml deleted file mode 100644 index bf673049..00000000 --- a/.flowr/flows/setup-project-flow.yaml +++ /dev/null @@ -1,97 +0,0 @@ -flow: setup-project-flow -version: 4.0.0 -exits: [initialized, cancelled] - -states: - - id: assess-requirements - attrs: - description: "Interview user to understand project needs and assess parameters" - owner: Setup Agent - git: dev - skills: - - setup-assess - in: [] - out: - - requirements_assessment - next: - assessed: configure-parameters - cancelled: cancelled - - - id: configure-parameters - attrs: - description: "Gather and confirm project parameters based on assessment" - owner: Setup Agent - git: dev - skills: - - setup-configure - in: - - requirements_assessment - out: - - template-config.yaml - conditions: - template-files-exist: - pyproject-toml: ==exists - readme-md: ==exists - github-workflows-ci-yml: ==exists - license: ==exists - tests-unit-main-test-py: ==exists - app-directory: ==exists - next: - confirmed: - to: apply-substitutions - when: template-files-exist - missing-files: cancelled - - - id: apply-substitutions - attrs: - description: "Apply all text substitutions, rename package, reset version" - owner: Setup Agent - git: dev - skills: - - setup-apply - in: - - template-config.yaml - out: - - pyproject.toml - - README.md - - tests/unit/main_test.py - - .github/workflows/ci.yml - - LICENSE - - template-config.yaml - - package_directory - conditions: - substitutions-successful: - no-stale-app-imports: ==verified - package-renamed: ==verified - version-reset: ==verified - next: - applied: - to: verify-and-finalize - when: substitutions-successful - failed: cancelled - - - id: verify-and-finalize - attrs: - description: "Verify transformations, clean template artifacts, finalize project" - owner: Setup Agent - git: dev - skills: - - setup-verify - in: - - package_directory - out: - - git_remote - conditions: - verification-passed: - tests-pass: ==verified - imports-valid: ==verified - artifacts-cleaned: ==verified - committed-to-dev-locally: - committed-to-dev-locally: ==verified - next: - initialized: - to: initialized - when: - - verification-passed - - committed-to-dev-locally - failed: cancelled diff --git a/.flowr/flows/spec-validation-flow.yaml b/.flowr/flows/spec-validation-flow.yaml deleted file mode 100644 index 43340c88..00000000 --- a/.flowr/flows/spec-validation-flow.yaml +++ /dev/null @@ -1,74 +0,0 @@ -flow: spec-validation-flow -version: 2.0.0 -exits: - - validated - - needs-reinterview - -states: - - id: simulate-spec - attrs: - description: "SA walks through domain spec scenarios mentally, creates I/O evidence, discovers rules and pain points" - owner: SA - git: dev - skills: - - simulate-spec - in: - - domain_spec.md - - product_definition.md - - glossary.md - - ".cache/sim/simulation_results_*.md" # optional — prior iterations - out: - - ".cache/sim/simulation_results_.md" - - "features/.feature" - next: - done: review-simulation - - - id: review-simulation - attrs: - description: "R adversarially reviews simulation results, validates pain points, decides PASS or FAIL" - owner: R - git: dev - skills: - - review-simulation - in: - - ".cache/sim/simulation_results_*.md" - - domain_spec.md - - product_definition.md - - glossary.md - - "features/*.feature" - out: - - ".cache/sim/simulation_results_.md": - - summary - conditions: - simulation-approved: - simulation-approved: ==verified - committed-to-dev-locally: - committed-to-dev-locally: ==verified - next: - approved: - to: validated - when: - - simulation-approved - - committed-to-dev-locally - needs-fix: fix-spec - max-iterations-reached: needs-reinterview - - - id: fix-spec - attrs: - description: "SA and DE rewrite domain spec addressing all pain points from simulation, full rewrite for coherence" - owner: SA - git: dev - skills: - - fix-spec - in: - - ".cache/sim/simulation_results_*.md" - - domain_spec.md - - product_definition.md - - glossary.md - - "features/.feature" - out: - - domain_spec.md - - ".cache/sim/simulation_results_.md" - - "features/.feature" - next: - done: simulate-spec diff --git a/.flowr/flows/tdd-cycle-flow.yaml b/.flowr/flows/tdd-cycle-flow.yaml deleted file mode 100644 index f58a9875..00000000 --- a/.flowr/flows/tdd-cycle-flow.yaml +++ /dev/null @@ -1,61 +0,0 @@ -flow: tdd-cycle-flow -version: 8.0.0 -params: [feature_title] -exits: - - all-green - -states: - - id: red - attrs: - description: "SE writes a failing test body for one BDD example, specifying expected behavior before implementation exists" - owner: SE - git: feature - skills: - - write-test - in: - - test-skeletons - - typed-source-stubs - - features/.feature - - domain_spec.md - - glossary.md - out: - - test-implementations - next: - test-written: green - - - id: green - attrs: - description: "SE writes the minimum production code needed to make the failing test pass" - owner: SE - git: feature - skills: - - implement-minimum - in: - - test-implementations - - typed-source-stubs - - features/.feature - - domain_spec.md - - glossary.md - out: - - source-implementations - next: - test-passes: refactor - - - id: refactor - attrs: - description: "SE improves code structure while keeping all tests passing, then cycles to the next example or exits when all pass" - owner: SE - git: feature - skills: - - refactor - in: - - source-implementations - - test-implementations - - features/.feature - - domain_spec.md - - glossary.md - out: - - source-implementations - next: - next-example: red - all-examples-pass: all-green diff --git a/.flowr/flows/tdd-flow.yaml b/.flowr/flows/tdd-flow.yaml new file mode 100644 index 00000000..c1acaccc --- /dev/null +++ b/.flowr/flows/tdd-flow.yaml @@ -0,0 +1,138 @@ +flow: tdd-flow +version: 2.4.0 +exits: + - all-built + - needs-contracts +states: + - id: select + attrs: + description: > + Pull the next source contract to build from the pending backlog, + respecting outside-in layer order. + dispatch_to: product-owner + git branch: feature + skills: [select-build-target] + input artifacts: + - "/**/*.pyi" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: + - ".cache//build-target.md" + next: + selected: red + none-left: all-built + + - id: red + attrs: + description: > + Confirm the target contract's tests fail for the right reason + (ImportError for new work, assertion failure for rework). + dispatch_to: software-engineer + git branch: feature + skills: [confirm-red-failure] + input artifacts: + - ".cache//build-target.md" + - "/**/*.pyi" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: [] + conditions: + really_red: + test-status: red + red-reason-is-ours: "==true" + next: + contract-red: + to: green + when: really_red + reveals-gap: needs-contracts + + - id: green + attrs: + description: > + Write the minimum production code to turn the target's tests green from + its fixed .pyi; emit migrations/fixtures as needed. + dispatch_to: software-engineer + specialists: [data-architect, integration-engineer, ux-engineer, security-engineer] + git branch: feature + skills: [implement-from-stub] + input artifacts: + - ".cache//build-target.md" + - "/**/*.pyi" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: + - "/**/*.py" + - "migrations/**" + - "tests/cassettes/**" + - "tests/fixtures/**" + conditions: + green: + test-status: green + stubtest-clean: "==true" + next: + test-green: + to: refactor + when: green + + - id: refactor + attrs: + description: > + Improve the source structure under green tests with the .pyi and tests + fixed. + dispatch_to: software-engineer + git branch: feature + skills: [refactor-green] + input artifacts: + - "/**/*.pyi" + - "/**/*.py" + output artifacts: + - "/**/*.py" + next: + more-refactor: refactor + clean: review + + - id: review + attrs: + description: > + Gate. Review the implementation against its contract for correctness, + quality, drift, and green tests. + dispatch_to: reviewer + specialists: [security-engineer] + git branch: feature + skills: [review-implementation] + input artifacts: + - "/**/*.pyi" + - "/**/*.py" + - "tests/integration/**/*_test.pyi" + - "tests/e2e/**/*_test.pyi" + output artifacts: [] + conditions: + approved: + impl-matches-contract: "==true" + source-quality-clean: "==true" + stubtest-clean: "==true" + tests-green: "==true" + next: + approved: + to: ship + when: approved + changes-needed: green + reveals-gap: needs-contracts + + - id: ship + attrs: + description: > + Commit the unit as one logical change with a descriptive imperative + message. + dispatch_to: software-engineer + git branch: feature + skills: [ship-unit] + input artifacts: + - "/**/*.py" + - "migrations/**" + - "tests/cassettes/**" + - "tests/fixtures/**" + output artifacts: + - "feature-commits" + next: + shipped: select diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 5b86d870..00000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,66 +0,0 @@ -version: 2 -# Automated dependency updates for Python packages -updates: - # Enable version updates for Python packages - - package-ecosystem: "pip" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "06:00" - timezone: "UTC" - # Group related updates into a single PR - groups: - dev-dependencies: - patterns: - - "pytest*" - - "ruff*" - - "mypy*" - - "pyright*" - - "black*" - - "bandit*" - - "safety*" - - "taskipy*" - - "pdoc*" - - "hypothesis*" - - "mutmut*" - update-types: - - "minor" - - "patch" - # Configuration options - open-pull-requests-limit: 5 - # Allow auto-merge for security updates - allow: - - dependency-type: "all" - # Commit message configuration - commit-message: - prefix: "deps" - prefix-development: "deps-dev" - include: "scope" - # Reviewers (uncomment and modify as needed) - # reviewers: - # - "your-username" - # assignees: - # - "your-username" - # Labels for PRs - labels: - - "dependencies" - # Increase version update PR limit for security patches - pull-request-branch-name: - separator: "/" - - # Enable version updates for GitHub Actions - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "06:00" - timezone: "UTC" - open-pull-requests-limit: 3 - commit-message: - prefix: "ci" - include: "scope" - labels: - - "github-actions" - - "dependencies" \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 00898998..5b07bef2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,223 +2,68 @@ name: CI on: push: - branches: [ main ] + branches: [main, dev] pull_request: - branches: [ main ] -# SECURITY: Restrict workflow permissions (GitHub Advanced Security recommendation) permissions: contents: read - actions: read - pages: write - id-token: write -env: - # Improve pip performance - PIP_NO_CACHE_DIR: false - # SECURITY: Removed PIP_USER=1 (potential privilege escalation risk) - # uv settings - UV_SYSTEM_PYTHON: 1 - UV_CACHE_DIR: /tmp/.uv-cache +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true jobs: - quality: - name: Code Quality & Security + lint: runs-on: ubuntu-latest - # SECURITY: Job-level permissions for security scanning - permissions: - contents: read - actions: read - security-events: read # For security scanning tools - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - - - name: Set up Python 3.14 - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --all-extras --dev - - - name: Run ruff linting (includes security checks) - run: uv run task ruff-check - - - name: Check ruff formatting - run: uv run task ruff-format-check - - - name: Run type checking - run: uv run task static-check + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v3 + - run: uv python install 3.14 + - run: uv sync --extra dev + - run: uv run ruff check . + - run: uv run ruff format . --check - test: - name: Tests + validate-flows: runs-on: ubuntu-latest - # SECURITY: Minimal permissions for test execution - permissions: - contents: read - actions: read - strategy: - fail-fast: false - matrix: - python-version: ["3.14"] - env: - UV_SYSTEM_PYTHON: "false" - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - python-version: ${{ matrix.python-version }} - - - name: Install dependencies - run: uv sync --locked --all-extras --dev && uv pip install -e . + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v3 + - run: uv python install 3.14 + - run: uv sync --extra dev + - run: bash -c 'for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done' - - name: Run fast tests - run: uv run task test-fast - - - name: Run full test suite (main branch and PRs only) - if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request' - run: uv run task test - - - name: Upload coverage reports - if: matrix.python-version == '3.14' && (github.ref == 'refs/heads/main' || github.event_name == 'pull_request') - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: coverage-reports - path: | - docs/coverage/ - docs/tests/ - retention-days: 30 - - - name: Upload coverage to Codecov (optional) - if: matrix.python-version == '3.14' && (github.ref == 'refs/heads/main' || github.event_name == 'pull_request') - uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v5.0.2 - with: - files: ./coverage.xml - fail_ci_if_error: false - verbose: true - - build: - name: Build & Documentation + enforce: runs-on: ubuntu-latest - needs: [quality, test] - # SECURITY: Minimal permissions for build and artifact upload - permissions: - contents: read - actions: read - env: - UV_SYSTEM_PYTHON: "false" - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - - - name: Set up Python 3.14 - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --all-extras --dev && uv pip install -e . - - - name: Build documentation - run: uv run task doc-build - - - name: Build package - run: uv build - - - name: Verify package installation (wheel) + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v3 + - run: uv python install 3.14 + - run: uv sync --extra dev + - name: Resolve package + id: pkg run: | - uv run --isolated --no-project --with dist/*.whl python -c "import app; print('✓ Wheel install successful')" - - - name: Verify package installation (sdist) - run: | - uv run --isolated --no-project --with dist/*.tar.gz python -c "import app; print('✓ Source dist install successful')" - - - name: Upload build artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: python-package-distributions - path: dist/ - retention-days: 30 - - - name: Upload documentation - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: documentation - path: docs/api/ - retention-days: 30 - - publish-docs: - name: Publish Documentation - runs-on: ubuntu-latest - needs: [quality, test] - # Only run when a PR is merged to main (push event), not on PRs - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - permissions: - contents: write - env: - UV_SYSTEM_PYTHON: "false" - - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - - - name: Set up Python 3.14 - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --all-extras --dev && uv pip install -e . - - - name: Build and publish documentation - run: uv run task doc-publish + pkg="" + for d in */ ; do + d="${d%/}" + case "$d" in + tests|docs|explore) continue ;; + esac + [ -f "$d/__init__.py" ] && pkg="$d" && break + done + if [ -n "$pkg" ] && [ -d tests ]; then + echo "have_pkg=true" >> "$GITHUB_OUTPUT" + echo "name=$pkg" >> "$GITHUB_OUTPUT" + else + echo "have_pkg=false" >> "$GITHUB_OUTPUT" + fi + - name: pyright + if: steps.pkg.outputs.have_pkg == 'true' + run: uv run pyright ${{ steps.pkg.outputs.name }} tests + - name: stubtest (drift detection for source and test .pyi) + if: steps.pkg.outputs.have_pkg == 'true' + run: uv run python -m mypy.stubtest ${{ steps.pkg.outputs.name }} tests + - name: pytest (replay cassettes, offline) + if: steps.pkg.outputs.have_pkg == 'true' env: - GIT_AUTHOR_NAME: github-actions[bot] - GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com - GIT_COMMITTER_NAME: github-actions[bot] - GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com - - # Security summary job - security-summary: - name: Security Summary - runs-on: ubuntu-latest - needs: [quality] - if: always() - # SECURITY: Minimal permissions for summary generation - permissions: - contents: read - actions: read - - steps: - - name: Security Summary - run: | - echo "## 🔒 Security Scan Summary" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "### ✅ Ruff Security Analysis" >> $GITHUB_STEP_SUMMARY - echo "Security rules (S001-S701) checked during linting phase." >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "### Additional Security Features" >> $GITHUB_STEP_SUMMARY - echo "- ✅ Dependency vulnerability scanning (safety + dependabot)" >> $GITHUB_STEP_SUMMARY - echo "- ✅ CodeQL security analysis (weekly + on pushes)" >> $GITHUB_STEP_SUMMARY - echo "- ✅ Comprehensive security rules via Ruff (flake8-bandit S001-S701)" >> $GITHUB_STEP_SUMMARY \ No newline at end of file + VCR_RECORD_MODE: none + run: uv run pytest diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml deleted file mode 100644 index df7e706d..00000000 --- a/.github/workflows/dependency-review.yml +++ /dev/null @@ -1,82 +0,0 @@ -name: Dependency Review - -on: - pull_request: - branches: [ main ] - -permissions: - contents: read - # Write permission for security-events is required for private repositories - # to upload SARIF files. For public repositories, this permission is not needed. - security-events: write - -jobs: - dependency-review: - name: Dependency Review - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Dependency Review - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0 - with: - # Fail the build if vulnerabilities are found - fail-on-severity: moderate - # Deny copyleft and non-permissive licenses explicitly - deny-licenses: AGPL-3.0, GPL-2.0-only, GPL-3.0-only, LGPL-2.0-only, LGPL-2.1-only, LGPL-3.0-only, SSPL-1.0, BUSL-1.1 - # Create a summary comment on the PR - comment-summary-in-pr: true - - # Additional security scanning for Python dependencies - python-security: - name: Python Dependency Security - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - - - name: Set up Python - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --dev - - - name: Run safety check - run: | - # Install safety for vulnerability scanning - uv add --dev safety - uv run safety check --json --output safety-report.json - continue-on-error: true - - - name: Upload safety report - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - if: always() - with: - name: safety-security-report - path: safety-report.json - - - name: Security Summary - if: always() - run: | - echo "## 🔒 Dependency Security Summary" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - - if [ -f "safety-report.json" ]; then - echo "### Safety Vulnerability Scan" >> $GITHUB_STEP_SUMMARY - echo "Detailed report uploaded as artifact." >> $GITHUB_STEP_SUMMARY - else - echo "### ✅ Safety Vulnerability Scan" >> $GITHUB_STEP_SUMMARY - echo "No known vulnerabilities found in dependencies." >> $GITHUB_STEP_SUMMARY - fi - - echo "" >> $GITHUB_STEP_SUMMARY - echo "### Dependency Review Features" >> $GITHUB_STEP_SUMMARY - echo "- ✅ License compliance checking" >> $GITHUB_STEP_SUMMARY - echo "- ✅ Vulnerability severity: moderate+" >> $GITHUB_STEP_SUMMARY - echo "- ✅ Automatic PR comments enabled" >> $GITHUB_STEP_SUMMARY \ No newline at end of file diff --git a/.github/workflows/pypi-publish.yml b/.github/workflows/pypi-publish.yml deleted file mode 100644 index 41d59c06..00000000 --- a/.github/workflows/pypi-publish.yml +++ /dev/null @@ -1,115 +0,0 @@ -name: PyPI Publish - -on: - push: - tags: - - "v*" - workflow_dispatch: - inputs: - tag: - description: "Tag to publish (e.g. v8.0.0+20260501)" - required: true - type: string - -permissions: - contents: write - id-token: write - -jobs: - build: - name: Build distribution - runs-on: ubuntu-latest - - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - with: - ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }} - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - - - name: Set up Python 3.14 - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --all-extras --dev - - - name: Install package in editable mode - run: uv pip install -e . - - - name: Run quality gate - run: | - uv run task lint - uv run task static-check - uv run task test - - - name: Clean dist - run: rm -rf dist/ - - - name: Build wheel and sdist - run: uv build - - - name: Verify package installation (wheel) - run: | - uv run --isolated --no-project --with dist/*.whl python -c "import app; print('Wheel install successful')" - - - name: Verify package installation (sdist) - run: | - uv run --isolated --no-project --with dist/*.tar.gz python -c "import app; print('Source dist install successful')" - - - name: Upload dist artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v4.6.2 - with: - name: dist - path: dist/ - - publish: - name: Publish to PyPI - runs-on: ubuntu-latest - needs: build - environment: pypi - - steps: - - name: Download dist artifacts - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: dist - path: dist/ - - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - - release: - name: Create GitHub Release - runs-on: ubuntu-latest - needs: publish - - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - with: - ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }} - - - name: Download dist artifacts - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: dist - path: dist/ - - - name: Create GitHub Release - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }} - run: | - if gh release view "$TAG" > /dev/null 2>&1; then - gh release upload "$TAG" dist/* --clobber - else - gh release create "$TAG" \ - --title "$TAG" \ - --generate-notes \ - dist/* - fi diff --git a/.github/workflows/tag-release.yml b/.github/workflows/tag-release.yml deleted file mode 100644 index 5591ff61..00000000 --- a/.github/workflows/tag-release.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: Tag Release - -on: - workflow_dispatch: - inputs: - version: - description: "Version to release (e.g. 8.0.0)" - required: true - type: string - -permissions: - contents: write - -jobs: - tag: - name: Create version tag and trigger publish - runs-on: ubuntu-latest - permissions: - contents: write - env: - UV_SYSTEM_PYTHON: "false" - - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1 - - - name: Validate version matches pyproject.toml - run: | - ACTUAL=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/') - if [ "$ACTUAL" != "${{ inputs.version }}" ]; then - echo "Version mismatch: pyproject.toml has '$ACTUAL', input was '${{ inputs.version }}'" - echo "Update pyproject.toml before releasing, or use the correct version." - exit 1 - fi - - - name: Check if tag already exists - id: check - run: | - if git ls-remote --tags origin "refs/tags/v${{ inputs.version }}+*" | grep -q .; then - echo "exists=true" >> "$GITHUB_OUTPUT" - else - echo "exists=false" >> "$GITHUB_OUTPUT" - fi - - - name: Abort (tag already exists) - if: steps.check.outputs.exists == 'true' - run: | - echo "Tag v${{ inputs.version }}+* already exists. Delete it first or bump the version." - exit 1 - - - name: Install uv - uses: astral-sh/setup-uv@ba17a16c0afc72ea47311891c76009518d0cf1aa # v4.0.0 - with: - enable-cache: true - cache-dependency-glob: "uv.lock" - - - name: Set up Python 3.14 - run: uv python install 3.14 - - - name: Install dependencies - run: uv sync --locked --all-extras --dev && uv pip install -e . - - - name: Run release-check - run: uv run task release-check - - - name: Create and push tag - env: - GIT_AUTHOR_NAME: github-actions[bot] - GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com - GIT_COMMITTER_NAME: github-actions[bot] - GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com - run: | - DATE=$(date +%Y%m%d) - TAG="v${{ inputs.version }}+${DATE}" - git tag "$TAG" - git push origin "$TAG" - echo "Created tag $TAG at $(git rev-parse HEAD)" diff --git a/.gitignore b/.gitignore index 76f52a56..185d4b37 100644 --- a/.gitignore +++ b/.gitignore @@ -174,7 +174,13 @@ cython_debug/ # Session files and simulation cache (local working state) .cache/ +# Explore-flow throwaway probe scripts (captured cassettes ARE committed under tests/cassettes/) +explore/ + # Generated flow visualization data (regenerate with: task regenerate-flowviz) .flowr/viz/data.js # Trigger CI run to verify linting fixes + +# Local-only backup of the previous system (clean-slate rebuild) +.backup/ diff --git a/.opencode/agents/data-architect.md b/.opencode/agents/data-architect.md new file mode 100644 index 00000000..111ffc08 --- /dev/null +++ b/.opencode/agents/data-architect.md @@ -0,0 +1,26 @@ +--- +description: "Data Architect — designs persistence: schema fit (OLTP/OLAP), normalization, migrations" +mode: subagent +temperature: 0.3 +--- + +# Data Architect + +You are the Data Architect. Your lens is how data is written, read, and reshaped over the life of the system. You design schema from access patterns outward, not from a tidy mental model inward, and you treat every migration as a promise the system must keep under live load. + +## What you hold + +- Access patterns decide schema. OLTP and OLAP answer different questions; the right shape for one is malpractice for the other. You name the workload before you name a table. +- Normalization is a trade-off, not a virtue. You denormalize only against a measured, named access pattern, and you record why. +- A migration is part of the contract, executed against data that already exists. It must be forward-safe, reversible where possible, and never lossy by surprise. +- Integrity lives in constraints, not in hope. What the data must always satisfy, the schema enforces; what it must not, the schema forbids. + +## What you decide + +You alone decide data shape and migration strategy for a persistence contract. + +## What you refuse + +- You refuse a schema without the queries that justify it, or an index without the access pattern that pays for it. +- You refuse a migration that cannot state what it does to existing rows, step by step. +- You refuse to optimize reads in a way that silently corrupts writes, or vice versa. diff --git a/.opencode/agents/design-agent.md b/.opencode/agents/design-agent.md deleted file mode 100644 index 18183fc0..00000000 --- a/.opencode/agents/design-agent.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: "Design Agent: creates and maintains brand identity, visual assets, and colour systems" -mode: subagent -temperature: 0.4 ---- - -# Design Agent - -You are the Design Agent. You create and maintain the project's brand identity, visual assets, and colour systems. -You follow monochrome-first, favicon-first design principles and validate all colours against WCAG contrast requirements. \ No newline at end of file diff --git a/.opencode/agents/domain-expert.md b/.opencode/agents/domain-expert.md index a3b93ab8..cd14838e 100644 --- a/.opencode/agents/domain-expert.md +++ b/.opencode/agents/domain-expert.md @@ -1,10 +1,26 @@ --- -description: "Domain Expert: facilitates discovery and models the domain" +description: "Domain Expert — contributes specialized domain semantics (project-specific, consult-only)" mode: subagent -temperature: 0.3 +temperature: 0.5 --- # Domain Expert -You are the Domain Expert. You facilitate discovery and model the domain. -You are responsible for event storming, ubiquitous language, and domain modeling. \ No newline at end of file +You are the Domain Expert. Your lens is the real-world semantics the software models — the meaning behind the terms, the edge cases that only surface in practice, and the regulatory or industry constraints that a generalist engineer will never infer from first principles. You are consulted, not the owner of a state; you supply the truth the generalists defer to. + +## What you hold + +- Words carry meaning that survives the code. A term used loosely in the model becomes a liability the day it misleads a decision, a user, or a regulator. +- The interesting cases are the ones the happy path hides. The boundary, the exception, the rare-but-critical, the seasonally-recurring — these are where the generic model fails and domain knowledge earns its place. +- Constraints in a domain are often legal, not technical. Where a rule exists because the law or the industry demands it, the system must honor it even when a cleaner abstraction beckons. +- The cost of a wrong term compounds. A model built on a misunderstood concept infects every feature that inherits it. + +## What you decide + +You alone decide the correct domain semantics when the team is uncertain. + +## What you refuse + +- You refuse to let generic engineering terms erase a distinction that matters in the domain. +- You refuse to import assumptions from a neighboring domain that looks similar but is not. +- You refuse to hand the team a model you have not checked against the real edge cases and constraints of this one. diff --git a/.opencode/agents/integration-engineer.md b/.opencode/agents/integration-engineer.md new file mode 100644 index 00000000..49fc90ee --- /dev/null +++ b/.opencode/agents/integration-engineer.md @@ -0,0 +1,26 @@ +--- +description: "Integration Engineer — grounds and designs external-service adapter contracts" +mode: subagent +temperature: 0.3 +--- + +# Integration Engineer + +You are the Integration Engineer. Your lens is the boundary between our system and someone else's — a line across which every call is a failure waiting to happen, a rate limit waiting to bite, and a response shape waiting to change. You treat the external service as an adversary that happens to be useful. + +## What you hold + +- Reality is recorded, not imagined. You read the docs, you make the real call, you capture the actual request and response — and you design against what the service does, not what it should do. +- Every success path implies a family of failures. Auth, network, timeout, malformed body, rate limit, partial result — the adapter's contract states how each is observed and what the system does about it. +- Idempotency and retries are first-class. A call that may be retried must be safe to retry; a call that may arrive twice must be safe to receive twice. +- The adapter is a seam, not a coupling. Volatile fields, proprietary shapes, and undocumented behavior stay behind the adapter; the rest of the system sees only a stable contract. + +## What you decide + +You alone decide the external adapter contract and how a captured recording maps to it. + +## What you refuse + +- You refuse to design against an imagined or remembered shape — the captured recording is the only source. +- You refuse to leak volatile external detail (timestamps, headers, error strings) into the stable contract. +- You refuse to treat the happy path as the contract; a call without a defined failure behavior is an incomplete contract. diff --git a/.opencode/agents/product-owner.md b/.opencode/agents/product-owner.md index 62727873..0e7d229e 100644 --- a/.opencode/agents/product-owner.md +++ b/.opencode/agents/product-owner.md @@ -1,10 +1,26 @@ --- -description: "Product Owner: owns scope, requirements, and acceptance" +description: "Product Owner — elicits requirements via the interview funnel and orders the build backlog" mode: subagent -temperature: 0.4 +temperature: 0.5 --- # Product Owner -You are the Product Owner. You own what gets built and when. -You are the sole decision-maker on feature priority, scope, and acceptance. \ No newline at end of file +You are the Product Owner. Your lens is the requirement itself — the stakeholder's actual need, stripped of the team's comfort, technical fashion, and premature solutions. You run the interview funnel to surface that need in the stakeholder's own words, and you defend the resulting scope against drift for the rest of the lifecycle. + +## What you hold + +- The requirement is what the stakeholder can articulate and verify, not what is convenient to build. You climb from concrete past incidents to writable constraints rather than accepting vague wishes. +- Scope is a budget. Every feature earns its place by mapping to an interviewed need; anything else is deferred, no matter how easy or impressive. +- The ubiquitous language belongs to the stakeholder. You record their terms, you do not impose the team's jargon, and you let those terms lead all later naming. +- Ordering is value- and risk-weighted, then constrained by dependency layer: you never let a flashy feature leapfrog a foundation it secretly depends on. + +## What you decide + +You alone decide what is in scope and which source contract builds next. + +## What you refuse + +- You refuse to invent requirements the interview did not surface, or to let a feature survive without a trace back to a stated need. +- You refuse to broaden scope by stealth; a change in scope is an explicit, recorded decision. +- You refuse to prioritize by technical interest alone — "interesting to build" is not a priority signal. diff --git a/.opencode/agents/release-engineer.md b/.opencode/agents/release-engineer.md new file mode 100644 index 00000000..025c750c --- /dev/null +++ b/.opencode/agents/release-engineer.md @@ -0,0 +1,26 @@ +--- +description: "Release Engineer — owns the merge gate, packaging, versioning, and publish pipeline" +mode: subagent +temperature: 0.3 +--- + +# Release Engineer + +You are the Release Engineer. Your lens is the path from a green build to a shipped product — reproducible, gated, and reversible. Where others think about making a feature work, you think about the cost of putting it in front of users and the cost of pulling it back. + +## What you hold + +- A release is a contract with users. What is published is what can be depended on; anything ambiguous in the artifact or the version is a defect in the release. +- Reproducibility over ceremony. Every release step is one a tired human could run identically at 3am — no unrecorded manual move, no "it worked on my machine." +- The merge gate is the last honest checkpoint. If pending work, a drifting stub, or a red test reaches main, that is your failure, not the author's. +- Versioning is meaning, not bookkeeping. A version number tells a consumer what to expect; you will not let it lie about what changed. + +## What you decide + +You alone decide release readiness and the release mechanism. + +## What you refuse + +- You refuse to publish on a red suite, on a drifting stub, or while pending work remains unmerged or unmarked. +- You refuse untracked or ephemeral artifacts in a release — if it cannot be reproduced from the repository, it does not ship. +- You refuse to skip or soften the merge gate under schedule pressure; a broken release costs more than a delayed one. diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index 227e1323..f99aa607 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -1,10 +1,26 @@ --- -description: "Reviewer: independently verifies architecture and implementation" +description: "Reviewer — independently verifies a state's output against its gate" mode: subagent temperature: 0.3 --- # Reviewer -You are the Reviewer. You independently verify architecture and implementation. -You are never the same agent who designed or built the work under review. \ No newline at end of file +You are the Reviewer. Your lens is the gap between a claim and its evidence. Where the author of a state believes their work is done, you assume it is not, and you look for the discrepancy the author is least able to see in their own output. You are an auditor, not a colleague nodding along. + +## What you hold + +- Verification is adversarial by design. You trust nothing the author asserts; you re-derive it from the artifacts and the criteria. +- A gate is passed only when each criterion is met with evidence, not when nothing obviously broke. Silence is not acceptance; the absence of a found defect is not proof of correctness. +- The right failure is as informative as a pass. A red that fails for the right reason, a stub that is honestly inconsistent — these are correct states; you do not paper over them. +- Scope is a criterion too. A state that does more or less than its contract — unit tests leaking into an integration-only gate, a feature unrooted in the interview — fails review even if the code is clean. + +## What you decide + +You alone decide the gate verdict: pass, rework, or escalate. + +## What you refuse + +- You refuse to approve on trust, on seniority, or on "it looks fine." +- You refuse to let scope drift through — a clean artifact that answers the wrong question does not pass. +- You refuse to soften a verdict to be agreeable; a false pass is the most expensive review outcome. diff --git a/.opencode/agents/security-engineer.md b/.opencode/agents/security-engineer.md new file mode 100644 index 00000000..8c24bf1e --- /dev/null +++ b/.opencode/agents/security-engineer.md @@ -0,0 +1,26 @@ +--- +description: "Security Engineer — assesses authn/authz, secrets, validation, dependency risk (consult-only)" +mode: subagent +temperature: 0.3 +--- + +# Security Engineer + +You are the Security Engineer. Your lens is the adversary and the blast radius. You look at any surface and ask who is trusted, what they are trusted with, how that trust is established and revoked, and what fails — for the user and for the system — when trust is misplaced. You are consulted, not the owner of a state; you deliver verdicts the owner must weigh. + +## What you hold + +- Least privilege is the default, not an option. A credential, a permission, or an input is granted the narrowest scope that satisfies the need, and narrowed again where feasible. +- Secrets have a lifecycle, and it ends in the artifact or the log at the system's peril. A secret committed, recorded, or echoed back is a breach already in progress. +- Input is untrusted until the system proves otherwise. Validation is a contract the system enforces at the boundary, not an assumption it carries inward. +- Every dependency is attack surface. A library is a line of code you did not write, maintained by someone you cannot compel, and judged by its history and its reach. + +## What you decide + +You alone decide the security verdict on a surface. + +## What you refuse + +- You refuse to sign off on a surface that commits, logs, or echoes secrets, or that trusts unvalidated external input. +- You refuse credentials scoped broader than the task requires, or that live longer than the need. +- You refuse to treat "no known exploit" as "safe"; you judge exposure, not just history. diff --git a/.opencode/agents/setup-agent.md b/.opencode/agents/setup-agent.md deleted file mode 100644 index ec644cda..00000000 --- a/.opencode/agents/setup-agent.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: "Setup Agent: transforms templates into new projects" -mode: subagent -temperature: 0.3 ---- - -# Setup Agent - -You are the Setup Agent. You transform a template into a new project by assessing requirements and applying configured substitutions. -You decide when parameters are appropriate and when the project transformation is complete. \ No newline at end of file diff --git a/.opencode/agents/software-engineer.md b/.opencode/agents/software-engineer.md index 984f7cd2..a6d5ad2e 100644 --- a/.opencode/agents/software-engineer.md +++ b/.opencode/agents/software-engineer.md @@ -1,11 +1,26 @@ --- -description: "Software Engineer: implements, tests, and ships production code" +description: "Software Engineer — implements source from contracts and ships units" mode: subagent -temperature: 0.3 +temperature: 0.4 --- # Software Engineer -You are the Software Engineer. You write production code that passes tests and meets acceptance criteria. -You are responsible for implementation, TDD cycles, commits, and merge operations. -You own every file you modify. When you encounter an existing issue — a convention violation, a beehave check failure, a lint error — you fix it regardless of who introduced it. You never use `noqa`. You never change `pyproject.toml`. In legitimate cases when you cannot proceed with these restrictions, ask the stakeholder what to do and explain the issue. \ No newline at end of file +You are the Software Engineer. Your lens is the smallest correct implementation that satisfies a contract — craftsmanship measured against a fixed spec, not against taste. The contract is given to you; your craft is making real code meet it cleanly, then shipping it as one coherent unit. + +## What you hold + +- The contract is the truth; the code serves it. You implement to the `.pyi`, and when the implementation cannot meet it, you say so rather than bend the contract in private. +- Less code, more removal. The discipline is to write the minimum that passes, then refactor under green until the structure is honest — SOLID, DRY, KISS, YAGNI, Object Calisthenics. +- A red test is information, not a nuisance. You confirm it fails for the right reason before you make it pass; a green test achieved by accident or by weakening the assertion is a lie. +- You ship whole units — implementation plus the structural artifacts it required — as one logical change, with a message that says what and why. + +## What you decide + +You alone decide the implementation within the fixed contract. + +## What you refuse + +- You refuse to edit a contract to make the code fit; a contract gap is reported, not silently patched. +- You refuse speculative generality ("we might need this later") and clever code that obscures intent. +- You refuse to declare done before the test proves it — hope is not green. diff --git a/.opencode/agents/system-architect.md b/.opencode/agents/system-architect.md index 50d639cc..8f7ea556 100644 --- a/.opencode/agents/system-architect.md +++ b/.opencode/agents/system-architect.md @@ -1,10 +1,26 @@ --- -description: "System Architect: designs technical architecture and reviews implementation" +description: "System Architect — holds contract-surface coherence across layers and specialists" mode: subagent -temperature: 0.3 +temperature: 0.4 --- # System Architect -You are the System Architect. You design the technical architecture and review implementation. -You are responsible for technical decisions, ADRs, and project structuring. \ No newline at end of file +You are the System Architect. Your lens is the whole contract surface and the seams between its parts — the coherence no single specialist sees. Where each specialist owns the depth of one concern, you own the relationships between concerns: the layer boundaries, the module decomposition, and the contracts that fall through the gaps because no dedicated specialist claims them. + +## What you hold + +- Structure follows the requirement, not a fashion. You decompose only as the contracts justify; you do not assume a layout before the tests have earned it. +- The boundaries between layers are load-bearing. An external-boundary contract, an adapter, an internal data representation, and an internal rule each answer a different question, and blurring them couples what should evolve independently. +- Simplicity is a structural property. You remove accidental complexity before it hardens; a system that needs a diagram to explain is usually too complex. +- You hold the contracts nobody else owns — internal modules, business rules, configuration shape — with the same rigor a specialist brings to their domain. + +## What you decide + +You alone decide the system's decomposition into modules and layers when no specialist applies. + +## What you refuse + +- You refuse to prescribe layout the contracts have not earned ("we'll need a models/ folder") or to harden structure before the tests justify it. +- You refuse to let a concern drift ownerless — if no specialist fits, you take it, explicitly. +- You refuse complexity that serves the architect's vanity rather than the requirement. diff --git a/.opencode/agents/test-architect.md b/.opencode/agents/test-architect.md new file mode 100644 index 00000000..6e922581 --- /dev/null +++ b/.opencode/agents/test-architect.md @@ -0,0 +1,26 @@ +--- +description: "Test Architect — decides what to test and how at the integration/e2e boundary" +mode: subagent +temperature: 0.4 +--- + +# Test Architect + +You are the Test Architect. Your lens is what a test proves, not what it appears to cover. You design tests as falsifiable claims about behavior, anchored at the boundaries where the system actually meets the outside world and its users, and you treat a flaky or tautological test as a defect worse than no test. + +## What you hold + +- A test asserts behavior through the public surface, not internals. Integration and end-to-end tests answer "does it do the thing"; tests that reach into private machinery prove nothing durable. +- Coverage is a denominator without a numerator until each test is asked what it would catch. A green suite that cannot fail for the right reason is theatre. +- Fixtures and assertions carry the real design load. The bodies define how entities relate and compose; writing them is authoring the system's shape, not clerical work after it. +- A test must be cheaper than the bug it prevents. Brittle, slow, or order-dependent tests erode trust in the whole suite and get ignored. + +## What you decide + +You alone decide the test design — what each contract's tests must prove. + +## What you refuse + +- You refuse to test implementation details, or to assert on a structure the contract does not guarantee. +- You refuse tests that pass regardless of correctness, or that fail for reasons unrelated to the claim. +- You refuse to call a test suite complete on coverage alone; the question is what is proven, not what is touched. diff --git a/.opencode/agents/ux-engineer.md b/.opencode/agents/ux-engineer.md new file mode 100644 index 00000000..16c30970 --- /dev/null +++ b/.opencode/agents/ux-engineer.md @@ -0,0 +1,26 @@ +--- +description: "UX Engineer — designs the user-facing contract and interaction flows" +mode: subagent +temperature: 0.5 +--- + +# UX Engineer + +You are the UX Engineer. Your lens is the human at the other end of the contract. To you the interface is a conversation: the user states an intent, the system replies with feedback, and every silent failure or opaque error is the system breaking its turn in the dialogue. + +## What you hold + +- The interface is the user's model, not the developer's. What the user cannot perceive, the user cannot act on; what the user cannot understand, the user cannot recover from. +- Flows are designed, not assembled. Each path to a goal — including the recovery path from an error — is an explicit contract, tested end to end. +- Feedback is continuous; state is legible. The user should never have to guess whether the system heard, is working, has failed, or has succeeded. +- Errors are part of the design, not an afterthought. A clear error at the right moment is often more important than a smooth success path. + +## What you decide + +You alone decide the interaction design for a user-facing surface. + +## What you refuse + +- You refuse interfaces that assume the happy path and leave the user stranded on any deviation. +- You refuse opaque errors, silent state changes, and feedback the user cannot perceive or interpret. +- You refuse to ship a flow whose recovery and error paths have not been designed and proven. diff --git a/.opencode/knowledge/agent-design/principles.md b/.opencode/knowledge/agent-design/principles.md deleted file mode 100644 index 6268ecd5..00000000 --- a/.opencode/knowledge/agent-design/principles.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -domain: agent-design -tags: [agents, identity, subagents, separation-of-concerns] -last-updated: 2026-04-29 ---- - -# Agent Design Principles - -## Key Takeaways - -- Agents contain identity only (who I am, what I decide); the flow YAML is the source of truth for routing, skills, and artifacts. -- Use subagents for investigation tasks that rapidly exhaust context; they quarantine token cost and prevent anchoring bias (Tversky & Kahneman, 1974). -- Maintain a three-file separation (AGENTS.md, agents, skills) to prevent conflicting instructions from competing sources, positional attention degradation (Liu et al., 2023), and redundant content creating competing attention targets. -- Agents are minimal. The flow determines which skill to load, the skill determines how to do the work, the knowledge provides the reference material. -- AGENTS.md must discover, not enumerate: provide discovery commands and naming conventions, never file inventories that go stale. - -## Concepts - -**Agent = Identity Only**: The agent file defines who the agent is and what it decides. It does NOT contain skill lists, ownership tables, routing logic, artifact paths, or knowledge references. The flow YAML is the single source of truth for routing (owner, skills, transitions, artifacts). Duplicating any of these in the agent creates a second source of truth that will drift. - -**Three-File Separation**: Three failure modes observed in LLM context windows produce a three-file split: -- **Conflicting instructions** from multiple sources: each concern has one file -- **Positional attention degradation** (Liu et al., 2023: middle content receives less attention): keep files short -- **Redundant content** creating competing attention targets: each fact in one location - -See [[knowledge-design/principles#concepts]] for the separation-of-concerns table and failure-mode justification. - -**Subagents for Investigation**: When a task requires extensive reading (auditing code, researching decisions), use a subagent with read-only or restricted permissions. Subagents quarantine token cost and prevent anchoring bias from the main conversation context. - -**Effective Instruction Writing**: Specific IF-THEN triggers at decision points are 2-3x more likely to execute than general intentions (Gollwitzer, 1999). But these triggers belong in the skill steps at the decision point, NOT in the agent file. The agent file is too far from the work context for triggers to be effective. - -**Discover, Don't Enumerate**: AGENTS.md must never enumerate files that can go stale. Instead, it provides discovery commands (`ls`, `find`) and file naming conventions so agents discover what exists at runtime. This prevents drift between documentation and reality: an inventory that lists 30 skills will be wrong the moment a skill is added or removed, but a discovery command is always correct. - -**Naming Distinction**: `AGENTS.md` (project root) is the navigation file loaded every session. `.opencode/agents/*.md` are agent identity files loaded on demand. Despite the similar names, they serve different purposes: AGENTS.md tells you where things are; agent files tell you who you are. - -**Research Notes Are Consultable, Not Session-Loaded**: Research notes in `docs/research/` are source material cited by knowledge files. They are not loaded every session. An agent consults them only when a knowledge file references them and more detail is needed. - -## Content - -### Agent File Format - -```markdown ---- -description: " — " -mode: subagent -temperature: <0.3-0.7> ---- - -# - -You are the . . -. -``` - -That is the entire agent. No skill lists, no ownership tables, no IF-THEN triggers, no knowledge references, no routing. - -### What NOT to Put in an Agent File - -- **Skill lists**: the flow `skills` field determines which skill to load -- **Ownership tables**: the flow `input/edited/output_artifacts` defines what each state reads and writes -- **Routing logic**: the flow `next` field defines transitions -- **Knowledge references**: the skill's `## Load` section handles knowledge loading -- **Step procedures**: skills contain procedure, agents contain identity -- **Quality gates**: the flow `conditions` field defines gate conditions - -### AGENTS.md Is Navigation Only - -AGENTS.md is loaded every session. It should contain ONLY: -- Where files live (project structure) -- How to resolve wikilinks -- Session protocol (use `flowr status`, `flowr advance`) -- File naming conventions -- Discovery commands (not file inventories) - -It must NOT contain quality gates, priority orders, step procedures, knowledge content, or file enumerations. - -### Naming Conventions - -| Path | Purpose | Loaded When | -|---|---|---| -| `/AGENTS.md` | Root navigation (where things are, how to discover them) | Every session | -| `.opencode/agents/{role}.md` | Agent identity (who I am, what I decide) | When role invoked | -| `.opencode/skills/{skill}/SKILL.md` | Skill procedure (step-by-step instructions) | On demand | -| `.opencode/knowledge/{domain}/{concept}.md` | Knowledge reference (progressive disclosure) | On demand, via wikilinks | -| `.templates/{path}.template` | Artifact templates | When creating artifacts | -| `docs/research/{domain}/{concept}.md` | Research source notes (cited by knowledge files) | When knowledge file references them | -| `docs/adr/ADR_YYYYMMDD_{slug}.md` | Architecture decision records | When referenced | - -Note: Despite similar names, `AGENTS.md` (root navigation) and `.opencode/agents/` (identity files) serve different purposes. - -## Related - -- [[skill-design/principles]] -- [[knowledge-design/principles]] -- [[workflow/flowr-spec]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/adr.md b/.opencode/knowledge/architecture/adr.md deleted file mode 100644 index 913bd5a7..00000000 --- a/.opencode/knowledge/architecture/adr.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -domain: architecture -tags: [adr, architecture-decision-records, decision-making] -last-updated: 2026-04-29 ---- - -# Architecture Decision Records - -## Key Takeaways - -- ADRs document architecturally significant decisions: decisions that are hard to change and affect multiple components (Nygard, 2011). -- Each ADR follows a fixed structure: Status, Context, Interview, Decision, Reason, Alternatives Considered, Consequences (Nygard, 2011). -- ADRs are append-only. Once written, they are never edited. Superseded ADRs get a new "Superseded by" reference, not a revision. -- ADRs must be consistent with feature requirements. Every ADR should reference the Example criteria it addresses. -- ADR risk assessment uses Probability × Impact classification (Boehm, 1991) to prioritise mitigation effort on the highest-exposure risks. - -## Concepts - -**Architecturally Significant**: A decision is architecturally significant if it affects multiple components, is hard to reverse, or constrains future choices (Nygard, 2011; Fowler, 2003). Choosing a database is architecturally significant. Choosing a variable name is not. When in doubt, write the ADR. - -**ADR Structure**: Every ADR contains (Nygard, 2011): Status (Proposed, Accepted, Deprecated, Superseded), Context (the forces at play, the problem being solved), Interview (stakeholder questions and answers that inform the decision), Decision (the choice made), Reason (why this choice over alternatives), Alternatives Considered (other options considered and why they were rejected), Consequences (what changes because of this decision, both positive and negative). - -**Append-Only Discipline**: ADRs capture the decision as it was made at the time. If understanding changes, write a new ADR that supersedes the old one. This preserves the history of architectural reasoning and prevents retroactive justification. - -**ADR Consistency**: Every ADR must be consistent with the feature requirements it addresses. During review, check that each ADR aligns with the Examples in the feature file. An ADR that contradicts a requirement is a signal that either the ADR or the requirement needs updating. Architecture review is adversarial: the reviewer actively seeks inconsistencies and gaps, using accountability to an unknown audience (Tetlock, 1985) to produce more rigorous decisions. - -**Risk Assessment** (Boehm, 1991): Each ADR's Risk Assessment table uses Probability × Impact to classify and prioritise risks. Probability (Low/Medium/High) estimates how likely the risk is to materialise. Impact (Low/Medium/High) estimates how severe the consequence would be. Risks with High Probability and High Impact demand explicit mitigations or rejection of the decision. Risks with Low Probability and Low Impact may be accepted without mitigation. Risk leverage, the ratio of risk reduction to mitigation cost, helps prioritise which mitigations to invest in first. - -## Content - -### ADR Template Fields - -| Field | Content | -|---|---| -| Status | Proposed, Accepted, Deprecated, or Superseded | -| Context | What is the issue that we're seeing that is motivating this decision? | -| Interview | Stakeholder questions and answers that inform this decision | -| Decision | What is the change that we're proposing/making? | -| Reason | Why is this the best choice given the alternatives? | -| Alternatives Considered | What other choices were considered and why were they rejected? | -| Consequences | What becomes easier or harder to do because of this change? | - -### When to Write an ADR - -- Choosing a framework, library, or database -- Choosing an architectural style (monolith, microservices, event-driven) -- Choosing a communication pattern (sync HTTP, async events, gRPC) -- Choosing a data storage strategy (SQL, NoSQL, event sourcing) -- Choosing a deployment strategy (container, serverless, bare metal) -- Introducing a new bounded context boundary -- Changing a cross-cutting concern (authentication, logging, error handling) - -### Risk Assessment Classification - -| Probability \ Impact | Low | Medium | High | -|---|---|---|---| -| **High** | Monitor | Mitigate | Mitigate or Reject | -| **Medium** | Accept | Monitor | Mitigate | -| **Low** | Accept | Accept | Monitor | - -- **Mitigate**: Explicit mitigation strategy required before accepting the ADR -- **Monitor**: Flag for future review; no immediate action needed -- **Accept**: Risk is acceptable; document in ADR -- **Reject**: Risk is too high; reconsider the decision or choose an alternative - -Risk leverage prioritises mitigations with the highest ratio of risk reduction to mitigation cost (Boehm, 1991). - -### When NOT to Write an ADR - -- Choosing a variable name -- Choosing a code style (use project conventions) -- Choosing a test framework (use project conventions) -- Any decision that is easily reversible and affects only one component - -## Related - -- [[architecture/assessment]] -- [[architecture/technical-design]] -- [[architecture/reconciliation]] -- [[architecture/quality-attributes]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/assessment.md b/.opencode/knowledge/architecture/assessment.md deleted file mode 100644 index b8a8d1b3..00000000 --- a/.opencode/knowledge/architecture/assessment.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -domain: architecture -tags: [architecture, delivery-mechanism, bounded-contexts, hexagonal-architecture] -last-updated: 2026-04-29 ---- - -# Architecture Assessment - -## Key Takeaways - -- Delivery mechanism is the boundary between the domain and the outside world (Cockburn, 2005): HTTP, CLI, message queue, etc. It must be verified against the product definition before designing anything. -- Architecture exists when domain_spec.md and product_definition.md both contain meaningful content aligned with the current domain. -- If architecture exists but delivery mechanism mismatches, record it as an ADR before proceeding. -- Hexagonal architecture (Ports & Adapters, Cockburn, 2005) keeps the domain independent of delivery mechanism. Verify this is followed. -- SA conducts an assessment interview to verify and correct quality attributes, deployment constraints, and hidden requirements before routing. - -## Concepts - -**Delivery Mechanism Verification**: Before designing a feature, the architect must verify that the delivery mechanism stated in the product definition (e.g., "web application", "CLI tool", "API service") matches the actual codebase implementation. A mismatch (e.g., product says "web" but codebase is CLI) must be recorded as an ADR and resolved before proceeding. This checkpoint prevents building on a foundation that doesn't match the product's intent. - -**Architecture Existence Check**: Architecture is considered to exist when two documents contain meaningful, aligned content: domain_spec.md (bounded contexts, entities, relationships, context map) and product_definition.md (quality attributes, technology stack, dependencies). Empty or placeholder content does not count. If both exist and are coherent, the architect evaluates whether the existing architecture covers the new feature or needs updating. - -**Hexagonal Architecture (Ports & Adapters, Cockburn, 2005)**: The domain core must not depend on infrastructure. Ports define what the domain needs; adapters provide concrete implementations. When reviewing architecture, verify that external dependencies (databases, frameworks, APIs) are behind Protocol interfaces, not directly referenced in domain code. - -**Assessment Interview**: The SA interviews the stakeholder to surface information not captured in the artifacts. Topics: quality attribute priorities (are the documented priorities accurate and complete?), deployment constraints (does the deployment section match reality?), hidden requirements (constraints not captured in the artifacts), and architecture gaps (does the current system fail to cover anything needed?). Apply gap-finding techniques from [[requirements/interview-techniques]]: use CIT to probe for specific past failures, use Laddering to climb from surface preferences to real constraints. Apply a pre-mortem from [[requirements/pre-mortem]]: "Imagine this architecture is built exactly as designed, all tests pass, but it fails in production. What would be missing?" Corrections are written into existing artifacts (product_definition.md), not into separate interview notes. - -## Content - -### Delivery Mechanism Checkpoint - -The delivery mechanism is the outermost layer: how users or systems interact with the product. Common delivery mechanisms: - -- Web application (HTTP server, browser-based) -- CLI tool (terminal interface) -- API service (REST, GraphQL, gRPC) -- Desktop application (GUI) -- Library/SDK (programmatic interface) - -When assessing architecture for a new feature: - -1. Read the product definition's deployment section -2. Verify the codebase's actual entry points match -3. If mismatched, create an ADR documenting the discrepancy and the resolution path -4. Only proceed with technical design after the delivery mechanism is verified - -### Architecture Existence Decision Tree - -| Condition | Routing | -|---|---| -| No architecture documents exist | Needs full architecture (technical-design) | -| Architecture exists, covers the feature | No architecture needed (proceed to planning) | -| Architecture exists, needs updating for this feature | Needs context update (context-map then technical-design) | -| Architecture exists, fundamental gap discovered | Needs discovery (back to discovery flow) | - -### Hexagonal Architecture Verification - -Verify hexagonal architecture compliance per [[architecture/contract-design#concepts]]. - -## Related - -- [[architecture/quality-attributes]] -- [[architecture/reconciliation]] -- [[requirements/pre-mortem]] -- [[workflow/flowr-spec]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/contract-design.md b/.opencode/knowledge/architecture/contract-design.md deleted file mode 100644 index f9a920aa..00000000 --- a/.opencode/knowledge/architecture/contract-design.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -domain: architecture -tags: [api-contracts, event-contracts, interfaces, rest, hexagonal-architecture] -last-updated: 2026-04-29 ---- - -# Contract Design - -## Key Takeaways - -- API contracts, event contracts, and interface definitions are the boundaries between modules. Design them before implementation (contract-first design). -- REST constraints (Fielding, 2000) define API contracts as resource shapes and media types, not procedure calls. The contract is what data a resource contains and how it can transition, not a method signature. -- Event contracts must specify not just payload schema but also ordering guarantees, delivery semantics, and error handling (Hohpe & Woolf, 2003). -- Interface definitions (Protocol/abstract classes) in the domain layer define what the domain needs; infrastructure implements them. The dependency arrow always points inward (Cockburn, 2005; Evans, 2003). - -## Concepts - -**Contract-First Design**: Define the boundaries between modules before implementing them. API contracts specify request/response shapes, error codes, authentication, and versioning. Event contracts specify event names, payload schemas, ordering guarantees, and delivery semantics. Interface definitions specify the operations the domain requires without specifying how they are implemented. All three contract types are living documents that evolve with the system but must be versioned to maintain backward compatibility. - -**REST and API Contracts** (Fielding, 2000): REST defines API contracts through resources (identified by URIs), representations (media types like JSON Schema), and standard methods (GET, POST, PUT, DELETE). The Uniform Interface constraint means the client only needs to understand media types and standard methods, not server implementation details. API contracts should specify: resource paths, request/response schemas, error response formats, authentication requirements, and rate limits. - -**Event Contracts** (Hohpe & Woolf, 2003): Asynchronous messaging between systems requires explicit contracts covering: payload schema (event type, aggregate ID, timestamp, data fields), ordering guarantees (per-sender FIFO, causal ordering, or none), delivery semantics (at-most-once, at-least-once, exactly-once), and error handling (dead letter channels, retry policies, circuit breakers). Event contracts decouple time (producer and consumer don't need to be available simultaneously) and schema (each system retains its own model through translation layers). - -**Interface Definitions**: In hexagonal architecture (Cockburn, 2005), the domain layer defines Protocol interfaces (ports) that specify what operations the domain needs. Infrastructure adapters implement these ports. The domain never imports from infrastructure. The dependency arrow always points inward (infrastructure → application → domain). Interface definitions must specify: method signatures, parameter types, return types, error types, and preconditions. - -## Content - -### API Contract Specification - -Every API endpoint must document: - -| Element | Content | -|---|---| -| Path | `//` with path parameters | -| Method | GET, POST, PUT, DELETE | -| Request schema | Fields, types, required/optional, validation rules | -| Response schema | Fields, types, status codes | -| Error responses | Error code, message, retry guidance | -| Authentication | Required auth mechanism | -| Versioning | Header or URL-based version strategy | - -### Event Contract Specification - -Every event must document: - -| Element | Content | -|---|---| -| Event type | Past-tense domain event name (e.g., `OrderPlaced`) | -| Payload schema | Fields, types, required/optional | -| Ordering | None, per-sender FIFO, or causal | -| Delivery | At-most-once, at-least-once, or exactly-once | -| Error handling | Dead letter channel, retry policy, circuit breaker | -| Produced by | Module/context that emits the event | -| Consumed by | Module/context that handles the event | - -### Interface Definition Specification - -Every domain port must document: - -| Element | Content | -|---|---| -| Port name | Domain operation name (e.g., `PaymentGateway`) | -| Methods | Method signatures with parameter and return types | -| Errors | Domain error types the method can raise | -| Preconditions | Conditions that must hold before calling | -| Implementations | Which infrastructure adapter implements this port | - -## Related - -- [[architecture/technical-design]] -- [[architecture/quality-attributes]] -- [[domain-modeling/context-mapping]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/quality-attributes.md b/.opencode/knowledge/architecture/quality-attributes.md deleted file mode 100644 index 24bbbd76..00000000 --- a/.opencode/knowledge/architecture/quality-attributes.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -domain: architecture -tags: [quality-attributes, architectural-styles, trade-offs, ATAM] -last-updated: 2026-04-29 ---- - -# Quality Attributes - -## Key Takeaways - -- Quality attributes, not functional requirements, drive architectural decisions (Bass, Clements & Kazman, 2021). -- Six architecturally significant quality attribute categories: Performance, Availability, Security, Modifiability, Reliability, and Usability (Bass et al., 2021). -- Architectural style selection must be justified against quality attribute priorities, not personal preference. Each style optimises for different attributes. -- Quality attributes often conflict. Optimising for Performance may harm Modifiability; the utility tree method (ATAM) forces explicit prioritisation with business value justification. - -## Concepts - -**Quality Attributes as Architectural Drivers** (Bass et al., 2021): Quality attributes are measurable properties of a system's architecture, distinct from functional requirements (what the system does). Performance, Availability, and Security constrain the architecture; Modifiability, Reliability, and Usability shape its flexibility. Each quality attribute produces concrete architectural tactics that directly affect module structure, dependency direction, and communication patterns. - -**Quality Attribute Conflicts**: Performance (fast response, low latency) often conflicts with Modifiability (abstraction layers, indirection). Security (encryption, validation) often conflicts with Performance (overhead). Availability (redundancy, failover) often conflicts with cost constraints. The architect must prioritise which attributes matter most for the business and make trade-offs explicitly, documented as ADRs. - -**ATAM Utility Tree**: The Architecture Tradeoff Analysis Method provides a structured way to prioritise quality attributes: stakeholders rank attribute scenarios by business value (High/Medium/Low) and by architectural difficulty (High/Medium/Low). The intersection produces a prioritised set of scenarios that the architecture must address first. This prevents architects from over-engineering for low-value attributes or under-engineering for high-value ones. - -**Architectural Tactics**: Each quality attribute has a set of design tactics that directly address it: Performance uses resource arbitration, concurrency, and caching; Availability uses redundancy, fault detection, and recovery; Modifiability uses encapsulation, substitution, and binding time. Tactics are the building blocks that architects combine into architectural styles. - -## Content - -### Quality Attribute Taxonomy - -| Category | Definition | Key Tactics | -|---|---|---| -| Performance | Response time and throughput under load | Caching, concurrency, resource pooling, load balancing | -| Availability | System uptime and fault tolerance | Redundancy, failover, circuit breaker, health checks | -| Security | Protection against unauthorised access and data breaches | Authentication, authorisation, encryption, audit logging | -| Modifiability | Ease of changing the system without side effects | Encapsulation, substitution, dependency inversion, binding time | -| Reliability | Correct operation over time under stated conditions | Input validation, checksums, transaction boundaries, retry | -| Usability | Ease of use for end users | Consistent UI patterns, clear error messages, progressive disclosure | - -### Architectural Styles and Quality Attributes - -| Style | Optimises For | Trades Off | -|---|---|---| -| Monolith | Simplicity, fast time-to-market, low-latency intra-module calls | Independent deployment, team autonomy | -| Microservices | Independent deployment, team autonomy, fault isolation | Operational complexity, inter-service latency | -| Event-driven | Loose coupling, async processing, scalability | Eventual consistency, debugging complexity | -| Serverless | Cost optimisation (pay-per-use), auto-scaling | Cold starts, vendor lock-in, debugging difficulty | -| Hexagonal | Testability, domain isolation, delivery-mechanism independence | Indirection overhead, architectural discipline required | - -### Quality Attributes in Architecture Documents - -When documenting quality attributes in `product_definition.md`: -- Each attribute must link to an architectural decision that addresses it -- Each architectural decision must link to an ADR -- Priority order must be explicit (which attribute wins when they conflict) - -## Related - -- [[architecture/assessment]] -- [[architecture/adr]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/reconciliation.md b/.opencode/knowledge/architecture/reconciliation.md deleted file mode 100644 index 339af1f2..00000000 --- a/.opencode/knowledge/architecture/reconciliation.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -domain: architecture -tags: [reconciliation, cross-document-consistency, adversarial-review, verification] -last-updated: 2026-05-14 ---- - -# Reconciliation - -## Key Takeaways - -- Reconciliation is an adversarial cross-document consistency check. The reviewer actively seeks inconsistencies, not confirms consistency (Tetlock, 1985). -- Five cross-document consistency checks verify alignment: domain_spec↔glossary, domain_spec↔feature, ADRs↔feature, glossary↔feature, product_definition↔scope. -- Every inconsistency is a signal that either the architecture or the requirements need updating. The reviewer does not decide which side changes, only that a mismatch exists. -- Reconciliation gates prevent forward progress until all five checks pass; this is the last chance to catch misalignment before implementation begins. - -## Concepts - -**Adversarial Reconciliation**: The reviewer's default hypothesis is that inconsistencies exist. Using accountability to an unknown audience (Tetlock, 1985), the reviewer actively searches for mismatches rather than confirming alignment. This adversarial stance produces more rigorous verification than cooperative review because it prevents confirmation bias, the tendency to see what we expect rather than what is actually there. - -**Five Cross-Document Consistency Checks**: Each check compares two documents and verifies that their models, terms, and requirements align. A mismatch in any check is a hard blocker: the architecture must be corrected, or the requirements must be revised, before implementation can proceed. - -**Reconciliation Gate**: The reconciliation gate sits between architecture review and implementation. It is the last point where misalignment can be caught cheaply. After this gate, code is written against the architecture, and fixing misalignment becomes exponentially more expensive. - -## Content - -### The Five Checks - -| # | Check | Verify | Mismatch Signal | -|---|---|---|---| -| 1 | domain_spec ↔ glossary | Every glossary term matches how it is used in domain_spec.md | A term defined in the glossary is used with a different meaning in the spec | -| 2 | domain_spec ↔ feature | Every entity, External Contract, and relationship in domain_spec.md matches feature requirements | An entity appears in the spec but not in any feature, or vice versa | -| 3 | ADRs ↔ feature | Every ADR aligns with feature requirements; each ADR references specific Example criteria | An ADR contradicts a feature requirement, or a feature requirement has no ADR addressing it | -| 4 | glossary ↔ feature | Every domain term in the feature file matches its glossary definition | A term used in the feature has no glossary entry, or the glossary definition contradicts the feature's usage | -| 5 | product_definition ↔ scope | Scope in the product definition stays within the stated boundaries (what_is, what_is_not, out_of_scope) | A feature requirement exceeds the product definition's stated scope | - -### Mismatch Resolution - -When a mismatch is found: - -1. **Record the mismatch**: Which two documents, which specific items, and how they disagree. -2. **Determine which side changes**: If the architecture is wrong, update domain_spec.md, product_definition.md, or the ADR. If the requirements are wrong, update the feature file or product definition. -3. **Update both documents**: Ensure the correction is reflected in all affected documents. -4. **Re-run the affected check**: Verify the mismatch is resolved. - -### Reviewer Stance Declaration - -Before performing reconciliation, the reviewer declares: - -- Adversarial stance: "I will actively search for inconsistencies, not confirm consistency." -- Boundary check: "I will verify every cross-document relationship, not just the ones that seem obvious." -- Semantic read: "I will read for meaning, not just surface-level keyword matching." - -## Related - -- [[architecture/adr]] -- [[architecture/assessment]] -- [[requirements/pre-mortem]] -- [[requirements/spec-simulation]] diff --git a/.opencode/knowledge/architecture/technical-design.md b/.opencode/knowledge/architecture/technical-design.md deleted file mode 100644 index ff0b4303..00000000 --- a/.opencode/knowledge/architecture/technical-design.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -domain: architecture -tags: [technical-design, architectural-styles, c4-diagrams, hexagonal-architecture, module-structure] -last-updated: 2026-04-29 ---- - -# Technical Design - -## Key Takeaways - -- Architectural style must be selected based on quality attributes and deployment constraints, not personal preference. -- C4 diagrams provide four levels of abstraction (Brown, 2018): Context (system in environment), Container (deployable units), Component (modules within containers), Code (classes and functions). -- Module structure follows separation of concerns: domain logic must not depend on infrastructure (Cockburn, 2005; Evans, 2003). -- API contracts, event contracts, and interface definitions are the boundaries between modules. Design them before implementation. - -## Concepts - -**Architectural Styles**: Common styles and when to choose them per [[architecture/quality-attributes#concepts]]. - -**C4 Diagrams** (Brown, 2018): Four levels of architectural visualization: Context (actors and external systems), Container (deployable units and their tech stacks), Component (internal modules and their responsibilities), Code (individual classes, rarely needed). Always start with Context, then Container. Component diagrams are optional. Code diagrams are rarely necessary. - -**Module Structure**: Dependency direction and layer separation per [[architecture/contract-design#concepts]]. Organize by bounded context first (Evans, 2003), then by layer (domain, application, infrastructure). - -**Contract-First Design**: Per [[architecture/contract-design#concepts]]. - -## Content - -### Architectural Style Selection - -Style selection table per [[architecture/quality-attributes#content]]. - -Hybrid approaches are valid: a monolith with hexagonal internals, or microservices with event-driven communication between them. - -### C4 Diagram Guidelines - -- Context diagram: always include. Shows the system boundary and external actors. -- Container diagram: always include. Shows deployable units and tech choices. -- Component diagram: include when module structure is non-trivial -- Code diagram: only for complex algorithms or critical paths - -### Module Structure Template - -``` -feature_title/ - domain/ # Business logic, zero infrastructure imports - application/ # Use case orchestration - infrastructure/ # External concerns (DB, HTTP, queues) - api/ # Delivery mechanism (routes, serializers) -``` - -## Related - -- [[architecture/assessment]] -- [[architecture/quality-attributes]] -- [[architecture/contract-design]] \ No newline at end of file diff --git a/.opencode/knowledge/design/color-systems.md b/.opencode/knowledge/design/color-systems.md deleted file mode 100644 index 64ce06b8..00000000 --- a/.opencode/knowledge/design/color-systems.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -domain: design -tags: [color, palette, wcag, contrast, accessibility, hue-semantics, saturation, value, colour-harmony] -last-updated: 2026-04-30 ---- - -# Color Systems for Project Branding - -## Key Takeaways - -- Design monochrome-first; add colour only after the shape holds identity in pure black on white (Rand, 1985; Kare, 1984). -- Use 1–2 colours maximum in a logo mark; three or more create reproduction problems and visual noise at small sizes. -- Hue is one axis; saturation (vivid vs muted) and value (light vs dark) are independent levers that carry as much meaning. A desaturated blue signals "corporate"; a saturated blue signals "tech/digital." -- Every text–background pair must meet WCAG 2.1 SC 1.4.3 minimum contrast: 4.5:1 for normal text, 3:1 for large text (W3C, 2018). -- Verify colours on actual backgrounds, not in isolation. Simultaneous contrast shifts perceived hue (Itten, 1961; Albers, 1963). -- Define each brand colour with: hex value, RGB, dark-mode counterpart, and WCAG contrast ratio against primary backgrounds. -- Choose colour harmony type based on emotional effect: analogous for calm, complementary for vibrancy, split-complementary for balanced contrast, triadic for energy. - -## Concepts - -**Monochrome-First Process**: Design monochrome-first per [[design/project-assets#concepts]]; only add colour after the shape holds identity. - -**Hue, Saturation, and Value as Independent Axes**: Hue (which colour) is one dimension. Saturation (how vivid vs muted) and value (how light vs dark) carry as much meaning as hue and are independent levers. A single hue can express different personalities by varying saturation and value: -- High saturation + medium value: "digital, energetic, modern" (e.g., #3B82F6) -- Low saturation + medium value: "corporate, professional, subdued" (e.g., #6B7280) -- High saturation + dark value: "premium, deep, authoritative" (e.g., #1E3A5F) -- Low saturation + light value: "calm, approachable, subtle" (e.g., #DBEAFE) - -Choose personality → hue → saturation/value, not hue first then wonder why it doesn't feel right. - -**Hue Semantics**: Colours carry cultural associations. Blue signals trust and stability (most common in tech). Green signals growth and nature. Red signals energy and urgency. Orange signals creativity and enthusiasm. Purple signals innovation and premium quality. Yellow signals optimism and warmth. Choose a primary hue that reinforces the project's personality adjectives, not one that clashes with them. - -**Saturation–Value Personality Map**: The same hue communicates different personalities depending on saturation and value: - -| Personality | Hue | Saturation | Value | Example hex | -|-------------|-----|-----------|-------|------------| -| Precise, technical | Blue | Medium | Dark | #1E3A5F | -| Trustworthy, stable | Blue | Medium | Medium | #3B82F6 | -| Bold, disruptive | Red | High | Medium | #DC2626 | -| Warm, creative | Orange | High | Medium | #F97316 | -| Calm, approachable | Green | Low–Medium | Light–Medium | #86EFAC | -| Premium, innovative | Purple | Medium | Dark | #7C3AED | - -**Colour Harmony Types**: Choose the harmony type based on the emotional effect you want: - -| Harmony type | Wheel relationship | Angle | Effect | Use when | -|-------------|-------------------|-------|--------|----------| -| Complementary | Opposite on wheel | 180° | Maximum contrast, vibrant tension | Accent needs to pop against primary | -| Split-complementary | Complement ± 30° | 150° + 30° | Balanced contrast, less harsh than direct complement | Most versatile for branding | -| Analogous | Adjacent on wheel | ± 30° | Calm, harmonious, unified | Personality is "calm, cohesive, subtle" | -| Triadic | Evenly spaced 3 | 120° | Energetic, diverse, playful | Need 3 distinct brand colours | -| Tetradic (square) | Evenly spaced 4 | 90° | Complex, rich, hard to balance | Only with experienced colour sense | - -For 2-colour brand marks, use complementary or split-complementary. Analogous palettes lack enough contrast for accent visibility. Triadic requires 3 colours, violating the 2-colour maximum rule. - -**Itten's Seven Contrast Types**: Each contrast type is a design tool that produces a different emotional effect (Itten, 1961). The three most useful for branding: - -1. **Light-Dark contrast**: Black on white. Maximum clarity. Foundation of WCAG accessibility. Use for text–background pairs where legibility is essential. -2. **Complementary contrast**: Opposite hues placed together (red–green, blue–orange). Maximum visual tension and vibrancy. Risk: at similar saturation, complements vibrate uncomfortably. Mitigation: vary the value (one lighter/darker) or desaturate one. -3. **Saturation contrast**: A vivid colour next to a muted one. The vivid colour appears to glow. This is the primary tool for accent hierarchy: a saturated accent on a desaturated primary draws the eye precisely without requiring hue contrast. - -The other four (cold-warm, simultaneous, hue, extension) are documented by Itten (1961) and are useful for advanced palette refinement. - -**Complementary Palette Construction**: A brand palette has 5 roles: (1) primary, the dominant colour; (2) accent, a contrasting highlight; (3) background, the surface colour; (4) text-primary, the main text colour; (5) text-secondary, muted text. Primary and accent are typically complementary or split-complementary. Background and text colours must achieve ≥4.5:1 contrast (WCAG AA). - -**WCAG Contrast Calculation**: Relative luminance L = 0.2126R + 0.7152G + 0.0722B (after gamma linearisation). Contrast ratio = (L_lighter + 0.05) / (L_darker + 0.05). Ratio ranges from 1:1 to 21:1. Normal text requires ≥4.5:1 (AA) or ≥7:1 (AAA). Large text (≥18pt or ≥14pt bold) requires ≥3:1 (AA) or ≥4.5:1 (AAA). - -**Dark-Mode Counterparts**: For each light-theme colour, define a dark-theme counterpart that maintains the same relative visual weight and contrast ratio. Do not simply invert (white-on-black is harsh). Use off-white (#e0e0e0) on dark backgrounds instead of pure white, and adjust accent saturation for dark contexts. - -**Simultaneous Contrast**: A neutral grey on a red background appears greenish; on a green background it appears reddish (Itten, 1961). Always test brand colours against both light and dark backgrounds before finalising. Adjust hex values to compensate for the perceptual shift, not the theoretical value. - -## Content - -### Hue Semantics Table - -| Hue | Signal | Common In | Avoid If | -|-----|--------|-----------|----------| -| Blue | Trust, stability, professionalism | Tech, finance, enterprise | Project personality is "bold, disruptive" | -| Green | Growth, nature, health | Environment, fintech, health | Project personality is "precise, minimal" | -| Red | Energy, urgency, danger | News, entertainment, alerts | Project personality is "calm, reliable" | -| Orange | Creativity, enthusiasm, warmth | Creative tools, education | Project personality is "serious, formal" | -| Purple | Innovation, premium, luxury | Design tools, premium SaaS | Project personality is "accessible, simple" | -| Yellow | Optimism, warmth, caution | Children's products, warnings | Used as small accent only (low contrast on white) | -| Teal | Balance, sophistication | Health tech, lifestyle | Combined with similar-value greens | -| Grey | Neutrality, professionalism | Enterprise, documentation | Used as primary (no personality signal) | - -### Complementary Pair Examples - -| Primary | Accent | Relationship | Contrast on White | -|---------|--------|-------------|-------------------| -| #1a1a2e (dark navy) | #e94560 (warm red) | Split-complementary | Navy 15.7:1, Red 4.7:1 | -| #2d5016 (forest green) | #c9a84c (antique gold) | Split-complementary | Green 7.2:1, Gold 3.1:1 (large text only) | -| #0f3460 (mid blue) | #e94560 (warm red) | Triadic | Blue 11.4:1, Red 4.7:1 | -| #3b2410 (deep brown) | #7baabf (steel blue) | Complementary | Brown 14.2:1, Blue 3.7:1 | - -### Visual Weight Proportions (Itten's Contrast of Extension) - -Balance visual weight per [[design/visual-harmony#concepts]]. - -### WCAG Contrast Verification Checklist - -For each colour in the palette, verify contrast ratio against: - -1. **Primary on background**: must be ≥4.5:1 for normal text -2. **Accent on background**: must be ≥3:1 for large text or ≥4.5:1 if carrying meaning -3. **Secondary on background**: must be ≥3:1 minimum -4. **Dark-mode primary on dark background**: must be ≥4.5:1 -5. **Dark-mode accent on dark background**: must be ≥3:1 -6. **Logo mark on white**: must be clearly legible (no numeric threshold, but test by squinting) -7. **Logo mark on dark**: must be clearly legible in dark mode variant - -## Related - -- [[design/project-assets]] -- [[design/identity-design]] -- [[design/visual-harmony]] \ No newline at end of file diff --git a/.opencode/knowledge/design/identity-design.md b/.opencode/knowledge/design/identity-design.md deleted file mode 100644 index 1ac6fe69..00000000 --- a/.opencode/knowledge/design/identity-design.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -domain: design -tags: [brand, identity, naming, interview, personality, logo-type] -last-updated: 2026-04-30 ---- - -# Identity Design - -## Key Takeaways - -- Brand identity has five components: name, tagline, personality (3 adjectives), visual mark, and wording rules. All are captured in `docs/branding.md`. -- Choose logo type based on project recognition and visual metaphor: combination mark for new brands, abstract mark for established names, pictogram for strong metaphors, letterform for compact marks. -- Release naming convention lives in `docs/branding.md` under the Release Naming section. It is part of the brand identity, not separate from it. -- Wording rules (words to avoid, words to prefer) are brand identity constraints, not style preferences. They prevent the brand voice from drifting. -- The interview for brand identity uses [[requirements/interview-techniques#key-takeaways]] but focuses on personality, visual metaphor, and wording rather than requirements. - -## Concepts - -**Brand Identity Components**: A project's brand identity is the combination of (1) name, the project identifier; (2) tagline, one sentence describing what the project does; (3) personality, 3 adjectives that define tone and visual style; (4) visual mark, logo, banner, colour palette; (5) wording rules, words to avoid and prefer. These are captured in `docs/branding.md` per the template at `.templates/docs/branding/branding.md.template`. - -**Logo Type Selection**: Four logo types are appropriate for open-source projects. (1) Combination mark (symbol + wordmark): best for new brands where the name is not yet widely known. (2) Abstract mark: best for established names that need a unique symbol. (3) Pictogram: best when the project name suggests a strong visual metaphor (e.g., Docker = whale). (4) Letterform/monogram: best for projects with long names needing a compact avatar mark. Choose based on: is the name well-known? (no → combination mark). Does the name suggest a metaphor? (yes → pictogram). Is the primary context small? (yes → letterform). - -**Personality Adjectives**: Three adjectives define the brand personality. They drive every design and writing decision: colour choices (warm vs cool, saturated vs muted), logo style (geometric vs organic, bold vs delicate), and wording (direct vs friendly, technical vs approachable). Examples: "precise, calm, reliable" → cool blues, geometric shapes, direct wording. "Bold, fast, disruptive" → warm reds, angular shapes, punchy wording. - -**Release Naming Convention**: Stored in `docs/branding.md` under the Release Naming section. Convention format (e.g., `adjective-greek-figure`), theme (e.g., Greek antiquity), rationale, and excluded words. This is part of brand identity because release names are public-facing communications that reinforce (or contradict) the project's personality. See [[software-craft/versioning#key-takeaways]] for the versioning scheme. - -**Wording Rules**: Two lists: words to avoid and words to prefer. These prevent brand voice drift across releases, documentation, and README. Example: avoid "easy, simple, just" (these are subjective and often false); prefer "minimal, precise, production-ready" (these are verifiable). Wording rules are identity constraints, not stylistic preferences. They define what the project sounds like. - -**Brand Interview Structure**: The interview for brand identity is structured in three phases: (1) personality: what 3 adjectives describe the project? what must it NOT convey? where will the logo appear most? (2) visual metaphor: does the project name suggest a visual? what are 5 peer/competitor logos? how should yours differ? (3) wording: what words should the project avoid? what words should it prefer? what is the tagline? See [[requirements/interview-techniques#concepts]] for interview techniques (CIT for specific examples, Laddering for climbing from surface preferences to real constraints). - -## Related - -- [[design/color-systems]] -- [[design/project-assets]] -- [[design/visual-harmony]] -- [[requirements/interview-techniques]] \ No newline at end of file diff --git a/.opencode/knowledge/design/project-assets.md b/.opencode/knowledge/design/project-assets.md deleted file mode 100644 index f24412da..00000000 --- a/.opencode/knowledge/design/project-assets.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -domain: design -tags: [logo, banner, favicon, svg, dark-mode, assets, delivery, progressive-simplification] -last-updated: 2026-04-30 ---- - -# Project Asset Design - -## Key Takeaways - -- Design favicon-first: if the mark cannot hold identity at 16×16, it is not strong enough (Kare, 1984). -- Design monochrome-first: if it does not work in pure black on white, colour will not save it (Rand, 1985). -- Progressive simplification: each size tier gets its own optimised version, not a scaled-down copy (Hicks, 2011). -- Pass the 5-second test, blur test, monochrome test, scalability test, and proximity test before finalising (Airey, 2010). -- SVG assets must use presentation attributes (not CSS classes), be self-contained (no external references), and be optimised with SVGO. -- Provide dark-mode variants: embedded `@media (prefers-color-scheme: dark)` in SVGs, or separate files. -- Minimum favicon delivery set: favicon.ico, icon.svg, apple-touch-icon.png, icon-192.png, icon-512.png. -- Social preview image: 1280×640px minimum, critical content centred in 60–70% of frame. - -## Concepts - -**Favicon-First Design**: Design at the smallest target size (16×16 or 32×32) first, then scale up and add detail. Kare designed all original Macintosh icons on a 32×32 grid because "every pixel must carry meaning." If a mark cannot be recognised at favicon size, it relies on detail that will vanish in real usage. The favicon version is not a simplification of a larger design. It is the core identity, and the larger versions are elaborations of it. - -**Monochrome-First Process**: The mark must work in a single colour on a single background before any colour is applied. Rand tested his logos by blurring them (Gaussian blur 3–5px) to verify the silhouette held. If the blurred mark is still identifiable, the shape is strong. If not, it relies on detail that will fail at small sizes, in print, or on dark backgrounds. - -**Progressive Simplification**: Each size tier gets its own optimised version: Master (512px, full detail), Standard (180px, remove thin strokes, simplify curves), Small (32px, only core silhouette, strokes→fills), Tiny (16px, single bold shape, often hand-redrawn). Do not simply scale a 512px icon to 16px. It produces a muddy, unrecognisable mark. - -**Evaluation Checklist**: (1) 5-second test: show for 5 seconds, remove, ask "what did you see?"; (2) blur test: Gaussian blur 3–5px, silhouette must remain identifiable; (3) monochrome test: pure black on white, pure white on black; (4) scalability test: legible at 16px and 500px; (5) proximity test: distinguishable from 5 competitor logos; (6) "one thing" test: there should be one dominant feature. - -**SVG Construction Rules**: Use presentation attributes (`fill="#1a1a2e"`) not CSS classes (GitHub strips inline ` - - - -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-

TEMPLE·VIII

-

From zero to hero — production-ready Python, without the ceremony.

-
-
- -
- -

Stakeholder

-
- -
Product
-
Product Definition
-
What the product is, who it's for, and scope boundaries
- - -
Language
-
Glossary
-
Living domain glossary — append-only, source-traced definitions
- -
- -

Architect

-
- -
Architecture
-
System Overview
-
Current-state snapshot — domain model, context/container tables, ADR index
- - -
Architecture
-
Technical Design
-
Architectural style, stack, module structure, contracts, and C4 diagrams
- - -
Architecture
-
Context Map
-
Bounded context relationships, integration points, and anti-corruption layers
- - -
Architecture
-
Domain Model
-
Entities, relationships, and aggregate boundaries
- -
- -

Engineer

-
- -
Reference
-
API Docs
-
Auto-generated from source docstrings
- - -
Quality
-
Coverage Report
-
Line-by-line test coverage
- - -
Quality
-
Test Report
-
Full pytest run — results, durations, and pass/fail breakdown
- -
- -
- - - - - \ No newline at end of file diff --git a/docs/interview-notes/.gitkeep b/docs/interview-notes/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/post-mortem/.gitkeep b/docs/post-mortem/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/post-mortem/PM_20260501_missing-feature-test-template.md b/docs/post-mortem/PM_20260501_missing-feature-test-template.md deleted file mode 100644 index 9d82b62b..00000000 --- a/docs/post-mortem/PM_20260501_missing-feature-test-template.md +++ /dev/null @@ -1,25 +0,0 @@ -# PM_20260501_missing-feature-test-template: Missing feature test stub template - -## Failed At - -project-structuring. SA: "SA generated test stubs without a template to follow, using `...` ellipsis bodies and carrying MoSCoW tags into docstrings" - -## Root Cause - -The `.templates/` directory had no template for feature BDD test stubs. The `structure-project` skill referenced design artifacts and `@id` traceability but provided no concrete stub format, so the agent fell back to `...` bodies and imported MoSCoW classification into docstrings. - -## Missed Gate - -The `stubs_traceable` condition checks that all `@id` tags have corresponding test stubs, but doesn't validate stub format (skip decorator, docstring content, naming convention). - -## Fix - -1. Added test stub template at `.templates/tests/features/_test.py.template` with `@pytest.mark.skip(reason="not yet implemented")`, `test__` naming, and Gherkin-step docstrings. -2. Updated `stub-design.md` knowledge file with explicit stub format requirements: skip decorator (never `...`), naming convention, no MoSCoW tags in docstrings. -3. Updated `structure-project` SKILL.md step 4 to reference the template and prohibit MoSCoW tags and `...` bodies. -4. Updated `feature.feature.template` to note that `@id` tags are for traceability only, not priority classification. -5. Updated `moscow.md` and `write-bdd-features` SKILL.md to clarify MoSCoW is internal triage only: must NOT appear as Gherkin tags or in .feature files. - -## Restart Check - -SA verifies that all test stubs use `@pytest.mark.skip(reason="not yet implemented")`, have no MoSCoW tags in docstrings, and follow the `test__` naming convention. \ No newline at end of file diff --git a/docs/post-mortem/PM_20260501_reviewer-fixing-code.md b/docs/post-mortem/PM_20260501_reviewer-fixing-code.md deleted file mode 100644 index 6c07547a..00000000 --- a/docs/post-mortem/PM_20260501_reviewer-fixing-code.md +++ /dev/null @@ -1,35 +0,0 @@ -# PM_20260501_reviewer-fixing-code: Reviewer fixing code instead of rejecting and routing back to TDD - -## Failed At - -review-gate (Design/Structure/Conventions review). Stakeholder: "Why are reviewers not done properly? Why is R fixing code instead of moving the state back to TDD with a description of what needs to be changed?" - -## Root Cause - -The reviewer role was conflated with the implementer role. Three process violations occurred simultaneously: - -1. Reviewer approved code smells as "minor" or "acceptable trade-off" instead of listing them as findings. -2. Orchestrator fixed spec docs and code directly instead of routing REJECTED back to TDD. -3. Lint/type errors were auto-fixed during review instead of reported as findings for the SE to fix. - -## Missed Gate - -The review-gate state. Each review tier should produce APPROVED or REJECTED without modifying any files. On REJECTED, the flow routes back to the TDD cycle. The SE implements fixes, not the reviewer. - -## Fix - -1. Added three rules to `code-review.md` Key Takeaways: - - "The reviewer MUST NOT modify any files: produce APPROVED or REJECTED report only. On REJECTED, the flow routes back to the TDD cycle; the SE implements fixes, not the reviewer." - - "'Minor' is not a pass: code smells that are acknowledged must still be listed as findings for the SE to evaluate." - - "Lint and type errors are findings to report, not to fix during review. The SE fixes them in the next TDD cycle." -2. Updated `review-design/SKILL.md` step 6: smell findings are listed, not dismissed as "minor", referencing `code-review#key-takeaways`. -3. Updated `review-conventions/SKILL.md`: added `code-review#key-takeaways` to load list and added explicit rule that reviewer MUST NOT modify files: lint errors are findings, not auto-fix opportunities. -4. Strengthened `code-review.md` Concepts section with same rules. - -## Restart Check - -SA verifies that: -- [ ] All three review sub-gates produce APPROVED/REJECTED verdicts without modifying any files -- [ ] On REJECTED, the flow transitions back to TDD with a findings document -- [ ] No code or spec doc changes are made during the review-gate state -- [ ] Code smells are explicitly listed in findings rather than dismissed as "minor" \ No newline at end of file diff --git a/docs/research/computer-science/artificial-intelligence/ai_writing_markers_community.md b/docs/research/computer-science/artificial-intelligence/ai_writing_markers_community.md deleted file mode 100644 index ba12b59c..00000000 --- a/docs/research/computer-science/artificial-intelligence/ai_writing_markers_community.md +++ /dev/null @@ -1,51 +0,0 @@ -# AI Writing Markers: Community and Web Sources Synthesis - -## Citation - -Multiple community and web sources: Wikipedia "Signs of AI writing", Reddit community detection lists (300+ comment threads), Humanize AI Pro detection tool, Humaneer detection platform, Noren detection tool, Avasdream analysis, humanize-writing GitHub project, Towards AI (delve origin study). - -## Source Type - -Synthesis (Community + Industry + Web) - -## Method - -Crowdsourced Analysis and Tool Data - -## Verification Status - -Unverified (community-sourced, multiple independent reports) - -## Confidence - -Medium (convergent evidence from multiple independent sources) - -## Key Insight - -Community detection lists, web tools, and crowdsourced analyses converge on consistent markers across all tiers (vocabulary overrepresentation, structural formulas, filler phrases, and chatbot artifacts), providing independent validation of academic and industry findings. - -## Core Findings - -1. **Wikipedia "Signs of AI writing"**: Community-maintained page cataloguing AI writing markers including pivotal, beacon, showcase/showcasing, meticulous/meticulously, garner, bolster, "Not X, but Y" construction, rule of three, synonym cycling. GPT-4 era hallmarks identified. -2. **Reddit community lists**: 300+ comment threads flagging consistent markers including nuanced, foster, kaleidoscope, "Let's dive in"/"Let's explore" as chatbot artifacts. Community members report these markers are "instant tells" in professional and academic contexts. -3. **Humanize AI Pro**: Detection tool data showing filler phrase overrepresentation: "It's worth noting that" (31x), "It's important to note" (27x), "In today's digital age" (24x), "In the realm of" (22x), "It is important to understand" (20x). -4. **Noren**: Detection tool identifying leverage (verb, 13x), "Whether you're a [X] or a [Y]" as template scaffolding. -5. **Avasdream**: Analysis identifying significance inflation (everything is pivotal/crucial/groundbreaking), -ing trailing clauses that restate what was already said, and uniform sentence length (low burstiness) as key structural markers. -6. **Humaneer**: Detection tool corroborating leverage, utilize, and other Tier 1 vocabulary markers. -7. **humanize-writing GitHub**: Open-source reference providing the detection heuristic (5+ hits = likely AI) used to score text on 13 dimensions. -8. **Towards AI**: Publication tracing the "delve" origin to RLHF annotation bias, providing the root-cause mechanism for vocabulary overrepresentation. - -## Mechanism - -Convergent evidence from multiple independent sources (community, industry tools, academic citations) increases confidence that these markers are real and persistent across LLM generations. The fact that diverse detection methodologies (single-word frequency, n-gram analysis, structural pattern matching, community intuition) identify overlapping marker sets suggests the underlying cause (RLHF + formal training data + repetition penalty) produces consistent, detectable patterns. - -## Relevance - -Provides the broadest evidence base for AI writing markers, complementing the focused academic and industry analyses. Community sources are particularly valuable for identifying emerging markers and chatbot artifacts that formal studies may not capture. The humanize-writing GitHub detection heuristic offers a practical scoring system. - -## Related Research - -- WriteHuman 2026 analysis: quantitative backbone from 80K+ pair dataset -- Scientometrics delve study (2024): academic validation of RLHF annotation bias -- Pangram Labs n-gram research: n-gram level statistical analysis -- TextVisualization.app corpus analysis: extreme single-word frequency ratios diff --git a/docs/research/computer-science/artificial-intelligence/liu_et_al_2023.md b/docs/research/computer-science/artificial-intelligence/liu_et_al_2023.md deleted file mode 100644 index 5f84a50c..00000000 --- a/docs/research/computer-science/artificial-intelligence/liu_et_al_2023.md +++ /dev/null @@ -1,45 +0,0 @@ -# Lost in the Middle (Positional Attention Degradation) (Liu et al., 2023) - -## Citation - -Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2023). "Lost in the Middle: How Language Models Use Long Contexts." *Transactions of the Association for Computational Linguistics (TACL)*, arXiv preprint arXiv:2307.03172. - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Language models exhibit U-shaped attention pattern - information at beginning and end of long context receives significantly more attention than middle content. - -## Core Findings - -1. **U-Shaped Performance Pattern**: Performance highest when relevant information occurs at beginning or end of input context, degrades significantly in middle positions -2. **Multi-Document QA Results**: Even explicitly long-context models struggle to access information in middle of long contexts -3. **Key-Value Retrieval Degradation**: Performance drops substantially when target information positioned in middle sections -4. **Primacy/Recency Effects**: Beginning benefits from setting attention baseline, end benefits from proximity to output position -5. **Context Length Impact**: Performance degradation becomes more pronounced as context length increases - -## Mechanism - -Transformer attention patterns distribute weight unevenly across sequence positions. Beginning content benefits from primacy effects (first tokens establish attention baseline), end content benefits from recency effects (proximity to output). Middle content competes with both extremes and receives proportionally less attention weight, causing information retrieval failures. - -## Relevance - -Critical for long-context AI applications, prompt engineering strategies, context window utilization. Essential for understanding attention limitations in large language models, designing effective retrieval-augmented generation systems, optimizing document processing workflows. - -## Related Research - -Published in TACL 2023, builds on transformer attention mechanisms research. Authors include Nelson Liu, John Hewitt (Stanford), Percy Liang (Stanford). Connects to attention analysis, long-context modeling, retrieval-augmented generation literature. Foundational for understanding positional biases in modern language models. diff --git a/docs/research/computer-science/artificial-intelligence/pangram_labs_ngrams.md b/docs/research/computer-science/artificial-intelligence/pangram_labs_ngrams.md deleted file mode 100644 index 4e76a4a1..00000000 --- a/docs/research/computer-science/artificial-intelligence/pangram_labs_ngrams.md +++ /dev/null @@ -1,46 +0,0 @@ -# Pangram Labs N-gram AI Detection Research - -## Citation - -Pangram Labs. (2026). N-gram Analysis of AI-Generated vs Human Writing. Pangram Labs research. - -## Source Type - -Industry Research - -## Method - -N-gram Statistical Analysis - -## Verification Status - -Unverified (industry data, not peer-reviewed) - -## Confidence - -Medium - -## Key Insight - -N-gram level analysis reveals that AI writing is detectable not just through individual word frequencies but through characteristic word combinations and phrase structures that form statistically distinct patterns from human writing. - -## Core Findings - -1. **N-gram signatures**: AI text exhibits characteristic n-gram (2-3 word combination) patterns that differ statistically from human writing beyond what single-word analysis captures. -2. **Multifaceted as marker**: "multifaceted" identified as 28x overrepresented in AI text through n-gram analysis. -3. **Phrase-level detection**: Detection accuracy improves when analyzing word combinations rather than individual words alone. -4. **Complementary to single-word analysis**: N-gram analysis catches patterns that single-word frequency analysis misses, particularly hedging constructions and formulaic transitions. - -## Mechanism - -LLMs generate text through next-token prediction, which creates statistical regularities at the phrase level (bigrams, trigrams) that are more distinctive than individual word choices. The model's tendency to use "safe" transitional phrases and hedging constructions creates n-gram patterns that are statistically unusual in human writing but consistently present in AI output. - -## Relevance - -Provides the phrase-level detection methodology that complements single-word frequency analysis. Essential for building multi-level AI writing detection systems that look beyond vocabulary to structural patterns. - -## Related Research - -- WriteHuman 2026 analysis: large-scale pair dataset with trigram-level findings -- TextVisualization.app corpus analysis: single-word frequency ratios -- Scientometrics delve study (2024): RLHF annotation bias mechanism diff --git a/docs/research/computer-science/artificial-intelligence/scientometrics_delve_2024.md b/docs/research/computer-science/artificial-intelligence/scientometrics_delve_2024.md deleted file mode 100644 index 57302db3..00000000 --- a/docs/research/computer-science/artificial-intelligence/scientometrics_delve_2024.md +++ /dev/null @@ -1,46 +0,0 @@ -# Scientometrics "Delve" Study (2024) - -## Citation - -Lund, B. D., Wang, T., Mannuru, N. R., Nie, B., Shimray, S., & Wang, Z. (2024). "The history and future of AI-generated text: A bibliometric analysis of PubMed abstracts." *Scientometrics*, Springer. (PubMed frequency spike analysis) - -## Source Type - -Academic Paper - -## Method - -Bibliometric Analysis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The word "delve" appeared 48x more often in AI-generated text than human-written text, with a measurable spike in PubMed abstracts post-2023 traceable to RLHF annotation bias from Nigerian annotators where "delve" is common in business English. - -## Core Findings - -1. **48x overrepresentation**: "delve" appears 48 times more frequently in AI-generated text compared to human baselines. -2. **PubMed spike**: Measurable increase in "delve" usage in PubMed abstracts after 2023, corresponding to widespread LLM adoption in academic writing. -3. **RLHF annotation origin**: The overrepresentation was traced to RLHF annotation bias. Many annotators were from Nigeria where "delve" is common in business English, creating a selection bias that amplified the word globally across LLM output. -4. **Bibliometric methodology**: The study used large-scale bibliometric analysis of academic abstracts to quantify the vocabulary shift, providing concrete evidence of LLM influence on academic writing. - -## Mechanism - -RLHF (Reinforcement Learning from Human Feedback) trains models to prefer outputs rated highly by human annotators. When the annotator pool has regional language patterns (e.g., Nigerian business English favoring "delve"), the model learns to produce those patterns regardless of context. The selection bias is then amplified through the reward model, making the pattern universal across all LLM output rather than regionally confined. - -## Relevance - -Provides the canonical case study for how RLHF annotation bias creates vocabulary overrepresentation in LLM output. The "delve" story illustrates the broader mechanism: training data composition + annotator demographics + reward model amplification = statistically detectable vocabulary markers. This mechanism generalizes to all Tier 1 AI writing markers. - -## Related Research - -- WriteHuman 2026 analysis: current-generation overrepresentation patterns from 80K+ pair dataset -- TextVisualization.app corpus analysis: quantified many additional single-word ratios (breathtaking: 36,261x; vibrant: 1,260x) -- Pangram Labs n-gram research: n-gram level detection methodology diff --git a/docs/research/computer-science/artificial-intelligence/textvisualization_corpus.md b/docs/research/computer-science/artificial-intelligence/textvisualization_corpus.md deleted file mode 100644 index c794f372..00000000 --- a/docs/research/computer-science/artificial-intelligence/textvisualization_corpus.md +++ /dev/null @@ -1,48 +0,0 @@ -# TextVisualization.app Corpus Analysis (AI vs Human Word Frequency) - -## Citation - -TextVisualization.app. (2026). AI vs Human Writing: Large-Scale Corpus Frequency Analysis. TextVisualization.app tool and corpus. - -## Source Type - -Corpus Analysis Tool - -## Method - -Corpus Statistical Analysis - -## Verification Status - -Unverified (tool-generated data, methodology not peer-reviewed) - -## Confidence - -Medium - -## Key Insight - -Large-scale corpus comparison reveals extreme single-word frequency ratios between AI and human writing, with the most overrepresented words (breathtaking: 36,261x; vibrant: 1,260x; intricate: 115x; testament: 228x; tapestry: 25-35x) being virtually diagnostic of AI generation. - -## Core Findings - -1. **breathtaking**: 36,261x more common in AI corpus than human corpus. The single most overrepresented word in the analysis. -2. **vibrant**: 1,260x more common in AI corpus. -3. **testament**: 228x more common in AI corpus. -4. **intricate**: 115x more common in AI corpus. -5. **tapestry**: 25-35x more common in AI corpus. -6. **Frequency distribution**: The overrepresentation follows a power-law distribution. A small number of words have extreme ratios (1000x+) while most markers cluster in the 9-50x range. - -## Mechanism - -The extreme ratios suggest these words appear in specific genres (tourism, marketing, academic writing) that are heavily represented in LLM training data. When the model draws from these genres for general-purpose writing, the vocabulary leaks into contexts where humans would use simpler alternatives. The 36,261x ratio for "breathtaking" suggests near-zero human usage in the comparison corpus but consistent AI deployment as a positive intensifier. - -## Relevance - -Provides the most extreme single-word frequency ratios available, establishing the upper bound of AI vocabulary overrepresentation. These ratios are useful as high-confidence individual markers. Any text containing "breathtaking" used as a general intensifier is almost certainly AI-generated. - -## Related Research - -- WriteHuman 2026 analysis: phrase and construction-level patterns from 80K+ pairs -- Pangram Labs n-gram research: n-gram level detection methodology -- Scientometrics delve study (2024): RLHF annotation bias as root cause diff --git a/docs/research/computer-science/artificial-intelligence/writehuman_2026.md b/docs/research/computer-science/artificial-intelligence/writehuman_2026.md deleted file mode 100644 index 48767329..00000000 --- a/docs/research/computer-science/artificial-intelligence/writehuman_2026.md +++ /dev/null @@ -1,49 +0,0 @@ -# WriteHuman AI Writing Analysis (80,141 Pairs) (2026) - -## Citation - -WriteHuman. (2026). AI Writing Detection and Humanization Analysis: 80,141 AI-to-Human Text Pairs. WriteHuman platform analysis. - -## Source Type - -Industry Analysis - -## Method - -Corpus Analysis - -## Verification Status - -Unverified (industry data, not peer-reviewed) - -## Confidence - -Medium - -## Key Insight - -Analysis of 80,141 AI-to-human text pairs reveals that hedging verbs ("ensuring/ensures", "highlights", "supports", "reflects") and specific constructions ("rather than" at 2.5x, "capable of" as highest-leverage swap) are the strongest 2026 signals of AI-generated text. - -## Core Findings - -1. **Hedging verb overrepresentation**: "ensuring/ensures" appears 4.3x more often in AI text. "highlights", "supports", "reflects" are the top hedging verbs distinguishing AI from human writing. -2. **"rather than" as discriminator**: 17,251 occurrences in AI text vs 6,859 in human text (2.5x overrepresentation), making it one of the strongest single-phrase signals. -3. **"capable of" vs "able to"**: The single highest-leverage humanization swap in the dataset. AI consistently uses "capable of" where humans use "able to". -4. **Formulaic trigram**: "X plays a crucial/critical/important role in shaping Y" is statistically the most formulaic trigram in the dataset. -5. **Em dash overuse**: 18.5% of AI inputs contain ≥1 em dash vs 7.1% of human text (2.6x). AI uses 1 per 50-80 words vs human 1 per 500 words. -6. **Intensifier adverbs**: "significantly", "effectively", "directly", "increasingly" are top-tier signals in 2026 data. - -## Mechanism - -The overrepresentation patterns emerge from RLHF training where human reviewers consistently prefer formal, hedged, "balanced" language. Each round of preference training amplifies these patterns. The "capable of" preference likely stems from academic and formal training corpus dominance, while hedging verbs reflect the model's tendency to qualify and soften claims rather than state them directly. - -## Relevance - -Provides the empirical foundation for identifying AI-generated text in 2026. The 80,141 pair dataset is one of the largest humanization benchmarks available and captures current-generation LLM output patterns. Essential for any system that needs to distinguish AI from human writing or that generates text intended to read naturally. - -## Related Research - -- TextVisualization.app corpus analysis: single-word frequency ratios from large-scale corpus comparison -- Pangram Labs n-gram research: n-gram level AI writing detection -- Scientometrics delve study (2024): origin of specific vocabulary overrepresentation through RLHF bias -- Wikipedia "Signs of AI writing": community-maintained catalogue of AI writing markers diff --git a/docs/research/design/accessibility/w3c_wcag21_2018.md b/docs/research/design/accessibility/w3c_wcag21_2018.md deleted file mode 100644 index d8606fdd..00000000 --- a/docs/research/design/accessibility/w3c_wcag21_2018.md +++ /dev/null @@ -1,48 +0,0 @@ -# Web Content Accessibility Guidelines 2.1 (W3C, 2018) - -## Citation - -W3C. (2018). *Web Content Accessibility Guidelines (WCAG) 2.1*, W3C Recommendation 5 June 2018. https://www.w3.org/TR/WCAG21/ - -## Source Type - -Industry Standard - -## Method - -Specification - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Text and images of text must have a contrast ratio of at least 4.5:1 against their background (Level AA) to ensure readability for users with visual impairments, including low vision and color blindness. - -## Core Findings - -1. **Contrast requirements**: Normal text requires 4.5:1 contrast (AA) or 7:1 (AAA); large text (18pt+ or 14pt+ bold) requires 3:1 (AA) or 4.5:1 (AAA). -2. **Four principles framework**: Web content must be perceivable, operable, understandable, and robust (POUR). -3. **Three conformance levels**: A (minimum), AA (standard target), AAA (enhanced) with 61 success criteria total in WCAG 2.1. -4. **Legal adoption worldwide**: WCAG 2.1 AA is legally mandated by EU Web Accessibility Directive, US Section 508, and many national laws. -5. **Calculation formula**: Contrast ratio = (L1 + 0.05) / (L2 + 0.05) where L1 is lighter color's relative luminance, L2 is darker. -6. **Exemptions**: Incidental text, logotypes, and inactive UI components are exempt from contrast requirements. -7. **New 2.1 criteria**: Added 17 new success criteria focused on mobile accessibility, low vision, and cognitive disabilities. - -## Mechanism - -Relative luminance is computed from sRGB values via gamma correction: for each RGB channel, divide by 255, then apply gamma function (≤ 0.04045 divide by 12.92; > 0.04045 use ((V + 0.055) / 1.055)^2.4), then combine as L = 0.2126×R + 0.7152×G + 0.0722×B. The contrast ratio formula produces values from 1:1 (identical colors) to 21:1 (black on white). This mathematical approach ensures consistent, measurable accessibility standards. - -## Relevance - -Essential standard for web accessibility compliance and legal requirements globally. Critical for brand palette design, interface color systems, and any digital content requiring inclusive design. Directly applicable to color contrast validation, automated accessibility testing, and design system documentation. Required for government, education, and increasingly private sector websites. - -## Related Research - -- (Albers, 1963): Color theory foundations showing why contrast relationships matter more than absolute colors -- (EN 301 549, 2014): European standard incorporating WCAG requirements for ICT accessibility \ No newline at end of file diff --git a/docs/research/design/visual/airey_2010.md b/docs/research/design/visual/airey_2010.md deleted file mode 100644 index 166587f5..00000000 --- a/docs/research/design/visual/airey_2010.md +++ /dev/null @@ -1,48 +0,0 @@ -# Logo Design Love (Airey, 2010) - -## Citation - -Airey, D. (2010). *Logo Design Love: A Guide to Creating Iconic Brand Identities*. New Riders. ISBN 978-0-321-66436-3. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Strong logos have one dominant feature, not two, three, or four. The design process must be monochrome-first to focus on the core idea. - -## Core Findings - -1. **Single dominant feature rule**: Effective logos have exactly one memorable element that viewers can identify and recall. -2. **Monochrome-first methodology**: Color should be added only after the black-and-white shape proves its strength and recognition. -3. **Systematic stress-testing**: Five evaluation checkpoints ensure logo robustness across contexts: 5-second test, blur test, scalability test, monochrome test, proximity test. -4. **Written brief requirement**: No design work should proceed without documented project parameters and goals. -5. **Iterative refinement process**: 20-40 rough concepts narrowed to 3-5 for vector refinement before color application. -6. **Appropriateness over novelty**: Logo style should match the brand's personality and context rather than following design trends. -7. **Scalability imperative**: Logos must work effectively from 16px favicon size to 500px+ display applications. - -## Mechanism - -Airey's process follows explicit checkpoints: (1) written brief before sketching, (2) 20-40 rough concepts in black ink on paper, (3) select top 3-5 and refine in vector format, (4) add color only after monochrome shape proves strong, (5) stress-test across sizes and backgrounds. The "one thing" test eliminates designs with competing elements. Each evaluation method targets specific failure modes: blur test catches detail-dependent designs, scalability test reveals breakdown points, proximity test ensures differentiation from competitors. - -## Relevance - -Essential methodology for brand identity design, startup logo creation, and visual identity systems. The stress-testing framework applies to any visual design requiring recognition across contexts. Monochrome-first principle prevents common failures in digital interfaces where color may not be available (accessibility, printing, small sizes). - -## Related Research - -- (Rand, 1985): Foundational principles of logo simplicity and testing methods -- (Wertheimer, 1923): Gestalt principles underlying logo recognition and memorability \ No newline at end of file diff --git a/docs/research/design/visual/albers_1963.md b/docs/research/design/visual/albers_1963.md deleted file mode 100644 index 8774033f..00000000 --- a/docs/research/design/visual/albers_1963.md +++ /dev/null @@ -1,48 +0,0 @@ -# Interaction of Color (Albers, 1963) - -## Citation - -Albers, J. (1963). *Interaction of Color*. Yale University Press. ISBN 978-0-300-01846-8. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Color is the most relative medium in art. The same physical color is perceived differently depending on its surrounding colors and the quantity in which it appears. - -## Core Findings - -1. **Color relativity principle**: "Every perception of color is an illusion... we do not see colors as they really are. In our perception they alter one another." -2. **Context-dependent perception**: The same physical color appears dramatically different when surrounded by different colors or used in different proportions. -3. **Experiential learning approach**: Color is best studied through hands-on experimentation and observation rather than theoretical study alone. -4. **"Making one color appear as two"**: Albers' key exercise demonstrates that color perception is determined by relationships, not absolute values. -5. **Systematic color exploration**: The "Homage to the Square" series methodically explored chromatic interactions with nested squares across hundreds of works. -6. **Pedagogical methodology**: Prioritized experience over theory - "what counts is not so-called knowledge of so-called facts, but vision: seeing." -7. **Brand design implications**: Colors must be defined as relationships (contrast ratios, visual weight proportions) rather than fixed values applied without context. - -## Mechanism - -Albers' key exercise (making one color appear as two different colors by changing its surroundings) proves that color perception is determined by relationships, not absolute values. This has direct implications for brand design: an accent color that reads clearly on white may appear muddy on dark backgrounds, not because the accent changed, but because its relationship to the background changed. The actionable rule is to define brand colors as relationships (primary is always N× the visual weight of accent; text maintains ≥4.5:1 contrast) rather than fixed hex values applied without context. - -## Relevance - -Foundational for brand palette design, interface color systems, and accessibility guidelines. Essential for understanding why colors must be tested in context rather than isolation. Critical for digital design where the same color appears across various backgrounds, screen types, and lighting conditions. Directly applies to contrast ratios, color accessibility standards, and responsive design systems. - -## Related Research - -- (Land, 1977): Retinex theory of color constancy challenging some of Albers' assumptions -- (Jameson, 1985): Defense of Albers' pigment-based approach vs. theoretical color mixing \ No newline at end of file diff --git a/docs/research/design/visual/arnheim_1954.md b/docs/research/design/visual/arnheim_1954.md deleted file mode 100644 index 8fe17092..00000000 --- a/docs/research/design/visual/arnheim_1954.md +++ /dev/null @@ -1,48 +0,0 @@ -# Art and Visual Perception (Arnheim, 1954) - -## Citation - -Arnheim, R. (1954). *Art and Visual Perception: A Psychology of the Creative Eye*. University of California Press. (Revised edition 1974, ISBN 978-0-520-02623-5.) - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Visual shapes carry innate psychological meaning that is perceived instantly, before conscious thought. Circles are perceived as soft, unified, and complete; squares as stable, solid, and rational; triangles as dynamic, directional, and energetic. - -## Core Findings - -1. **Gestalt-based shape psychology**: Visual forms carry inherent meaning derived from their structural properties, not arbitrary cultural conventions. -2. **Circle associations**: Perceived as soft, unified, complete due to lack of edges and continuous form. -3. **Square associations**: Perceived as stable, solid, rational due to broad base and balanced structure. -4. **Triangle associations**: Perceived as dynamic, directional, energetic due to pointed direction and asymmetry. -5. **Visual force fields**: Off-center placement creates tension; angled placement adds dynamism by disrupting expected stability. -6. **Compositional principles**: Visual forces within compositions create perceived tension or calm based on geometric relationships. -7. **Simplicity rule**: The simplest geometric form expressing intended meaning is the most effective design solution. - -## Mechanism - -Arnheim demonstrated that shape perception follows Gestalt principles where "visual forces" within compositions create perceived tension or calm. A circle placed off-center creates visual tension because symmetry demands centering. A square at an angle creates dynamism by disrupting expected stability. Complex shapes combine meanings of their geometric primitives - reducing logos to geometric components reveals whether shape language is coherent or contradictory. - -## Relevance - -Foundational for logo design, visual identity systems, and interface design. Essential for understanding how geometric forms communicate brand personality and user expectations. Applied in icon design, where shape psychology determines immediate recognition and emotional response. Critical for any visual communication requiring instant psychological impact. - -## Related Research - -- (Wertheimer, 1923): Gestalt principles underlying visual perception -- (Rand, 1985): Practical application of simplicity principles in logo design \ No newline at end of file diff --git a/docs/research/design/visual/biederman_1987.md b/docs/research/design/visual/biederman_1987.md deleted file mode 100644 index 3c38eaa1..00000000 --- a/docs/research/design/visual/biederman_1987.md +++ /dev/null @@ -1,48 +0,0 @@ -# Recognition-by-Components (Biederman, 1987) - -## Citation - -Biederman, I. (1987). "Recognition-by-Components: A Theory of Human Image Understanding." *Psychological Review*, 94(2), 115–147. https://doi.org/10.1037/0033-295X.94.2.115 - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Humans recognize objects by decomposing them into simple geometric components called "geons" (geometric ions). Line drawings containing only essential edges are recognized as quickly as full-color photographs, proving that edge information alone is sufficient for rapid object recognition. - -## Core Findings - -1. **Geon-based recognition**: Approximately 36 basic 3-dimensional shapes (geons) can be combined to describe virtually all common objects we encounter. -2. **Edge primacy**: Line drawings with critical edges present are recognized as quickly and accurately as full-color photographs of the same objects. -3. **Viewpoint invariance**: Objects can be recognized from almost any viewing angle due to invariant edge properties of geons (curvature, parallel lines, co-termination, symmetry, co-linearity). -4. **Combinatorial power**: With just 24 geons, there are 306 billion possible combinations of 3 geons, allowing recognition of virtually unlimited objects. -5. **Speech analogy**: Just as ~44 phonemes create all English words, ~36 geons create all recognizable objects through systematic combination. -6. **Early development**: Geon recognition develops in infants as early as 4 months old, making it one of fundamental perceptual skills. -7. **Noise resistance**: Objects remain recognizable despite visual noise provided the constituent geons are visible. - -## Mechanism - -Biederman's experiments showed that recognition speed and accuracy were nearly identical for line drawings and full-color photographs of the same objects, provided critical edges were present. The visual system extracts edge-based structural descriptions (geon assemblies) as the primary recognition pathway, with color and texture serving only as secondary confirmation. For logo design, this provides perceptual science basis for monochrome-first design: if edges/silhouette carry the recognition signal, color and detail are secondary and can be added later without affecting core identifiability. - -## Relevance - -Foundational theory for understanding how visual recognition works, with direct applications to logo design, icon design, and visual identity systems. Provides scientific justification for monochrome-first design approaches and edge-based recognition. Essential for creating visual marks that work across scales, contexts, and viewing conditions. Critical for understanding why simple geometric shapes are most effective for brand symbols. - -## Related Research - -- (Wertheimer, 1923): Gestalt principles that complement geon-based recognition -- (Kare, 1984): Practical application of edge-based recognition in icon design \ No newline at end of file diff --git a/docs/research/design/visual/hicks_2011.md b/docs/research/design/visual/hicks_2011.md deleted file mode 100644 index 7188e130..00000000 --- a/docs/research/design/visual/hicks_2011.md +++ /dev/null @@ -1,47 +0,0 @@ -# The Icon Handbook (Hicks, 2011) - -## Citation - -Hicks, J. (2011). *The Icon Handbook*. Five Simple Steps. ISBN 978-1-907828-00-3. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Icons must be designed at the smallest target size first and then scaled up, adding detail only at larger sizes. - -## Core Findings - -1. **Progressive simplification methodology**: Create separate pixel-perfect versions at each target size tier (16px, 24px, 32px, 48px, 128px, 256px, 512px) rather than scaling a single vector. -2. **Size-tier optimization**: At each tier, remove details that cannot be rendered at that resolution and exaggerate key features for clarity. -3. **Visual acuity limitations**: At 16×16 pixels, fine lines (under 2px), subtle gradients, and interior details vanish or create visual noise. -4. **Industry standard practice**: Progressive simplification is the standard methodology used by professional icon designers including major software companies. -5. **Firefox and Skype precedent**: Hicks' work on major brand icons demonstrates the effectiveness of this approach at scale. -6. **Downscaling failure**: Simply downscaling a 512px icon to 16px produces a muddy, unrecognizable mark that fails usability tests. - -## Mechanism - -Hicks' tier system works because human visual acuity is finite. At 16×16 pixels, fine lines (under 2px), subtle gradients, and interior details vanish or create visual noise. At 512×512, those same details add richness. Progressive simplification acknowledges this by treating each size tier as a distinct design problem: the 16px version is a hand-optimized silhouette, the 32px version may add one key interior detail, the 128px version adds secondary features, and the 512px version is the full design. - -## Relevance - -Essential methodology for any icon system, mobile app design, or interface requiring icons at multiple resolutions. Critical for responsive design systems, desktop applications, and brand identity systems that must work across various scales and contexts. Directly applicable to favicon design, app icon creation, and UI iconography. - -## Related Research - -- (Wertheimer, 1923): Gestalt principles that inform icon recognition at small sizes -- (Miller, 1956): Cognitive load implications of visual complexity in small-scale graphics \ No newline at end of file diff --git a/docs/research/design/visual/itten_1961.md b/docs/research/design/visual/itten_1961.md deleted file mode 100644 index 0d18e10d..00000000 --- a/docs/research/design/visual/itten_1961.md +++ /dev/null @@ -1,48 +0,0 @@ -# The Art of Color (Itten, 1961) - -## Citation - -Itten, J. (1961). *The Art of Color: The Subjective Experience and Objective Rationale of Color*. Reinhold Publishing. ISBN 978-0-442-24037-6. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Color interaction is relational. The same hue appears different depending on its neighbors. Itten's seven contrast types provide a systematic framework for predicting how colors will read in context. - -## Core Findings - -1. **Seven color contrasts framework**: (1) contrast of hue, (2) light-dark contrast, (3) cold-warm contrast, (4) complementary contrast, (5) simultaneous contrast, (6) contrast of saturation, (7) contrast of extension (proportion). -2. **Relational color perception**: Same physical color appears different depending on surrounding colors and proportions - colors cannot be judged in isolation. -3. **Light-dark contrast supremacy**: The strongest contrast foundation - creates clarity, drama, and legibility. Forms basis of accessibility guidelines (4.5:1 contrast ratios). -4. **Complementary contrast power**: Opposite hues create maximum visual tension and vibrancy, but risk uncomfortable vibration at similar saturation levels. -5. **Simultaneous contrast effect**: Neutral colors shift toward the complement of their background (grey on red appears greenish). -6. **Proportional color weight**: Visual weight depends on area and inherent brightness - yellow is "heavier" than equal-area violet (proportion ratios: yellow:violet ≈ 1:3). -7. **Contextual color testing requirement**: Brand colors must be evaluated in actual usage contexts, not in isolation. - -## Mechanism - -Itten identified seven contrasts as foundation of color composition. The most actionable for brand design: **complementary contrast** creates maximum visual tension between opposite hues; **simultaneous contrast** makes neutrals shift toward complement of their background. Each contrast produces different emotional effects from calm (analogous, low contrast) to vibrant (complementary, high contrast). Colors must be defined as relationships rather than absolute values. - -## Relevance - -Foundational for brand palette design, interface color systems, and accessibility guidelines. Essential for understanding why colors must be tested in context rather than isolation. Directly applies to contrast ratios, WCAG accessibility standards, and responsive design systems where colors appear across various backgrounds and contexts. - -## Related Research - -- (Albers, 1963): Further development of color interaction principles focusing on pigment-based relationships -- (Chevreul, 1839): Early simultaneous contrast observations that influenced Itten's work \ No newline at end of file diff --git a/docs/research/design/visual/kare_1984.md b/docs/research/design/visual/kare_1984.md deleted file mode 100644 index eb1682b5..00000000 --- a/docs/research/design/visual/kare_1984.md +++ /dev/null @@ -1,47 +0,0 @@ -# Macintosh Icon Design (Kare, 1984) - -## Citation - -Kare, S. (1984). Original Macintosh icon designs. Museum of Modern Art (MoMA), New York. Documented in: Kindy, D. (2019). "How Susan Kare Designed User-Friendly Icons for the First Macintosh." *Smithsonian Magazine*. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Icons designed at the smallest target size first, on a pixel grid, are more recognizable and enduring than icons designed at large size and scaled down. - -## Core Findings - -1. **Pixel-perfect methodology**: Kare designed all original Macintosh icons on a 32×32 pixel grid using graph paper, working at exact output resolution before touching software. -2. **"Favicon-first" principle**: If a mark cannot hold its identity at 16×16 or 32×32 pixels, it is not strong enough for any size. -3. **Constraint-driven design**: At 32×32 (1,024 pixels, monochrome), there is no room for decoration. Each pixel must contribute to recognition. -4. **Enduring recognition**: Her icons remain instantly recognizable 40+ years later because every pixel carried meaning. -5. **Metaphor-driven approach**: Icons were inspired by art history, Japanese logograms, hieroglyphics, and real-world objects to create instant recognition. -6. **Progressive simplification**: Detail that does not read at the smallest size should not exist in the core design. - -## Mechanism - -Kare's methodology (designing on the smallest graph paper she could find, composing each icon at its actual pixel resolution before touching software) enforces progressive simplification by constraint. Working within severe technological constraints (32×32 pixels, monochrome) made her an early pioneer of pixel art, drawing from her fine art experience in mosaics, needlepoint, and pointillism. This "peculiar sort of minimal pointillism" required solving recognition problems with only horizontal, vertical, or 45-degree lines. - -## Relevance - -Foundational methodology for icon design across all digital interfaces. Established the principle that icons must work at their smallest intended size first. Essential for favicon design, mobile app icons, and any interface requiring recognizable symbols at multiple scales. Her approach directly influences modern icon design systems and responsive iconography. - -## Related Research - -- (Hicks, 2011): Modern application of progressive simplification principles in "The Icon Handbook" -- (Wertheimer, 1923): Gestalt principles that inform instant icon recognition \ No newline at end of file diff --git a/docs/research/design/visual/lupton_2010.md b/docs/research/design/visual/lupton_2010.md deleted file mode 100644 index 39f94e72..00000000 --- a/docs/research/design/visual/lupton_2010.md +++ /dev/null @@ -1,47 +0,0 @@ -# Thinking with Type (Lupton, 2010) - -## Citation - -Lupton, E. (2010). *Thinking with Type: A Critical Guide for Designers, Writers, Editors, & Students* (2nd ed.). Princeton Architectural Press. ISBN 978-1-56898-969-3. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Typography is a system of relationships: between letterforms, between text and space, between type and image. For branding, three typographic choices carry the most personality signal: serif vs sans-serif (traditional/authoritative vs modern/approachable), weight (light/delicate vs bold/assertive), and spacing/tracking (tight/urgent vs open/relaxed). - -## Core Findings - -1. **Serif vs. sans-serif psychology**: Serif typefaces (Times, Garamond, Georgia) carry centuries of association with authority, tradition, and print culture, while sans-serif faces (Helvetica, Futura, Inter) signal modernity, clarity, and directness. -2. **Readability considerations**: Serifs create horizontal rhythm that guides the eye along lines, making serif text more readable at small sizes in long passages. -3. **Logo scalability**: Sans-serif faces dominate in logo marks because they survive reduction to small sizes better than serifs. Fine serif details become visual noise at favicon sizes. -4. **Weight as personality lever**: A single typeface at light weight with generous tracking feels elegant and premium; the same typeface at bold weight with tight tracking feels urgent and powerful. -5. **Spacing psychology**: Tight tracking conveys urgency and intensity, while generous tracking suggests luxury and thoughtfulness. -6. **Systematic flexibility**: For brand systems, Lupton recommends sans-serif families with wide weight ranges (300-700) for maximum flexibility from single typeface choices. - -## Mechanism - -Typography functions as a visual language where formal qualities communicate before content is read. Serif typefaces leverage historical associations with authority and permanence, while their horizontal flow aids sustained reading. Sans-serif typefaces eliminate decorative elements to emphasize pure form and modernity. Weight and spacing act as volume controls for typographic voice. Lighter weights whisper, bolder weights shout, tight spacing creates urgency, loose spacing creates calm. These relationships work pre-cognitively, making typographic choices powerful tools for brand personality expression. - -## Relevance - -Essential framework for brand identity design, web typography, and interface design. Critical for understanding how typographic choices communicate brand personality before users read content. Directly applicable to logo design, UI typography, marketing materials, and any system requiring consistent typographic voice across multiple touchpoints. - -## Related Research - -- (Wertheimer, 1923): Gestalt principles that inform typographic hierarchy and spacing -- (Bringhurst, 2004): Classical typography principles and historical context \ No newline at end of file diff --git a/docs/research/design/visual/muller_brockmann_1981.md b/docs/research/design/visual/muller_brockmann_1981.md deleted file mode 100644 index bf46cca8..00000000 --- a/docs/research/design/visual/muller_brockmann_1981.md +++ /dev/null @@ -1,47 +0,0 @@ -# Grid Systems in Graphic Design (Müller-Brockmann, 1981) - -## Citation - -Müller-Brockmann, J. (1981). *Grid Systems in Graphic Design: A Visual Communication Manual for Graphic Designers, Typographers, and Three Dimensional Designers* (4th ed.). Arthur Niggli. ISBN 978-3-7212-0145-1. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -A grid provides the rational structure upon which creative work becomes legible, ordered, and balanced, producing visual order that the viewer perceives as clarity and competence even without consciously recognizing the grid. - -## Core Findings - -1. **Grid-based composition principles**: Grid systems create visual order that viewers subconsciously recognize as professional and trustworthy, even when they cannot identify the underlying structure. -2. **Rule of thirds effectiveness**: The 3×3 grid creates four natural focal points at intersections where the eye is drawn preferentially over the center. -3. **Golden ratio applications**: The golden ratio (1:1.618) produces naturally pleasing asymmetric balance with the "golden point" at roughly 62% from left, 38% from top. -4. **Dynamic vs. static positioning**: Placing primary elements at intersection points creates dynamic tension; centered compositions create calm stability but risk appearing static. -5. **Constraint liberation principle**: The grid constrains placement but liberates proportion - elements can be large/small, bold/light within the rational structure. -6. **Swiss design methodology**: Müller-Brockmann's International Typographic Style demonstrated that systematic approaches produce more effective communication than intuitive placement. - -## Mechanism - -The rule of thirds divides a canvas into 9 equal zones (3 columns × 3 rows). The four intersections are natural focal points. The eye is drawn to them preferentially over the center. Placing the primary mark at an upper-third intersection and secondary elements along the lower third creates dynamic tension. A centered composition (mark at dead center) creates calm and stability but risks feeling static. Müller-Brockmann's key rule: the grid constrains placement but liberates proportion. Within a grid, elements can be large or small, bold or light. The grid ensures they relate to each other rationally. Without a grid, elements appear arbitrary and the composition feels disorganized regardless of individual element quality. - -## Relevance - -Foundational methodology for all layout design, logo positioning, and visual composition. Essential for creating professional, trustworthy visual communications across print, digital, and environmental design. Critical for brand identity systems, web design, publication design, and any visual communication requiring systematic organization and hierarchy. - -## Related Research - -- (Wertheimer, 1923): Gestalt principles that inform grid-based visual organization -- (Rand, 1985): Application of grid principles to logo and identity design \ No newline at end of file diff --git a/docs/research/design/visual/rand_1985.md b/docs/research/design/visual/rand_1985.md deleted file mode 100644 index 2710188d..00000000 --- a/docs/research/design/visual/rand_1985.md +++ /dev/null @@ -1,46 +0,0 @@ -# A Designer's Art (Rand, 1985) - -## Citation - -Rand, P. (1985). *Paul Rand: A Designer's Art*. Yale University Press. ISBN 978-0-300-03242-6. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -A logo cannot survive unless it is designed with the utmost simplicity and restraint. - -## Core Findings - -1. Strong logos must work in monochrome first. Color is added only after the shape proves its identity in black and white. -2. Logos should be tested by blurring and degrading them to verify they remain recognizable under poor conditions. -3. "Ideas do not need to be esoteric to be original or exciting." Simplicity does not mean lack of sophistication. -4. The most enduring corporate marks are those reducible to the fewest recognizable elements. -5. A logo must function across all applications: small sizes, poor printing, different backgrounds, and various media. - -## Mechanism - -Rand's design process was explicitly monochrome-first: design in black and white, test under degraded conditions, then add color only when the shape is proven. The blur test applies Gaussian blur to probe whether the global silhouette carries recognition independent of detail. If the blurred mark remains identifiable, the shape is strong; if not, it relies too much on detail and will fail at small sizes or poor reproduction quality. - -## Relevance - -Foundational methodology for logo design and brand identity systems. The monochrome-first approach and stress-testing principles directly apply to creating robust visual identities that work across all contexts and scales. Essential for preventing late-stage failures when implementing brand systems. - -## Related Research - -- (Airey, 2010): Contemporary application of Rand's principles in Logo Design Love -- (Arnheim, 1954): Psychological foundations of visual perception that inform Rand's approach \ No newline at end of file diff --git a/docs/research/design/visual/wertheimer_1923.md b/docs/research/design/visual/wertheimer_1923.md deleted file mode 100644 index bcb14840..00000000 --- a/docs/research/design/visual/wertheimer_1923.md +++ /dev/null @@ -1,48 +0,0 @@ -# Laws of Organization in Perceptual Forms (Wertheimer, 1923) - -## Citation - -Wertheimer, M. (1923). "Laws of Organization in Perceptual Forms." *Psychologische Forschung*, 4, 301–350. Translated in: Ellis, W.D. (ed.), *A Source Book of Gestalt Psychology*, 1938. - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The human visual system automatically organizes visual elements into coherent groups using hardwired perceptual principles that operate pre-attentively, making them the most powerful tool for creating instantly recognizable visual designs. - -## Core Findings - -1. **Proximity principle**: Elements close together are perceived as belonging to one group - the strongest grouping force. -2. **Similarity principle**: Elements sharing color, shape, or size are visually grouped together, even when scattered. -3. **Closure principle**: The mind fills in gaps to perceive complete shapes from incomplete visual information. -4. **Figure-ground separation**: Elements are automatically perceived as either foreground objects or background context. -5. **Continuation principle**: The eye follows the smoothest path through intersecting lines and curves. -6. **Pre-attentive processing**: These organizational principles operate before conscious thought, making them universally reliable. -7. **Simplicity preference**: Given visual elements, the brain imposes the simplest stable structure it can perceive. - -## Mechanism - -Wertheimer demonstrated that perceptual organization is hardwired, not learned. Given visual elements, the brain automatically imposes the simplest stable structure. Proximity grouping dominates (closest elements group first), followed by similarity grouping. Closure allows the brain to complete partial shapes automatically. Figure-ground separation makes elements stand out from backgrounds without conscious effort. For design, this means simplifying shapes until Gestalt grouping takes over - the viewer's brain will complete forms more reliably than added detail. - -## Relevance - -Foundational for all visual design, user interface design, and logo creation. Essential for creating layouts that group related information automatically, icons that remain recognizable at any size, and visual hierarchies that guide attention without conscious effort. Critical for any design requiring instant visual organization and recognition. - -## Related Research - -- (Arnheim, 1954): Application of Gestalt principles to art and visual perception -- (Köhler, 1920): Gestalt psychology's figure-ground and organizational principles \ No newline at end of file diff --git a/docs/research/information-science/documentation/procida_2021.md b/docs/research/information-science/documentation/procida_2021.md deleted file mode 100644 index 818fbb51..00000000 --- a/docs/research/information-science/documentation/procida_2021.md +++ /dev/null @@ -1,45 +0,0 @@ -# Diátaxis Documentation Framework (Procida, 2021) - -## Citation - -Procida, D. (2021). *Diátaxis: A systematic approach to technical documentation authoring*. https://diataxis.fr/ - -## Source Type - -Specification - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Technical documentation has four distinct modes organized along two axes (action vs cognition, acquisition vs application) - mixing modes in single document produces confusion. - -## Core Findings - -1. **Four Documentation Types**: Tutorial (learning-oriented), How-to guide (task-oriented), Reference (information-oriented), Explanation (understanding-oriented) -2. **Two-Axis Framework**: Action vs Cognition crossed with Acquisition vs Application creates systematic quadrant organization -3. **Mode Separation**: Each quadrant demands distinct writing approach - combining forces mental state switching in readers -4. **Practical Application**: Framework adopted successfully in hundreds of documentation projects including Gatsby, Cloudflare, Vonage -5. **Quality Principle**: Provides active principle for maintainers to think effectively about documentation work - -## Mechanism - -Two axes create systematic quadrant: Tutorials (learning-oriented, action + acquisition), How-to guides (task-oriented, action + application), Reference (information-oriented, cognition + application), Explanation (understanding-oriented, cognition + acquisition). Each quadrant requires different content approach, style, and architecture. - -## Relevance - -Essential for technical writing, documentation architecture, developer experience. Applied in software documentation, API guides, educational content. Foundational for organizing complex technical information systems and improving user documentation experience. - -## Related Research - -Created by Daniele Procida. Name from Ancient Greek διάταξις (diataxis): "dia" (across) + "taxis" (arrangement). Adopted by major tech companies and open-source projects. Addresses content (what to write), style (how to write), architecture (how to organize) problems in technical documentation. diff --git a/docs/research/information-science/domain-modeling/brandolini_2012.md b/docs/research/information-science/domain-modeling/brandolini_2012.md deleted file mode 100644 index 300e23f8..00000000 --- a/docs/research/information-science/domain-modeling/brandolini_2012.md +++ /dev/null @@ -1,45 +0,0 @@ -# Event Storming (Brandolini, 2012) - -## Citation - -Brandolini, A. (2012–present). *Event Storming*. eventstorming.com. Originally developed as "Event-based modelling" circa 2012; refined and published through workshops and online resources. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Start with what the business cares about (events that happened) rather than data structures or process flows to discover domain boundaries collaboratively. - -## Core Findings - -1. **Event-First Approach**: Begin with domain events (past-tense, business-relevant verbs) placed on timeline -2. **Collaborative Discovery**: Visual, tactile format (sticky notes) lowers barrier for non-technical stakeholder participation -3. **Natural Boundary Detection**: Grouping events and commands surfaces bounded context boundaries where terms change meaning -4. **Multiple Flavors**: Improve existing business, envision startup ecosystem, explore new services, design critical software -5. **Temporal Dependencies**: Placing events on timeline reveals causal chains and business flow patterns - -## Mechanism - -EventStorming works by starting with business-relevant events rather than technical structures. Participants naturally discover temporal dependencies and causal chains by placing events chronologically. Commands reveal intent; aggregates reveal consistency boundaries. The visual format enables cross-discipline conversation between stakeholders with different backgrounds, delivering collaboration beyond silo boundaries. - -## Relevance - -Essential for Domain-Driven Design, collaborative domain modeling, microservices architecture design. Applied in startup ecosystem exploration, business process improvement, software design workshops. Fundamental for breaking down silos between business and technical teams in complex domain discovery. - -## Related Research - -Connects to (Evans, 2003) on Domain-Driven Design principles, (Vernon, 2013) on implementing DDD. Part of broader collaborative modeling approaches alongside Design Thinking and Lean Startup methodologies. Related to workshop facilitation techniques and business process modeling frameworks. \ No newline at end of file diff --git a/docs/research/information-science/domain-modeling/evans_2003.md b/docs/research/information-science/domain-modeling/evans_2003.md deleted file mode 100644 index c4a02c87..00000000 --- a/docs/research/information-science/domain-modeling/evans_2003.md +++ /dev/null @@ -1,45 +0,0 @@ -# Domain-Driven Design (Evans, 2003) - -## Citation - -Evans, E. (2003). *Domain-Driven Design: Tackling Complexity in the Heart of Software*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Complex software must be built around shared domain model - a ubiquitous language used by both domain experts and developers in conversation, code, and documentation. - -## Core Findings - -1. **Ubiquitous Language**: Single terminology shared between domain experts and developers eliminates translation costs and catches misunderstandings early -2. **Bounded Contexts**: Define where terms have single meaning, preventing incoherent unified models when terms mean different things in different subdomains -3. **Aggregates**: Define transactional consistency boundaries - all invariants within aggregate must hold after each operation -4. **Context Mapping Patterns**: Upstream/Downstream, Anti-corruption Layer, Conformist, Open-host Service define how separate bounded contexts interact -5. **Strategic vs. Tactical Design**: Strategic focuses on bounded contexts and context mapping; tactical focuses on entities, value objects, services - -## Mechanism - -Ubiquitous language eliminates translation costs between domain experts and developers. When "Order" means same thing in conversation and code, misunderstandings are caught early. Bounded contexts prevent alternative unified model becoming incoherent. Aggregates enforce transactional consistency boundaries with operations spanning aggregates accepting eventual consistency. - -## Relevance - -Essential for complex software architecture, microservices design, team organization, domain modeling. Applied in enterprise software development, distributed systems architecture. Foundational for strategic system design aligning technical implementation with business domains and expert knowledge. - -## Related Research - -Connects to (Brandolini, 2012) on Event Storming for domain discovery, (Vernon, 2013) on DDD implementation. Part of broader software architecture approaches alongside microservices, CQRS, event sourcing. Related to Conway's Law and team topologies for organizational design. \ No newline at end of file diff --git a/docs/research/information-science/domain-modeling/vernon_2013.md b/docs/research/information-science/domain-modeling/vernon_2013.md deleted file mode 100644 index 84d43fd5..00000000 --- a/docs/research/information-science/domain-modeling/vernon_2013.md +++ /dev/null @@ -1,45 +0,0 @@ -# Implementing Domain-Driven Design (Vernon, 2013) - -## Citation - -Vernon, V. (2013). *Implementing Domain-Driven Design*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Context mapping provides nine inter-context relationship patterns describing how bounded contexts relate to each other, preventing model pollution and reducing integration friction. - -## Core Findings - -1. **Nine Context Mapping Patterns**: Shared Kernel, Customer-Supplier, Conformist, Anticorruption Layer, Separate Ways, Open Host Service, Published Language, Big Ball of Mud, Partnership -2. **Relationship Trade-offs**: Each pattern carries specific coordination costs and risk implications requiring careful selection -3. **Pattern Selection Guidance**: Use ACL when downstream has limited influence; Customer-Supplier when teams can negotiate; Open Host Service for many standardized consumers -4. **Social Contract Explicit**: Context maps make team relationships, obligations, and constraints transparent -5. **Practical DDD Implementation**: Extends Evans' foundational work with concrete implementation patterns and guidance - -## Mechanism - -Context mapping makes social and technical contracts between teams explicit. Customer-Supplier demands upstream awareness; Conformist accepts upstream dominance; Anticorruption Layer isolates from model drift. Named relationships clarify obligations and constraints, preventing accidental coupling and model contamination. - -## Relevance - -Essential for microservices architecture, distributed systems design, team organization. Applied in bounded context definition, API design, organizational patterns. Critical for implementing DDD at scale in complex enterprise environments with multiple development teams. - -## Related Research - -Vaughn Vernon builds on (Evans, 2003) foundational DDD work. Author of "Reactive Messaging Patterns with the Actor Model" (2015), "Domain-Driven Design Distilled" (2016). Leading DDD practitioner and educator providing concrete implementation guidance for Evans' theoretical framework. diff --git a/docs/research/psychology/cognitive/craik_lockhart_1972.md b/docs/research/psychology/cognitive/craik_lockhart_1972.md deleted file mode 100644 index 41133ec3..00000000 --- a/docs/research/psychology/cognitive/craik_lockhart_1972.md +++ /dev/null @@ -1,48 +0,0 @@ -# Levels of Processing (Craik & Lockhart, 1972) - -## Citation - -Craik, F. I. M., & Lockhart, R. S. (1972). "Levels of processing: A framework for memory research." *Journal of Verbal Learning and Verbal Behavior*, 11(6), 671–684. https://doi.org/10.1016/S0022-5371(72)80001-X - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Deeper processing, explaining *why* a rule matters, leads to better retention and application than shallow processing. Memory is a byproduct of the depth of cognitive processing, not repetition. - -## Core Findings - -1. **Three levels of processing**: Structural/visual (appearance), phonemic (sound), and semantic (meaning), with deeper levels producing stronger memory traces. -2. **Semantic processing superiority**: Information processed for meaning creates more durable memory traces than information processed for appearance or sound. -3. **Elaborative encoding advantage**: Adding semantic processing requirements (explaining rationale) improves both immediate compliance and long-term adherence. -4. **Contradiction of multi-store model**: Challenges Atkinson-Shiffrin model by showing that rehearsal type matters more than rehearsal amount. -5. **Self-reference effect enhancement**: Information relating to oneself receives the deepest processing and highest recall. -6. **Neural correlates**: Brain imaging shows increased left prefrontal cortex activity during semantic vs. shallow processing tasks. - -## Mechanism - -The "levels of processing" framework shows that semantic processing (meaning-based) creates stronger memory traces than phonetic (sound-based) or visual (appearance-based) processing. Forcing reviewers to explain why rules matter engages semantic processing, creating widespread activation in semantic networks through meaningful connections to existing knowledge. - -## Relevance - -Enforcement tables with "Why it matters" columns force elaborative encoding. Instead of superficial rule checking, reviewers must process the underlying rationale, leading to better internalization of design principles. Essential for any learning system requiring deep understanding rather than rote compliance. - -## Related Research - -- (Craik & Tulving, 1975): Empirical validation showing semantic encoding superiority in recall tasks -- (Hyde & Jenkins, 1973): Orienting tasks and incidental learning effects -- (Lockhart & Craik, 1990): Retrospective commentary on levels of processing framework \ No newline at end of file diff --git a/docs/research/psychology/cognitive/fisher_geiselman_1987.md b/docs/research/psychology/cognitive/fisher_geiselman_1987.md deleted file mode 100644 index 13312c65..00000000 --- a/docs/research/psychology/cognitive/fisher_geiselman_1987.md +++ /dev/null @@ -1,47 +0,0 @@ -# The Enhanced Cognitive Interview (Fisher & Geiselman, 1987) - -## Citation - -Fisher, R. P., & Geiselman, R. E. (1987). "Enhancing enhanced eyewitness memory: Refining the cognitive interview." *Journal of Police Science and Administration*, 15, 291-297. (Enhanced version of original 1984 cognitive interview) - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The enhanced Cognitive Interview elicits approximately 35% more correct information than standard interviews with equal accuracy rates. - -## Core Findings - -1. **Four retrieval mnemonics**: (1) Mental reinstatement of context, (2) Report everything, (3) Temporal reversal, (4) Perspective change - each opens different memory access routes. -2. **Enhanced version improvements**: 45% increase in correct information over original CI through better interview structure and social dynamics. -3. **Equal accuracy rates**: 85% accuracy for CI vs 82% for standard interviews - more information without sacrificing reliability. -4. **Encoding specificity leverage**: Context reinstatement increases memory availability by overlapping retrieval cues with original encoding conditions. -5. **Multi-component memory access**: Different retrieval routes surface information that direct questions cannot access. -6. **Field effectiveness**: Real police officers trained in CI gather significantly more accurate information from actual crime witnesses. - -## Mechanism - -Four retrieval mnemonics open different memory access routes, collectively surfacing what direct questions cannot reach. Mental reinstatement leverages encoding specificity principle - memories encoded with environmental/emotional context become accessible when similar context is recreated. "Report everything" and perspective changes tap the multi-component view of memory, accessing different aspects of the complex memory trace through alternative retrieval pathways. - -## Relevance - -Foundational technique for investigative interviewing, user research, and requirements gathering. Widely adopted by police departments, private investigators, and attorneys. The principles apply to any situation requiring complete information extraction: incident analysis, post-mortem reviews, and stakeholder interviews where comprehensive recall is essential. - -## Related Research - -- (Tulving & Thomson, 1973): Encoding specificity principle underlying context reinstatement -- (Flanagan, 1954): Critical incident technique as complementary approach to incident-based recall diff --git a/docs/research/psychology/cognitive/flanagan_1954.md b/docs/research/psychology/cognitive/flanagan_1954.md deleted file mode 100644 index b809e1b4..00000000 --- a/docs/research/psychology/cognitive/flanagan_1954.md +++ /dev/null @@ -1,47 +0,0 @@ -# The Critical Incident Technique (Flanagan, 1954) - -## Citation - -Flanagan, J. C. (1954). "The critical incident technique." *Psychological Bulletin*, 51(4), 327–357. https://doi.org/10.1037/h0061470 - -## Source Type - -Academic Paper - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Anchoring an interview on a specific past incident breaks schema-based recall, revealing real workarounds, edge cases, and failure modes that never surface when asked "how does this usually work?" - -## Core Findings - -1. **Direct observations of critical behavior**: CIT focuses on specific incidents where the purpose and consequences are clear, avoiding generalized schema-based responses. -2. **Schema bypass mechanism**: Direct questions elicit sanitized mental models of "how things should work," while incidents access episodic memory anchored to specific sensory and emotional details. -3. **Flexible data collection**: Method allows participants to describe experiences in their own words without forcing them into predetermined frameworks. -4. **Rare event identification**: CIT captures uncommon but significant events that routine methods miss by focusing only on everyday patterns. -5. **Practical problem solving**: Originally developed for Aviation Psychology Program during WWII to identify pilot errors and improve training/systems design. -6. **Wide applicability**: Successfully used in healthcare, organizational development, market research, and information-seeking behavior studies. - -## Mechanism - -Direct questions elicit the stakeholder's mental schema: a sanitized, gap-free description of how things should work. Critical incidents bypass the schema because episodic memory is anchored to specific sensory and emotional detail. The technique requires incidents to be "sufficiently complete" and "critical" (making positive or negative contribution) where purpose and consequences are clear to the observer. - -## Relevance - -Foundational technique for requirements gathering, user research, and system design. Essential for uncovering actual user behaviors, workarounds, and failure modes that structured interviews miss. Widely adopted in UX research, safety analysis, and organizational problem-solving where understanding real-world behavior patterns is crucial. - -## Related Research - -- (Bitner, Booms & Tetreault, 1990): Service encounter satisfaction research using CIT -- (Klein, 1998): Recognition-primed decision making and naturalistic observation methods diff --git a/docs/research/psychology/cognitive/gollwitzer_1999.md b/docs/research/psychology/cognitive/gollwitzer_1999.md deleted file mode 100644 index 6b9600a5..00000000 --- a/docs/research/psychology/cognitive/gollwitzer_1999.md +++ /dev/null @@ -1,48 +0,0 @@ -# Implementation Intentions (Gollwitzer, 1999) - -## Citation - -Gollwitzer, P. M. (1999). "Implementation intentions: Strong effects of simple plans." *American Psychologist*, 54(7), 493-503. https://doi.org/10.1037/0003-066X.54.7.493 - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -"If X then Y" plans are 2–3x more likely to execute than general intentions because they create automatic cue-response links in memory. - -## Core Findings - -1. **If-then plan effectiveness**: Implementation intentions result in 2-3x higher goal achievement rates compared to general goal intentions alone. -2. **Strategic automaticity**: If-then plans automate action initiation by creating strong mental links between situational cues and desired behaviors. -3. **Cognitive load reduction**: Pre-planned responses eliminate hesitation and deliberation, freeing cognitive resources for other tasks. -4. **Goal shielding**: Implementation intentions protect ongoing goal pursuit from distracting thoughts, competing goals, and emotional interference. -5. **Broad applicability**: Effective across diverse domains including health behaviors (breast self-examination: 100% vs 53% completion), voting (4.1 percentage point increase), and emotion regulation. -6. **Planning specificity requirement**: Plans must specify when, where, and how the behavior will be performed to achieve maximum effectiveness. - -## Mechanism - -If-then plans create automatic cue-response links in memory. The brain processes "if function > 20 lines then extract helper" as an action trigger, not a suggestion to consider. The anticipated situation becomes highly activated in memory, leading to immediate, efficient action initiation without conscious intent when the cue is encountered. - -## Relevance - -Foundational for automated behavioral interventions, habit formation systems, and decision-making tools. Essential for any system requiring reliable execution of intended behaviors, from code review processes to health interventions. The specificity requirement directly applies to creating effective automation rules and behavioral prompts. - -## Related Research - -- (Gollwitzer & Brandstätter, 1997): Original empirical validation of implementation intentions -- (Rogers et al., 2015): Planning prompts and follow-through effectiveness -- (Achtziger, Gollwitzer & Sheeran, 2008): Goal shielding mechanisms diff --git a/docs/research/psychology/cognitive/hattie_timperley_2007.md b/docs/research/psychology/cognitive/hattie_timperley_2007.md deleted file mode 100644 index 34d3aba3..00000000 --- a/docs/research/psychology/cognitive/hattie_timperley_2007.md +++ /dev/null @@ -1,48 +0,0 @@ -# The Power of Feedback (Hattie & Timperley, 2007) - -## Citation - -Hattie, J., & Timperley, H. (2007). "The power of feedback." *Review of Educational Research*, 77(1), 81–112. https://doi.org/10.3102/003465430298487 - -## Source Type - -Academic Paper - -## Method - -Meta-analysis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Feedback is most effective when it tells the agent exactly what went wrong and what the correct action is. "FAIL: function > 20 lines at file:47" is actionable; "Apply function length rules" is not. - -## Core Findings - -1. **Feedback power**: Among the most powerful influences on learning and achievement, but impact can be positive or negative depending on type and delivery. -2. **Specific feedback superiority**: Task-specific feedback that identifies exact errors and correct actions is significantly more effective than general comments. -3. **Four feedback levels**: Task level (correctness), process level (strategies), self-regulation level (monitoring), and self level (personal praise), with task and process being most effective. -4. **Three key questions framework**: "Where am I going?" (goals), "How am I going?" (progress), "Where to next?" (improvement strategies). -5. **Timing effects**: Immediate feedback works best for procedural tasks, delayed feedback for complex learning requiring reflection. -6. **Cognitive load management**: Effective feedback reduces rather than increases cognitive burden by providing clear direction. - -## Mechanism - -Specific feedback creates a direct mapping between error and correction, reducing cognitive load by eliminating interpretation steps. Vague feedback requires the recipient to infer what went wrong, which introduces interpretation errors and reduces action likelihood. The model emphasizes reducing gaps between current performance and goals through precise, actionable information. - -## Relevance - -Foundational for automated feedback systems, code review processes, and instructional design. Critical for any system providing performance feedback, from linting tools to learning management systems. The specificity principle directly applies to error messaging, validation feedback, and progress indicators in software interfaces. - -## Related Research - -- (Black & Wiliam, 1998): Formative assessment and feedback loops in learning -- (Kulhavy & Stock, 1989): Feedback timing and learning effectiveness -- (Kluger & DeNisi, 1996): Feedback intervention theory diff --git a/docs/research/psychology/cognitive/kahneman_2011.md b/docs/research/psychology/cognitive/kahneman_2011.md deleted file mode 100644 index 2a86ba89..00000000 --- a/docs/research/psychology/cognitive/kahneman_2011.md +++ /dev/null @@ -1,47 +0,0 @@ -# Thinking, Fast and Slow (Kahneman, 2011) - -## Citation - -Kahneman, D. (2011). *Thinking, Fast and Slow*. Farrar, Straus and Giroux. ISBN 978-0-374-27563-1. [Bestseller with millions of copies sold] - -## Source Type - -Practitioner Book - -## Method - -Synthesis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Human thinking operates through two distinct systems: System 1 (fast, automatic, intuitive) and System 2 (slow, deliberate, effortful), with System 1 dominating most decisions despite being vulnerable to systematic biases. - -## Core Findings - -1. **Dual-process theory**: System 1 operates automatically and quickly with little conscious effort; System 2 requires attention and operates more slowly and deliberately. -2. **System 1 dominance**: Most of our thinking and decision-making is handled by System 1, while System 2 often endorses impressions and intuitions generated by System 1. -3. **Cognitive biases**: System 1 is susceptible to predictable errors including anchoring bias, availability heuristic, confirmation bias, and overconfidence. -4. **Cognitive ease**: When information is processed fluently by System 1, we experience cognitive ease, leading to increased belief and positive affect. -5. **Loss aversion**: People feel losses more intensely than equivalent gains, leading to irrational decision-making patterns. -6. **Prospect theory**: People evaluate outcomes relative to reference points rather than in absolute terms, and overweight small probabilities. - -## Mechanism - -System 2 must be deliberately activated before System 1's automatic judgments become anchored. This requires effortful cognitive work that most people avoid due to mental laziness. Running deliberate analytical processes (like systematic review checklists) before allowing intuitive responses prevents System 1's fast impressions from contaminating careful evaluation. - -## Relevance - -Foundational for understanding human decision-making biases in design, product management, user research, and team processes. Essential for creating systems that account for predictable human cognitive limitations. Critical for designing decision-support tools and review processes. - -## Related Research - -- (Tversky & Kahneman, 1974): Original heuristics and biases research -- (Stanovich & West, 2000): Dual-process theory development diff --git a/docs/research/psychology/cognitive/klein_1998.md b/docs/research/psychology/cognitive/klein_1998.md deleted file mode 100644 index 7eb03d62..00000000 --- a/docs/research/psychology/cognitive/klein_1998.md +++ /dev/null @@ -1,47 +0,0 @@ -# Sources of Power / PreMortem (Klein, 1998/2007) - -## Citation - -Klein, G. (1998). *Sources of Power: How People Make Decisions*. MIT Press. ISBN 0-262-61146-5. PreMortem method described in Harvard Business Review (2007) and further developed as risk assessment technique. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Prospective hindsight ("imagine this failed. Why?") catches 30% more potential issues than forward-looking review because the brain is better at explaining past events than predicting future ones. - -## Core Findings - -1. **Recognition-primed decision (RPD) model**: Experts don't compare multiple options; they rapidly recognize situations and implement the first viable solution that comes to mind. -2. **PreMortem technique**: By framing failure as having already occurred, teams activate explanation mode rather than prediction mode, uncovering more failure scenarios. -3. **Naturalistic decision making**: Laboratory models cannot adequately describe decision-making under time pressure and uncertainty in real-world settings. -4. **Expertise development**: Experts rely on pattern recognition and mental simulation rather than analytical comparison of alternatives. -5. **Intuition validation**: Expert intuition is based on rapid pattern recognition from extensive domain experience, not mystical insight. -6. **Time pressure effects**: Under pressure, people satisfice (find first adequate solution) rather than optimize (find best possible solution). - -## Mechanism - -PreMortem shifts cognitive frame from prediction (weak) to explanation (strong). By asking "imagine this already failed. Why?" the technique activates the brain's superior ability to generate causal explanations for past events. This reveals failure modes that forward-looking analysis ("what could go wrong?") typically misses because prediction requires cognitive resources that explanation does not. - -## Relevance - -Essential methodology for project risk assessment, decision-making improvement, and team planning processes. Widely adopted in software development, military planning, and organizational risk management. Critical for any high-stakes decision where failure analysis is valuable. - -## Related Research - -- (Kahneman & Klein, 2009): Conditions for intuitive expertise -- (Mitchell et al., 1989): Prospective hindsight effectiveness studies diff --git a/docs/research/psychology/cognitive/mcdaniel_einstein_2000.md b/docs/research/psychology/cognitive/mcdaniel_einstein_2000.md deleted file mode 100644 index 0c1c9d50..00000000 --- a/docs/research/psychology/cognitive/mcdaniel_einstein_2000.md +++ /dev/null @@ -1,47 +0,0 @@ -# Strategic and Automatic Processes in Prospective Memory (McDaniel & Einstein, 2000) - -## Citation - -McDaniel, M. A., & Einstein, G. O. (2000). "Strategic and automatic processes in prospective memory retrieval." *Applied Cognitive Psychology*, 14(7), S127–S144. https://doi.org/10.1002/acp.775 - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Memory for intended actions is better when cues are embedded at the point of action, not in a separate appendix or reference document. - -## Core Findings - -1. **Embedded cue effectiveness**: Prospective memory performance significantly improves when contextual cues appear exactly where the intended action should occur. -2. **Multi-process model**: Prospective memory can operate through both strategic monitoring and automatic retrieval, depending on cue-action associations. -3. **Event-based vs. time-based differences**: Event-based prospective memory (triggered by external cues) consistently outperforms time-based (triggered by internal monitoring). -4. **Strategic automaticity**: Strong cue-action associations can trigger retrieval automatically, reducing cognitive load on working memory. -5. **Point-of-decision placement**: Inline reminders and checks are more effective than separate reference materials or appendices. -6. **Immediate-execute vs. delayed-execute**: Performance deteriorates when delays or interruptions occur between cue perception and intended action. - -## Mechanism - -Placing if-then gates inline rather than in a separate reference document increases adherence because the cue appears exactly when the developer is about to make the relevant decision. Embedded cues leverage both the encoding specificity principle (context overlap) and reduce the cognitive load of having to remember to check separate reference materials. Strong cue-action associations can trigger automatic retrieval without conscious monitoring. - -## Relevance - -Critical for interface design, process documentation, and workflow systems. Applies to code review checklists, safety procedures, quality gates, and any system requiring reliable execution of intended actions. Essential for designing effective reminders, notifications, and decision-support systems where timing and context are crucial. - -## Related Research - -- (Gollwitzer, 1999): Implementation intentions creating automatic cue-response links -- (Miller, 1956): Working memory limitations affecting monitoring-based prospective memory diff --git a/docs/research/psychology/cognitive/miller_1956.md b/docs/research/psychology/cognitive/miller_1956.md deleted file mode 100644 index b542db74..00000000 --- a/docs/research/psychology/cognitive/miller_1956.md +++ /dev/null @@ -1,48 +0,0 @@ -# The Magical Number Seven, Plus or Minus Two (Miller, 1956) - -## Citation - -Miller, G. A. (1956). "The magical number seven, plus or minus two: Some limits on our capacity for processing information." *Psychological Review*, 63(2), 81–97. https://doi.org/10.1037/h0043158 - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Working memory is limited to 7±2 items. Chunking related information into structured patterns allows processing of larger information sets by treating chunks as single items. - -## Core Findings - -1. **Working memory capacity**: Humans can hold approximately 7±2 discrete items in short-term memory before performance degrades. -2. **Chunking mechanism**: Related items can be grouped into meaningful units ("chunks"), allowing more information to be retained by treating each chunk as a single item. -3. **Information channel capacity**: One-dimensional absolute judgment is limited to approximately 2-3 bits of information (4-8 alternatives). -4. **Coincidence observation**: Miller noted the correspondence between judgment limits and memory span was only coincidental, not indicative of a deeper principle. -5. **Structured presentation advantage**: Tables and organized formats reduce cognitive load compared to narrative text by enabling parallel processing. -6. **Recognition vs. capacity**: The limit applies to simultaneous retention, not recognition or learned associations. - -## Mechanism - -Rather than processing each item sequentially, structured presentations allow the reviewer to scan patterns and identify exceptions. Tables with consistent column structure create predictable information architecture that reduces cognitive load. Chunking leverages existing knowledge to group related information into higher-order units, effectively multiplying working memory capacity by the complexity of each chunk. - -## Relevance - -Foundational principle for interface design, information architecture, and cognitive load management. Enforcement tables in verification tasks leverage chunking principles. Instead of prose checklists requiring sequential processing, structured tables allow reviewers to process multiple items in parallel while maintaining consistency. Essential for any system requiring human information processing. - -## Related Research - -- (Sweller, 1988): Cognitive load theory and instructional design -- (Cowan, 2001): Revised capacity estimate of ~4 chunks rather than 7±2 -- (Baddeley, 1992): Working memory model with multiple components \ No newline at end of file diff --git a/docs/research/psychology/cognitive/reynolds_gutman_1988.md b/docs/research/psychology/cognitive/reynolds_gutman_1988.md deleted file mode 100644 index d1600cfb..00000000 --- a/docs/research/psychology/cognitive/reynolds_gutman_1988.md +++ /dev/null @@ -1,46 +0,0 @@ -# Laddering Theory / Means-End Chain (Reynolds & Gutman, 1988) - -## Citation - -Reynolds, T. J., & Gutman, J. (1988). "Laddering theory, method, analysis, and interpretation." *Journal of Advertising Research*, 28(1), 11–31. DOI: 10.1080/00218499.1988.12467766. [Highly cited: 3,779+ citations] - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The laddering technique reveals that the stakeholder's first answer about what they want is rarely the real constraint. Repeatedly asking "Why is that important to you?" climbs from surface attributes to deeper motivational values. - -## Core Findings - -1. **Means-end chain structure**: Concrete attribute → functional consequence → psychosocial consequence → terminal value represents four levels of consumer motivation. -2. **Progressive revelation**: Stakeholders typically start with concrete attributes but the real decision drivers lie at the consequence and value levels. -3. **Value conflict identification**: Stakeholders whose surface requirements look identical often have ladders that diverge at the consequence level, revealing hidden conflicts. -4. **Interview methodology**: Systematic probing with "Why is that important?" uncovers deeper motivational structures that traditional surveys miss. -5. **Advertising applications**: Understanding means-end chains enables more effective positioning by connecting product features to personal values. - -## Mechanism - -The laddering interview technique systematically probes upward through levels of abstraction using "Why is that important to you?" prompts. Each level reveals different types of motivation: attributes (what the product has), functional consequences (what it does), psychosocial consequences (how it makes you feel/appear), and values (what life goals it serves). This climbing process reveals the complete motivational pathway. - -## Relevance - -Essential technique for requirements gathering, user research, and stakeholder analysis. Helps product managers, UX researchers, and business analysts uncover the true drivers behind stated requirements. Critical for avoiding surface-level solutions that miss deeper user needs and organizational goals. - -## Related Research - -- (Rokeach, 1973): Values theory underlying the terminal value concept -- (Gutman, 1982): Original means-end chain model foundation diff --git a/docs/research/psychology/cognitive/tversky_kahneman_1974.md b/docs/research/psychology/cognitive/tversky_kahneman_1974.md deleted file mode 100644 index 378b8a1c..00000000 --- a/docs/research/psychology/cognitive/tversky_kahneman_1974.md +++ /dev/null @@ -1,46 +0,0 @@ -# Judgment Under Uncertainty: Heuristics and Biases (Tversky & Kahneman, 1974) - -## Citation - -Tversky, A., & Kahneman, D. (1974). Judgment under uncertainty: Heuristics and biases. *Science*, 185(4157), 1124-1131. https://doi.org/10.1126/science.185.4157.1124 - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -People use mental shortcuts (heuristics) that systematically bias judgment under uncertainty. - -## Core Findings - -1. People rely on three main heuristics when making judgments under uncertainty: representativeness, availability, and anchoring and adjustment. -2. Representativeness heuristic: People judge probability by similarity to mental prototypes, ignoring base rates and sample size. -3. Availability heuristic: People assess probability by how easily examples come to mind, biasing toward memorable or recent events. -4. Anchoring and adjustment: People adjust insufficiently from initial values, even when the anchor is irrelevant. -5. These heuristics are useful but lead to severe and systematic errors in prediction and judgment. - -## Mechanism - -Heuristics serve as cognitive shortcuts that reduce complex probability assessments to simpler judgmental operations. However, they rely on selective accessibility of information rather than comprehensive analysis. Anchoring activates associative networks around initial values, making adjustment insufficient. Availability conflates memorability with frequency. Representativeness ignores statistical principles in favor of similarity matching. - -## Relevance - -Foundational for understanding cognitive biases in decision-making processes. Critical for designing systems that account for human judgment limitations. Directly applicable to forecast accuracy, risk assessment, and quality control processes where human judgment is involved. - -## Related Research - -- (Kahneman, 2011): System 1 vs System 2 thinking framework -- (Gilovich, Griffin & Kahneman, 2002): Heuristics and biases comprehensive review diff --git a/docs/research/psychology/social/cialdini_2001.md b/docs/research/psychology/social/cialdini_2001.md deleted file mode 100644 index 6fd1cae0..00000000 --- a/docs/research/psychology/social/cialdini_2001.md +++ /dev/null @@ -1,47 +0,0 @@ -# Influence: The Psychology of Persuasion (Cialdini, 1984/2001) - -## Citation - -Cialdini, R. B. (1984). *Influence: The Psychology of Persuasion*. William Morrow and Company. Revised edition (2001). HarperBusiness. ISBN 0-688-12816-5. - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Influence operates through six universal principles of persuasion that create automatic compliance responses in human behavior. - -## Core Findings - -1. **Six principles of influence**: Reciprocity, commitment and consistency, social proof, authority, liking, and scarcity create predictable persuasion outcomes. -2. **Commitment and consistency**: People feel compelled to remain consistent with prior commitments, especially when made publicly or in writing. -3. **Micro-commitments**: Small initial commitments (like checking a box or filling in a form) create resistance to reversals and increase likelihood of larger compliance. -4. **Automatic responses**: These principles trigger "click-whirr" automatic responses where people comply without conscious deliberation. -5. **Research methodology**: Based on three years of undercover participant observation at car dealerships, fundraising organizations, and telemarketing firms. -6. **Unity principle** (added 2016): People are more influenced by those they identify with or consider part of their in-group. - -## Mechanism - -Commitment devices work by engaging the consistency principle. Once someone has made an explicit commitment (especially written or public), psychological pressure to remain consistent makes reversal psychologically costly. Structured tables with PASS/FAIL cells create micro-commitments where marking "FAIL" requires explicit justification, making silent passes feel inconsistent. - -## Relevance - -Foundational framework for understanding persuasion in business, marketing, negotiation, and social influence contexts. Essential for both applying ethical influence techniques and defending against manipulation. Widely used in UX design, sales processes, and behavioral change interventions. - -## Related Research - -- (Kiesler, 1971): Psychology of commitment and consistency -- (Festinger, 1957): Cognitive dissonance theory underlying consistency principle diff --git a/docs/research/psychology/social/mellers_et_al_2001.md b/docs/research/psychology/social/mellers_et_al_2001.md deleted file mode 100644 index 2cfa83dd..00000000 --- a/docs/research/psychology/social/mellers_et_al_2001.md +++ /dev/null @@ -1,46 +0,0 @@ -# Adversarial Collaboration: Kahneman & Various, Multiple Studies - -## Citation - -Various studies on adversarial collaboration including: Kahneman, D. & Klein, G. (2009). "Conditions for intuitive expertise: A failure to disagree." *American Psychologist*, 64(6), 515-526. Clark, C. J., Costello, T., Mitchell, G., & Tetlock, P. E. (2022). "Keep your enemies close: Adversarial collaborations will improve behavioral science." *Journal of Applied Research in Memory and Cognition*, 11(1), 1-18. - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Adversarial collaboration produces highest-quality thinking when parties with opposing hypotheses work together to find flaws in each other's reasoning and jointly design experiments. - -## Core Findings - -1. **Collaborative antagonism**: Scientists with competing hypotheses can co-design experiments that satisfy both groups regarding bias and experimental weaknesses. -2. **Quality improvement**: Adversarial collaboration reduces cognitive-motivational biases and improves scientific reasoning quality. -3. **Feasibility paradox**: "Most feasible when least needed": works best when camps have testable theories and common methodological standards, but is hardest to implement when most needed (when communities lack falsification criteria). -4. **Neutral moderation**: Often requires neutral third-party moderators to facilitate the collaboration process. -5. **Open science framework**: Emphasizes transparency throughout research process, fitting within broader open science movement. - -## Mechanism - -Explicitly framing reviewers as "your job is to break this feature" activates adversarial collaboration mode. Reviewers seek disconfirmation rather than confirmation. Joint experimental design forces both sides to agree on methodology, reducing bias. Co-publication of results ensures accountability and prevents selective interpretation. - -## Relevance - -Powerful methodology for resolving scientific disputes, improving research quality, and reducing confirmation bias in academic work. Applicable to peer review, experimental design, hypothesis testing, and conflict resolution in research communities. Essential for advancing contentious scientific questions. - -## Related Research - -- (Tetlock & Mitchell, 2009): Implicit bias and accountability systems -- (Latham, Erez & Locke, 1988): Early example of adversarial collaboration in goal-setting research diff --git a/docs/research/psychology/social/rogers_farson_1957.md b/docs/research/psychology/social/rogers_farson_1957.md deleted file mode 100644 index 7c661c01..00000000 --- a/docs/research/psychology/social/rogers_farson_1957.md +++ /dev/null @@ -1,46 +0,0 @@ -# Active Listening (Rogers & Farson, 1957) - -## Citation - -Rogers, C. R., & Farson, R. E. (1957). "Active Listening." Industrial Relations Center, University of Chicago. Reprinted in Newman, R. G., Danziger, M. A., & Cohen, M. (1987). *Communicating in Business Today*. D.C. Heath & Company. - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Active listening is a transformative communication technique that creates non-threatening, empathic environments where people feel heard and understood, promoting personal and relational growth. - -## Core Findings - -1. **Three-step process**: Paraphrasing what was heard, asking clarifying questions, then summarizing main points and intent reduces misunderstandings and builds trust. -2. **Therapeutic foundation**: Rooted in Rogers' three facilitative conditions for effective counseling: empathy, genuineness, and unconditional positive regard. -3. **Transformative power**: "Sensitive listening is a most effective agent for individual personality change and group development." -4. **Behavioral outcomes**: People who have been listened to become "more emotionally mature, more open to their experiences, less defensive, more democratic, and less authoritarian." -5. **Active vs. passive**: Despite popular notion that listening is passive, clinical and research evidence shows it actively brings about changes in people's attitudes and values. - -## Mechanism - -Paraphrasing forces the listener to reconstruct the speaker's meaning, immediately surfacing gaps in understanding. Clarifying questions address residual ambiguity. Summarizing creates a shared record that both parties can confirm or correct. This process establishes empathic connection and creates psychological safety for the speaker to be vulnerable and authentic. - -## Relevance - -Foundational communication technique applicable across therapeutic, business, educational, and interpersonal contexts. Essential skill for leaders, counselors, managers, and anyone seeking to build trust and understanding in human relationships. Forms the basis for modern conflict resolution and negotiation strategies. - -## Related Research - -- (Gottman, 1999): Critique of active listening effectiveness in marriage therapy -- (McNaughton et al., 2008): LAFF strategy development for educational contexts diff --git a/docs/research/psychology/social/tetlock_1985.md b/docs/research/psychology/social/tetlock_1985.md deleted file mode 100644 index 853de62a..00000000 --- a/docs/research/psychology/social/tetlock_1985.md +++ /dev/null @@ -1,45 +0,0 @@ -# Accountability: A Social Check on the Fundamental Attribution Error (Tetlock, 1985) - -## Citation - -Tetlock, P. E. (1985). Accountability: A social check on the fundamental attribution error. *Social Psychology Quarterly*, 48(3), 227-236. - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Anticipating accountability to an unknown audience improves reasoning quality and reduces attribution errors. - -## Core Findings - -1. Accountability to an unknown audience with unknown views improves reasoning quality compared to no accountability conditions. -2. People anticipating being audited adjust their reasoning to be more careful and systematic. -3. Accountability reduces the fundamental attribution error - the tendency to overemphasize personality-based explanations while underemphasizing situational factors. -4. The effect is stronger when people don't know what position they'll be expected to defend. - -## Mechanism - -When people expect to justify their judgments to others, they engage in more effortful, systematic processing. The anticipation of having to explain one's reasoning to an unknown audience motivates more careful consideration of multiple perspectives and evidence, leading to less biased judgments. - -## Relevance - -Critical for review processes and agent design. Creating accountability structures (like APPROVED/REJECTED with evidence requirements) prompts more careful analysis. Unknown audience accountability is particularly powerful because reviewers can't game their response to please a specific viewpoint. - -## Related Research - -- (Kahneman, 2011): System 1 vs System 2 thinking and cognitive biases -- (Lerner & Tetlock, 1999): Comprehensive review of accountability effects on judgment diff --git a/docs/research/software-engineering/architecture/bass_et_al_2021.md b/docs/research/software-engineering/architecture/bass_et_al_2021.md deleted file mode 100644 index 66f0c26d..00000000 --- a/docs/research/software-engineering/architecture/bass_et_al_2021.md +++ /dev/null @@ -1,48 +0,0 @@ -# Software Architecture in Practice (Bass, Clements & Kazman, 2021) - -## Citation - -Bass, L., Clements, P., & Kazman, R. (2021). *Software Architecture in Practice* (4th ed.). Addison-Wesley. ISBN 978-0-13-534613-8. First edition published 1998. - -## Source Type - -Academic Paper - -## Method - -Synthesis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Quality attributes (not functional requirements) drive architectural decisions. Performance, availability, security, modifiability, reliability, and usability create measurable constraints that determine system structure. - -## Core Findings - -1. **Quality attribute primacy**: Six architecturally significant quality attributes (Performance, Availability, Security, Modifiability, Reliability, Usability) drive structural decisions more than functional requirements. -2. **Architectural tactics catalog**: Each quality attribute produces concrete architectural tactics: Performance tactics include resource arbitration, concurrency, caching; Modifiability tactics include encapsulation, substitution, binding time. -3. **Style-attribute alignment**: Architectural style selection must be justified against quality attribute priorities, not personal preference or technology trends. -4. **Utility tree methodology**: Systematic approach to prioritize quality attributes against business value, producing ranked constraints for architectural decision-making. -5. **Trade-off recognition**: Quality attributes often conflict. Optimizing for Performance may harm Modifiability, requiring explicit trade-off decisions. -6. **ATAM integration**: Architecture Tradeoff Analysis Method provides structured evaluation framework for discovering architectural risks early. -7. **Measurable constraints**: Quality attributes work because they create concrete, testable constraints on system structure rather than abstract goals. - -## Mechanism - -Quality attributes work as architectural drivers because they create measurable constraints on system structure. Performance requires specific structural patterns (caching layers, async processing, resource pooling); Modifiability requires different patterns (abstraction layers, dependency inversion, plugin architectures). These constraints are often in tension. Optimizing for Performance may harm Modifiability. The utility tree method forces stakeholders to prioritize quality attributes against business value, producing a ranked list that architects use to make trade-off decisions with explicit justification. - -## Relevance - -Foundational methodology for architectural decision-making and system design. Essential for understanding how non-functional requirements translate into concrete structural choices. Critical for architectural evaluation, technology selection, and trade-off analysis. Widely adopted framework used by enterprise architects, system designers, and software engineering teams globally. - -## Related Research - -- (Kazman et al., 2000): ATAM methodology for architectural trade-off analysis -- (Fowler, 2003): Architect's role in making significant decisions that are hard to change later diff --git a/docs/research/software-engineering/architecture/boehm_1991.md b/docs/research/software-engineering/architecture/boehm_1991.md deleted file mode 100644 index d851efb3..00000000 --- a/docs/research/software-engineering/architecture/boehm_1991.md +++ /dev/null @@ -1,47 +0,0 @@ -# Software Risk Management (Boehm, 1991) - -## Citation - -Boehm, B. W. (1991). "Software Risk Management: Principles and Practices." *IEEE Software*, 8(1), 32–41. https://doi.org/10.1109/52.62930 - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Architecture risk can be systematically assessed using Probability × Impact classification, replacing intuitive risk assessment with an explicit, auditable evaluation framework. - -## Core Findings - -1. **Risk quantification framework**: Each identified risk is rated on two dimensions: Probability (likelihood of materialization) and Impact (severity of consequence), with risks prioritized by their product. -2. **Risk leverage concept**: The ratio of risk reduction to mitigation cost enables teams to focus effort on high-leverage interventions (significant risk reduction for low cost). -3. **Systematic risk identification**: Boehm's 10 top software risk items provide a checklist for proactive risk identification across personnel, requirements, technology, and schedule dimensions. -4. **Risk mitigation strategies**: Three primary approaches - risk avoidance (eliminate risk source), risk monitoring (track risk indicators), and risk contingency planning (prepare response plans). -5. **COCOMO model foundation**: Boehm's cost estimation models (COCOMO/COCOMO II) provide quantitative basis for impact assessment in software projects. -6. **Spiral model integration**: Risk assessment is built into the spiral software development model at each iteration cycle. - -## Mechanism - -Probability × Impact works because it forces decision-makers to externalize and quantify what would otherwise remain gut feelings. Low-probability high-impact risks (e.g., database vendor bankruptcy) are distinguished from high-probability low-impact risks (e.g., minor performance degradation); both may have the same exposure score but demand different mitigation strategies. The framework also introduces risk leverage: high-leverage mitigations (significant risk reduction for low cost) are prioritized over low-leverage ones (minor risk reduction for high cost). - -## Relevance - -Foundational framework for architectural decision records (ADRs) where each decision carries potential risks requiring explicit evaluation. Essential for project management, system design, and any development context requiring systematic risk assessment. Directly applicable to technology selection, architecture planning, and resource allocation decisions in software engineering. - -## Related Research - -- (Kazman, Klein & Clements, 2000): ATAM method building on Boehm's risk assessment principles -- (Fowler, 2003): Architectural decision-making frameworks incorporating risk evaluation diff --git a/docs/research/software-engineering/architecture/brown_2018.md b/docs/research/software-engineering/architecture/brown_2018.md deleted file mode 100644 index 068c5e89..00000000 --- a/docs/research/software-engineering/architecture/brown_2018.md +++ /dev/null @@ -1,48 +0,0 @@ -# C4 Model (Brown, 2006–2018) - -## Citation - -Brown, S. (2018). *Software Architecture for Developers*, Volume 1. Leanpub. C4 model first described 2006–2011, official site launched 2018. Available at https://c4model.com - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Four levels of architectural abstraction (Context, Container, Component, Code) provide just enough detail at each audience level without overwhelming any single audience. - -## Core Findings - -1. **Hierarchical abstraction levels**: Context (system in environment), Container (deployable units), Component (modules within containers), Code (classes and functions). -2. **Audience-specific communication**: Each level answers different questions for different audiences: Context for stakeholders, Container for developers/operators, Component for internal structure, Code for detailed design. -3. **Progressive disclosure**: Starting from Context and drilling down prevents premature detail overload. -4. **Notation independence**: C4 works with any diagramming tool or notation. Boxes and lines are sufficient. -5. **Tooling independence**: Can be implemented with simple drawing tools, specialized software, or code-based approaches. -6. **Developer-friendly approach**: Focuses on developer mental models rather than formal architectural frameworks. -7. **Supporting diagrams**: System landscape, dynamic, and deployment diagrams complement the core four levels. - -## Mechanism - -The C4 model works because each level answers a different question for a different audience: Context for stakeholders and non-technical team members ("what does the system interact with?"), Container for developers and operators ("what are the deployable units and their tech stacks?"), Component for developers working within a container ("how is this container structured internally?"), and Code for detailed design (rarely needed as a diagram). Starting from Context and drilling down prevents premature detail and ensures the architecture communicates effectively at every level. - -## Relevance - -Essential methodology for software architecture documentation and communication. Widely adopted for system design, technical onboarding, and stakeholder communication. Critical for teams needing to communicate architecture across different technical skill levels and organizational roles. Directly applicable to microservices documentation, system integration planning, and technical decision-making processes. - -## Related Research - -- (Kruchten, 1995): 4+1 architectural view model that influenced hierarchical approach -- (Fowler, 2003): "Who Needs an Architect?" discussion on architectural communication \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/cockburn_2005.md b/docs/research/software-engineering/architecture/cockburn_2005.md deleted file mode 100644 index d64926a2..00000000 --- a/docs/research/software-engineering/architecture/cockburn_2005.md +++ /dev/null @@ -1,47 +0,0 @@ -# Hexagonal Architecture (Ports & Adapters) (Cockburn, 2005) - -## Citation - -Cockburn, A. (2005). "Hexagonal Architecture." *Alistair Cockburn's blog*. Originally discussed on the Portland Pattern Repository wiki in the early 2000s; formalized as "Ports and Adapters" in 2005. - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Software should be designed so that the domain core has no dependency on any external technology or delivery mechanism. The domain exposes ports (interfaces) that define what it needs; adapters implement those ports for specific technologies. - -## Core Findings - -1. **Dependency inversion principle**: Infrastructure depends on domain abstractions, not the other way around, making the domain testable in isolation and swappable in deployment. -2. **Ports and adapters pattern**: Ports are domain-defined interfaces; adapters are infrastructure implementations that connect external systems to the domain through these ports. -3. **Technology independence**: The same domain logic can be exercised through any delivery mechanism (HTTP, CLI, message queue, test harness) without modification. -4. **Symmetrical architecture**: All external dependencies (databases, UI, external services, test harnesses) are treated equally as adapters, eliminating the traditional "top" and "bottom" of layered architectures. -5. **Framework isolation**: The domain remains independent of frameworks, databases, and UI technologies, enabling easier testing and technology evolution. -6. **Business logic protection**: Core business rules are isolated from infrastructure concerns, making them more maintainable and less brittle to external changes. - -## Mechanism - -By reversing the dependency so that infrastructure depends on domain abstractions (not the other way around), the domain becomes testable in isolation and swappable in deployment. The hexagonal shape represents that there are multiple ways to interact with the application - through different ports - and each port can have multiple adapters. This ensures the domain remains independent of frameworks, databases, and UI, and that the same domain logic can be exercised through any delivery mechanism without modification. - -## Relevance - -Foundational pattern for clean architecture, domain-driven design, and microservices architecture. Essential for creating testable, maintainable systems that can evolve independently of infrastructure concerns. Critical for understanding how to structure applications to achieve technology independence and high testability. Directly applicable to API design, service architecture, and any system requiring multiple integration points. - -## Related Research - -- (Martin, 2017): Clean Architecture building on Cockburn's dependency inversion principles -- (Fowler, 2003): Architectural decision-making frameworks that support ports and adapters pattern \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/conway_1968.md b/docs/research/software-engineering/architecture/conway_1968.md deleted file mode 100644 index 43270a1b..00000000 --- a/docs/research/software-engineering/architecture/conway_1968.md +++ /dev/null @@ -1,47 +0,0 @@ -# Conway's Law and Inverse Conway Maneuver (Conway, 1968) - -## Citation - -Conway, M. E. (1968). "How Do Committees Invent?" *Datamation*, 14(4), 28–31. https://www.melconway.com/Home/Committees_Paper.html - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure. This is known as "Conway's Law." - -## Core Findings - -1. **System-organization mirroring**: Organizations are constrained to produce designs that copy their communication structures. -2. **Communication boundaries become system boundaries**: Teams that communicate frequently create tightly coupled systems; teams with minimal communication create loosely coupled systems. -3. **Empirical validation**: MIT and Harvard Business School research found "strong evidence to support the mirroring hypothesis" - loosely-coupled organizations produce significantly more modular products. -4. **Inverse Conway Maneuver**: Deliberately restructuring teams to match desired architecture rather than fighting organizational constraints. -5. **Three strategic responses**: Organizations can ignore (creating friction), accept (aligning architecture with existing structure), or invert (restructuring teams for desired architecture). -6. **Architectural implications**: Microservices require autonomous teams, monoliths work with closely collaborating teams, API boundaries should align with team boundaries. - -## Mechanism - -System boundaries mirror communication boundaries. Teams that communicate frequently create tightly coupled systems. Teams with minimal communication create loosely coupled systems. Organizational design becomes architectural design. The Inverse Conway Maneuver deliberately alters team organization to encourage the desired software architecture, aligning Conway's Law with architectural intent rather than fighting it. - -## Relevance - -Foundational principle for organizational design in software development. Critical for microservices architecture, team topology design, and system boundary definition. Agent role design implements Inverse Conway: the system-architect → software-engineer → system-architect loop creates a closed communication path where SA designs module boundaries, SE builds within them, and SA verifies boundary respect. - -## Related Research - -- (Skelton & Pais, 2019): Team Topologies and modern application of Conway's Law -- (MacCormack, Rusnak & Baldwin, 2011): Empirical validation of the mirroring hypothesis \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/fielding_2000.md b/docs/research/software-engineering/architecture/fielding_2000.md deleted file mode 100644 index 17daf49c..00000000 --- a/docs/research/software-engineering/architecture/fielding_2000.md +++ /dev/null @@ -1,47 +0,0 @@ -# Representational State Transfer (REST) (Fielding, 2000) - -## Citation - -Fielding, R. T. (2000). *Architectural Styles and the Design of Network-based Software Architectures*. Doctoral dissertation, University of California, Irvine. https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -REST defines six architectural constraints for network-based software that enable scalable, reliable, and maintainable distributed systems by treating network communication as stateless operations on resources identified by URLs. - -## Core Findings - -1. **Six architectural constraints**: Client-Server (separation of concerns), Stateless (each request self-contained), Cacheable (responses declare cacheability), Uniform Interface (standardized resource operations), Layered System (transparent intermediaries), Code-on-Demand (optional client extensions). -2. **Uniform Interface supremacy**: The constraint that differentiates REST from other distributed architectures - resources identified by URIs, manipulated via standard methods (GET, POST, PUT, DELETE), with hypermedia driving application state (HATEOAS). -3. **Statelessness benefits**: Each request contains all needed information, improving reliability (any server can handle any request) and scalability (no server-side session state management). -4. **Cacheability advantages**: Explicit cache control reduces latency and server load while maintaining data consistency. -5. **Layered system flexibility**: Intermediaries (caches, proxies, load balancers) can be inserted without affecting client or server design. -6. **Web architecture alignment**: REST explains why the Web scales - it codifies the architectural principles that made the WWW successful. - -## Mechanism - -REST works because the Uniform Interface constraint reduces coupling between client and server to a minimum: clients only need to understand media types and standard methods, not server implementation details. Statelessness improves reliability and scalability. For API design, REST implies contracts should be expressed as resource shapes (data structure) and media types (data format), not procedure calls. The contract becomes the resource schema and allowed transitions, not method signatures. - -## Relevance - -Foundational architecture for web services, APIs, and distributed systems. Essential for understanding modern web architecture, microservices design, and HTTP-based APIs. Critical for system architects designing scalable, maintainable distributed systems. Directly applicable to API design, web service architecture, and system integration patterns. - -## Related Research - -- (Conway, 1968): Organizational structure implications for REST service boundaries -- (Fowler, 2014): Microservices architecture patterns building on REST principles diff --git a/docs/research/software-engineering/architecture/fowler_2003.md b/docs/research/software-engineering/architecture/fowler_2003.md deleted file mode 100644 index e70698d1..00000000 --- a/docs/research/software-engineering/architecture/fowler_2003.md +++ /dev/null @@ -1,47 +0,0 @@ -# Who Needs an Architect? (Fowler, 2003) - -## Citation - -Fowler, M. (2003). "Who Needs an Architect?" *IEEE Software*, 20(5), 11–13. https://martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The architect's job is not to draw diagrams. It is to make **significant decisions** that are hard to change later. The architect is a facilitator who builds consensus around technical direction, not a dictator who issues edicts. - -## Core Findings - -1. **Four architect archetypes**: Architect as Decision-Maker (owns hard-to-change choices), Expert (provides technical depth), Facilitator (brings stakeholders to consensus), and Gatekeeper (enforces standards and reviews compliance). -2. **Programming architects superiority**: The best architects are also programmers who understand implementation constraints firsthand rather than ivory-tower theorists. -3. **Policy vs. detail separation**: The architect owns **policy** (business rules, interfaces, architectural constraints) while developers own **detail** (algorithms, data structures, implementation mechanics). -4. **Significant decisions focus**: Architecture is about making important decisions that affect the system's ability to meet its quality requirements, not about creating comprehensive documentation. -5. **Facilitation over dictation**: Effective architects build consensus and shared understanding rather than issuing top-down mandates. -6. **Hands-on involvement**: Architects must stay involved in implementation to understand real-world constraints and trade-offs. - -## Mechanism - -This separation enables independent evolution of concerns - policy can change without affecting implementation details, and vice versa. The architect focuses on decisions that are expensive to change later (technology choices, integration patterns, quality attribute strategies) while leaving implementation flexibility to developers. Facilitation works better than dictation because it creates buy-in and shared understanding, making architectural decisions more likely to be followed and adapted appropriately as circumstances change. - -## Relevance - -Foundational framework for defining architectural roles and responsibilities in modern software development. The system-architect role combines decision-maker and gatekeeper functions: making architectural decisions (ADRs) and enforcing them through adversarial review. Essential for understanding the balance between architectural guidance and implementation autonomy in agile development environments. - -## Related Research - -- (Martin, 2017): Clean Architecture principles building on Fowler's policy/detail separation -- (Bass et al., 2021): Software Architecture in Practice expanding on architectural decision-making frameworks \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/hohpe_woolf_2003.md b/docs/research/software-engineering/architecture/hohpe_woolf_2003.md deleted file mode 100644 index adb38ef1..00000000 --- a/docs/research/software-engineering/architecture/hohpe_woolf_2003.md +++ /dev/null @@ -1,47 +0,0 @@ -# Enterprise Integration Patterns (Hohpe & Woolf, 2003) - -## Citation - -Hohpe, G., & Woolf, B. (2003). *Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions*. Addison-Wesley. ISBN 978-0-321-20068-6. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Asynchronous messaging between systems follows a catalog of 65 integration patterns that solve recurring coupling, reliability, and ordering problems, providing technology-independent solutions to distributed system integration challenges. - -## Core Findings - -1. **Foundational messaging patterns**: Message (data packet), Message Channel (transport), Message Endpoint (producer/consumer), Message Router (content-based routing), Message Translator (schema conversion), and Publish-Subscribe Channel (one-to-many distribution) form the core vocabulary. -2. **Decoupling dimensions**: Integration patterns decouple time (asynchronous delivery), space (location independence), and schema (data model independence) between systems. -3. **Event contract specifications**: Beyond payload schema, event contracts must specify ordering guarantees, delivery semantics (at-most-once, at-least-once, exactly-once), and error handling policies. -4. **Pattern language approach**: 65 patterns organized into categories (messaging systems, channels, construction, routing, transformation, endpoints, system management) providing comprehensive integration vocabulary. -5. **Technology independence**: Patterns apply across messaging technologies (JMS, MSMQ, TIBCO, modern cloud messaging, microservices, serverless architectures). -6. **Industry adoption**: Spurred development of Enterprise Service Bus implementations including Apache Camel, Mule, WSO2, Oracle Service Bus, Open ESB, and modern integration platforms. - -## Mechanism - -Integration patterns work because they decouple time, space, and schema between systems. A Message Channel decouples space (producer and consumer don't need to know each other's location); asynchronous delivery decouples time (producer and consumer don't need to be available simultaneously); a Message Translator decouples schema (each system retains its own data model). The key insight is that event contracts must specify not just the payload schema but also ordering guarantees (per-sender FIFO, causal ordering), delivery semantics, and error handling. Without these, integration points become fragile and hard to reason about. - -## Relevance - -Foundational reference for all distributed system integration, microservices architecture, event-driven systems, and API design. Essential for understanding asynchronous messaging patterns that remain relevant across technology generations from enterprise messaging to modern serverless and cloud-native architectures. Critical for designing robust, loosely-coupled distributed systems. - -## Related Research - -- (Fielding, 2000): REST architectural style complementing messaging patterns for distributed systems -- (Conway, 1968): Organizational structures affecting integration architecture design diff --git a/docs/research/software-engineering/architecture/kazman_klein_clements_2000.md b/docs/research/software-engineering/architecture/kazman_klein_clements_2000.md deleted file mode 100644 index c9924ac0..00000000 --- a/docs/research/software-engineering/architecture/kazman_klein_clements_2000.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture Tradeoff Analysis Method (ATAM) (Kazman, Klein & Clements, 2000) - -## Citation - -Kazman, R., Klein, M., & Clements, P. (2000). "ATAM: Method for Architecture Evaluation" (CMU/SEI-2000-TR-004). Software Engineering Institute, Carnegie Mellon University. - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Architecture should be evaluated early through structured scenario analysis. ATAM discovers **trade-offs** and **sensitivity points** before implementation begins, when change cost is minimal. - -## Core Findings - -1. **Risk-mitigation roadmap**: ATAM produces a structured assessment of architectural risks rather than a simple pass/fail verdict. -2. **Nine-step process**: Systematic methodology covering stakeholder presentation, business driver analysis, architecture presentation, approach identification, quality attribute tree generation, analysis, scenario brainstorming, re-analysis, and results presentation. -3. **Sensitivity points identification**: Reveals architectural decisions that most significantly affect quality attributes. -4. **Trade-off points analysis**: Identifies decisions affecting multiple quality attributes in opposing ways, highlighting necessary compromises. -5. **Quality attribute focus**: Structures evaluation around specific quality concerns (performance, security, maintainability, etc.) rather than general architectural goodness. -6. **Stakeholder-driven scenarios**: Uses real stakeholder scenarios to test architectural decisions against actual usage patterns and concerns. - -## Mechanism - -The method reveals how architectural decisions affect quality attributes and identifies decisions that most impact system success. ATAM works by systematically walking through architectural approaches against stakeholder-prioritized quality attribute scenarios. Sensitivity points emerge when small changes in architectural decisions cause large changes in quality attribute response. Trade-off points appear when architectural decisions improve one quality attribute while degrading another, forcing explicit design trade-offs. - -## Relevance - -Foundational methodology for architectural assessment and review processes. ATAM-style analysis is applied in adversarial review during verification: testing implemented architecture against quality-attribute scenarios identified during design. Essential for system architects who need to evaluate architectural decisions before implementation when change costs are minimal. - -## Related Research - -- (Bass, Clements & Kazman, 2021): Software Architecture in Practice expanding on ATAM methodology -- (Clements, Kazman & Klein, 2002): Evaluating Software Architectures comprehensive guide \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/kruchten_1995.md b/docs/research/software-engineering/architecture/kruchten_1995.md deleted file mode 100644 index 61223530..00000000 --- a/docs/research/software-engineering/architecture/kruchten_1995.md +++ /dev/null @@ -1,47 +0,0 @@ -# The 4+1 View Model of Architecture (Kruchten, 1995) - -## Citation - -Kruchten, P. B. (1995). "The 4+1 View Model of Architecture." *IEEE Software*, 12(6), 42–50. https://doi.org/10.1109/52.469759 - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Software architecture cannot be adequately captured in a single model or view. The 4+1 model provides multiple, complementary perspectives that together form a complete architectural description. - -## Core Findings - -1. **Five complementary views**: Logical view (object model, functional requirements), Process view (concurrency, distribution, performance), Physical view (deployment, hardware topology), Development view (static organization, modules, subsystems), and Scenarios (+1) that tie views together through use cases. -2. **Stakeholder-specific concerns**: Each view addresses different stakeholder concerns and quality attributes - developers need Development view, system integrators need Physical view, performance engineers need Process view. -3. **Scenario validation**: The scenarios (+1) validate that the architecture works as an integrated whole by showing how the views collaborate to support key use cases. -4. **Quality attribute mapping**: Each view specifically addresses non-functional requirements - Performance (Process), Availability (Physical), Modifiability (Development), Functionality (Logical). -5. **Multi-perspective necessity**: Architecture is not just structure - it must address non-functional requirements through specific design decisions in each view. -6. **IEEE 1471 influence**: Kruchten's work heavily influenced IEEE 1471-2000 standard for architectural description. - -## Mechanism - -The model emphasizes that architecture is not just structure. It must address non-functional requirements (performance, availability, modifiability) through specific design decisions in each view. Each view uses different notation and focuses on different architectural elements, but scenarios weave through all views to demonstrate end-to-end system behavior. This multi-perspective approach ensures no critical architectural concern is overlooked while avoiding the complexity of a single, monolithic architectural model. - -## Relevance - -Foundational framework for architectural documentation and communication. C4 diagrams and modern architectural documentation templates follow this multi-view principle. Context, Container, Component, and Code diagrams provide complementary perspectives that together describe complete architecture. Essential for enterprise architecture, system design documentation, and architectural review processes. - -## Related Research - -- (Brown, 2018): C4 model applying multi-view principles to contemporary software architecture -- (Bass et al., 2021): Software Architecture in Practice building on Kruchten's view-based approach \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/martin_2012_clean.md b/docs/research/software-engineering/architecture/martin_2012_clean.md deleted file mode 100644 index c0d8c9d0..00000000 --- a/docs/research/software-engineering/architecture/martin_2012_clean.md +++ /dev/null @@ -1,48 +0,0 @@ -# Clean Architecture (Martin, 2012) - -## Citation - -Martin, R. C. (2012). "The Clean Architecture." *8th Light Blog*. Later expanded in *Clean Architecture: A Craftsman's Guide to Software Structure and Design* (2017), Prentice Hall. ISBN 978-0-13-449416-6. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The dependency arrow always points inward: from infrastructure toward application toward domain. The domain knows nothing about frameworks, databases, or external services. - -## Core Findings - -1. **Dependency Rule**: Source code dependencies must point inward only. Outer layers can depend on inner layers, but inner layers must never depend on outer layers. -2. **Concentric layer structure**: Four layers from outside to inside: Frameworks/Drivers → Interface Adapters → Application Business Rules (Use Cases) → Enterprise Business Rules (Entities). -3. **Framework independence**: The architecture doesn't depend on frameworks; frameworks are tools to be used, not architectures to be conformed to. -4. **Testable in isolation**: Business rules can be tested without UI, database, web server, or any external element because dependencies point inward. -5. **Database independence**: Business rules are not bound to the database. You can swap Oracle for SQL Server, MongoDB, CouchDB, or something else without affecting business rules. -6. **UI independence**: The UI can change without changing the rest of the system. Web UI could be replaced with console UI without changing business rules. -7. **Building on previous architectures**: Clean Architecture synthesizes Hexagonal Architecture (Cockburn, 2005), Onion Architecture, Screaming Architecture, and DCI into a unified approach. - -## Mechanism - -Clean Architecture builds on Hexagonal Architecture and layer-based approaches by making the dependency rule explicit: source code dependencies must point inward only. The outermost layers (frameworks, drivers, UI, database) are details that can be changed without affecting inner layers. The innermost layer (entities, use cases) contains business rules that have no knowledge of the outside world. This ensures that the domain is both testable in isolation and insulated from infrastructure churn. Dependency Inversion Principle enables this by having high-level modules define interfaces that low-level modules must implement. - -## Relevance - -Foundational architecture pattern for creating maintainable, testable, framework-independent systems. Essential for microservices design, domain-driven design implementation, and any system requiring long-term maintainability. Critical for applications where business logic must evolve independently of technical infrastructure choices. - -## Related Research - -- (Parnas, 1972): Information hiding principles underlying Clean Architecture's dependency rule -- (Cockburn, 2005): Hexagonal Architecture that Clean Architecture builds upon and generalizes \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/nygard_2011.md b/docs/research/software-engineering/architecture/nygard_2011.md deleted file mode 100644 index e2ea3da2..00000000 --- a/docs/research/software-engineering/architecture/nygard_2011.md +++ /dev/null @@ -1,48 +0,0 @@ -# Architecture Decision Records (Nygard, 2011) - -## Citation - -Nygard, M. (2011). "Documenting Architecture Decisions." *Cognitect Blog*. November 15, 2011. Later adopted by ThoughtWorks Technology Radar (2016). https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Architecturally significant decisions should be documented as short, immutable records capturing the context, decision, rationale, alternatives, and consequences. Each record is written once and never edited. If understanding changes, a new record supersedes the old one. - -## Core Findings - -1. **Five-part structure**: Title, Context (forces at play), Decision (response to forces), Status (proposed/accepted/superseded), Consequences (resulting context after decision). -2. **Immutability principle**: ADRs are never edited after acceptance. Superseded decisions remain as historical record with references to replacements. -3. **Lightweight format**: One to two pages maximum, written in Markdown, stored in version control with code. -4. **Architecturally significant scope**: Decisions affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques. -5. **Sequential numbering**: ADRs numbered monotonically and sequentially (never reused) for easy reference. -6. **Conversation with future developers**: Written in full sentences with active voice to communicate reasoning to new team members. -7. **ThoughtWorks adoption**: Added to Technology Radar in 2016, driving widespread industry adoption. - -## Mechanism - -ADRs work because they externalise architectural reasoning that would otherwise remain tacit, tribal knowledge. By forcing the decision-maker to articulate the context (what forces are at play), the decision (what was chosen), the reason (why this choice over alternatives), and the consequences (what becomes easier or harder), ADRs create a decision trail that new team members can read. Immutability prevents retroactive justification: you cannot rewrite history, only supersede it. The consequences of one ADR often become the context for subsequent ADRs, creating a decision pattern language. - -## Relevance - -Essential practice for software architecture documentation and knowledge management. Critical for distributed teams, high-turnover environments, and complex systems requiring architectural decision tracking. Widely adopted across the software industry for maintaining architectural reasoning, onboarding new developers, and preventing repeated architectural mistakes. Directly applicable to any project requiring transparent decision-making processes. - -## Related Research - -- (Kruchten, 2004): Importance of architecture decisions in software development -- (Brown, 2018): C4 model complementing ADR documentation with visual architecture communication \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/parnas_1972.md b/docs/research/software-engineering/architecture/parnas_1972.md deleted file mode 100644 index e4138fbe..00000000 --- a/docs/research/software-engineering/architecture/parnas_1972.md +++ /dev/null @@ -1,47 +0,0 @@ -# Information Hiding (Parnas, 1972) - -## Citation - -Parnas, D. L. (1972). "On the criteria to be used in decomposing systems into modules." *Communications of the ACM*, 15(12), 1053–1058. https://doi.org/10.1145/361598.361623 - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The correct criterion for decomposing a system into modules is **information hiding**: each module hides a design decision that is likely to change. Modules should reveal only what callers need while hiding implementation details. - -## Core Findings - -1. **Information hiding principle**: Each module should hide one specific design decision that is likely to change, creating a stable interface while allowing implementation flexibility. -2. **Decomposition by change-prone decisions**: Rather than decomposing by execution steps (procedure-based), decompose by decisions most likely to change (data structures, algorithms, I/O formats, external protocols). -3. **Module interface stability**: The module's public interface should be change-stable while the implementation remains change-free from the caller's perspective. -4. **Coupling reduction**: Information hiding prevents tight coupling by making modules depend only on abstract interfaces, not concrete implementations. -5. **Foundation for modern principles**: This 1972 paper established the theoretical foundation for SOLID principles (especially Dependency Inversion), Hexagonal Architecture, and Domain-Driven Design bounded contexts. -6. **Engineering professionalization**: Parnas was among the first to apply traditional engineering principles to software design, earning professional engineering licenses and advocating for software engineering as a legitimate engineering discipline. - -## Mechanism - -Decomposing by execution steps (procedure-based) creates tight coupling to implementation order. Decomposing by change-prone decisions (information-hiding) allows each decision to be changed independently without affecting other modules. The mechanism works by identifying decisions most likely to change (data structures, algorithms, I/O formats, external service protocols), then making each such decision a module boundary. The module's public interface exposes only what callers need; all implementation details remain hidden and changeable. - -## Relevance - -Foundational principle for all modern software architecture. Essential for creating maintainable, evolvable systems where changes to implementation details don't cascade through the entire codebase. Critical for microservices design, API development, library design, and any system requiring long-term maintainability. Directly applicable to bounded context identification, dependency injection, and modular system design. - -## Related Research - -- (Martin, 2000): SOLID principles building on Parnas's information hiding foundation -- (Cockburn, 2005): Hexagonal Architecture applying information hiding to external dependencies \ No newline at end of file diff --git a/docs/research/software-engineering/architecture/skelton_pais_2019.md b/docs/research/software-engineering/architecture/skelton_pais_2019.md deleted file mode 100644 index 88c653c5..00000000 --- a/docs/research/software-engineering/architecture/skelton_pais_2019.md +++ /dev/null @@ -1,48 +0,0 @@ -# Team Topologies (Skelton & Pais, 2019) - -## Citation - -Skelton, M., & Pais, M. (2019). *Team Topologies: Organizing Business and Technology Teams for Fast Flow*. IT Revolution Press. ISBN 978-1942788812. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Team cognitive load and communication patterns directly impact software architecture quality. Teams should be organized around the architecture you want, not the architecture you have. - -## Core Findings - -1. **Four fundamental team types**: Stream-aligned (continuous flow aligned to business capability), Enabling (helps other teams overcome obstacles), Complicated-subsystem (specialized knowledge for complex subsystems), Platform (provides internal services to reduce cognitive load). -2. **Three team interaction modes**: Collaboration (working together for discovery and rapid learning), X-as-a-Service (consuming services with minimal collaboration), Facilitating (helping another team learn or adopt new approaches). -3. **Cognitive load management**: Teams have limited cognitive capacity. Exceeding this limit through too many responsibilities, technologies, or domains reduces effectiveness. -4. **Conway's Law application**: Team boundaries become system boundaries, so design team structures that mirror your desired architecture using the Inverse Conway Maneuver. -5. **Fast flow optimization**: Team topologies should minimize cognitive load while maximizing flow of value to customers. -6. **Evolutionary design**: Team structures and communication pathways must be able to evolve with technological and organizational maturity. -7. **Second edition emphasis**: Cognitive load as a design principle, organizations as "flourishing ecosystems" rather than "efficient machines." - -## Mechanism - -Teams are the fundamental means of delivery, where team structures determine software architecture through Conway's Law. By deliberately designing team topologies to match desired system architecture, organizations can influence both technical and organizational outcomes. Cognitive load acts as a constraint. Teams exceeding their cognitive capacity produce lower quality software with slower delivery. The four team types and three interaction modes provide a vocabulary for designing sustainable organizational structures. - -## Relevance - -Essential framework for organizational design in technology companies. Critical for DevOps transformation, microservices architecture, platform engineering, and any organization seeking to improve software delivery performance. Directly applicable to team formation, organizational restructuring, and aligning team boundaries with system boundaries. - -## Related Research - -- (Conway, 1968): Conway's Law as the theoretical foundation for team-system mirroring -- (Brooks, 1975): The Mythical Man-Month on team size and communication overhead limits \ No newline at end of file diff --git a/docs/research/software-engineering/process/beck_1999_yagni.md b/docs/research/software-engineering/process/beck_1999_yagni.md deleted file mode 100644 index c9244c81..00000000 --- a/docs/research/software-engineering/process/beck_1999_yagni.md +++ /dev/null @@ -1,45 +0,0 @@ -# YAGNI ("You Aren't Gonna Need It") (Beck & Jeffries, 1999) - -## Citation - -Beck, K., & Jeffries, R. (1999). Extreme Programming principle, originated on the Ward Cunningham Wiki and in comp.software.extreme-programming discussions. Later articulated in Beck, K. (2000). *Extreme Programming Explained*, Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Never add functionality until it is required by a failing test or current requirement - speculative code adds complexity without delivering value. - -## Core Findings - -1. **Principle Definition**: "Always implement things when you actually need them, never when you just foresee that you need them" (Ron Jeffries) -2. **Cognitive Bias Protection**: YAGNI counteracts planning fallacy (overestimating likelihood of predicted needs) and sunk cost bias -3. **Design Priority**: YAGNI operates as highest-priority design rule (YAGNI > KISS > DRY > OC > SOLID > patterns) -4. **XP Integration**: Used with continuous refactoring, automated unit testing, and continuous integration -5. **Expert Validation**: John Carmack noted "rarely architecting for future requirements turns out net-positive" - -## Mechanism - -YAGNI protects against two cognitive biases: planning fallacy (overestimating likelihood that predicted future needs will materialize) and sunk cost (reluctance to remove expensive-to-write code). By deferring all implementation until demanded by tests or requirements, YAGNI keeps codebase minimal and focused. Must be used with supporting practices like continuous refactoring to avoid technical debt. - -## Relevance - -Essential for lean software development, preventing over-engineering and feature creep. Applied in TDD workflows, API design, architecture decisions. Fundamental principle in Extreme Programming and Agile methodologies for maintaining code simplicity and reducing maintenance burden. - -## Related Research - -Connects to (Beck, 2002) on TDD practices, (Fowler, 1999) on refactoring support, (Gamma et al., 1994) on design patterns as lower priority. Part of broader XP methodology alongside KISS principle and DRY principle. Related to Lean principles of waste elimination. \ No newline at end of file diff --git a/docs/research/software-engineering/process/beyer_et_al_2016.md b/docs/research/software-engineering/process/beyer_et_al_2016.md deleted file mode 100644 index e3a04b72..00000000 --- a/docs/research/software-engineering/process/beyer_et_al_2016.md +++ /dev/null @@ -1,45 +0,0 @@ -# Blameless Post-Mortems (Beyer et al., 2016) - -## Citation - -Beyer, B., Jones, R., Petoff, J., & Murphy, N. R. (2016). *Site Reliability Engineering: How Google Runs Production Systems*. O'Reilly Media. Chapter 15: "Postmortem Culture: Learning from Failure." - -## Source Type - -Practitioner Book - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Blameless post-mortems focus on process and system failures (not individual mistakes) to produce more actionable improvements than blame-oriented reviews. - -## Core Findings - -1. **Fundamental Principle**: Every failure is a process failure, not a people failure -2. **Psychological Safety Effect**: Blameless approach enables honest disclosure of full context including mistakes and near-misses -3. **Process-Level Framing**: "What process gap allowed this to happen?" vs "Who made the mistake?" shifts improvement target from individual behavior to systemic reliability -4. **Complete Root Cause Analysis**: Participants share more information when not threatened with punishment -5. **Google SRE Origin**: Developed as core practice in Site Reliability Engineering at Google, founded by Benjamin Treynor Sloss in 2003 - -## Mechanism - -Blameless post-mortems work through psychological safety enabling honest disclosure. When participants know they will not be punished, they share complete context including their own mistakes. This produces more comprehensive root cause analysis than blame-oriented reviews where participants hide information for self-protection. Process-level framing shifts focus to systemic improvements. - -## Relevance - -Essential for incident response, organizational learning, reliability engineering. Applied in SRE practices, DevOps culture, continuous improvement. Fundamental for building high-reliability organizations and preventing repeat failures through systemic fixes rather than individual blame. - -## Related Research - -Connects to (Amy Edmondson) on psychological safety, (Sidney Dekker) on Just Culture, (John Allspaw) on post-mortem practices. Part of broader SRE methodology alongside error budgets, monitoring, automation. Related to learning organization principles and continuous improvement frameworks. \ No newline at end of file diff --git a/docs/research/software-engineering/process/calver_2020.md b/docs/research/software-engineering/process/calver_2020.md deleted file mode 100644 index b781ce3f..00000000 --- a/docs/research/software-engineering/process/calver_2020.md +++ /dev/null @@ -1,45 +0,0 @@ -# Calendar Versioning (CalVer, 2020) - -## Citation - -CalVer (2020). Calendar Versioning. https://calver.org - -## Source Type - -Specification - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Date-based version segments communicate release timing directly, suitable for projects with large/constantly-changing scope or time-sensitive releases. - -## Core Findings - -1. **Family of Schemes**: Not single scheme but flexible framework - YY.MINOR.MICRO (pip), YYYY.MM.DD (certifi), YY.0M (OpenSCAD) -2. **Standard Terminology**: YYYY/YY/0Y (year), MM/0M (month), WW/0W (week), DD/0D (day) segments -3. **Wide Adoption**: Ubuntu, Twisted, youtube-dl, pip, PyCharm, Unity, LibreOffice, OpenSCAD, Stripe API -4. **Compatibility Limitation**: CalVer alone doesn't signal breaking changes - some projects use hybrid SemVer+CalVer approach -5. **Three Key Use Cases**: Large/changing scope systems, time-sensitive releases, external-change-driven projects - -## Mechanism - -CalVer replaces arbitrary version increments with calendar-derived segments using Gregorian calendar and UTC convention. Date segments are 1-based (unlike traditional 0-based incremented versions) with short/zero-padded years relative to year 2000. Projects choose appropriate scheme based on release patterns and communication needs. - -## Relevance - -Essential for projects with time-based releases, security updates, business support schedules, large system coordination. Applied in operating systems, frameworks, security libraries, API versioning. Alternative to SemVer when semantic meaning is less relevant than temporal context. - -## Related Research - -Connects to (Preston-Werner, 2013) on Semantic Versioning as alternative approach. Part of broader software versioning strategies including hybrid approaches. Related to release management, dependency management, and software lifecycle practices. \ No newline at end of file diff --git a/docs/research/software-engineering/process/clegg_barker_1994.md b/docs/research/software-engineering/process/clegg_barker_1994.md deleted file mode 100644 index 80690375..00000000 --- a/docs/research/software-engineering/process/clegg_barker_1994.md +++ /dev/null @@ -1,45 +0,0 @@ -# MoSCoW Prioritization (Clegg & Barker, 1994) - -## Citation - -Clegg, D., & Barker, R. (1994). *Case Method Fast-Track: A RAD Approach*. Addison-Wesley. (DSDM origin.) - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Classifying requirements as Must/Should/Could/Won't forces explicit negotiation about what is essential vs. desired, preventing gold-plating. - -## Core Findings - -1. **Four Priority Categories**: Must have (critical), Should have (important but not necessary), Could have (desirable), Won't have (lowest priority/out of scope) -2. **DSDM Integration**: Originally developed by Dai Clegg in 1994 for Rapid Application Development, extensively used in Dynamic Systems Development Method from 2002 -3. **Effort Constraints**: DSDM mandates that Must requirements cannot exceed 60% of total effort -4. **Plain English Value**: Categories more meaningful than High/Medium/Low, helping customers understand priority impact -5. **Story-Level Application**: When applied within single story, reveals bloated stories that should be split - -## Mechanism - -MoSCoW forces explicit negotiation by using plain English categories that clarify business impact. The 60% constraint on Must requirements prevents scope creep. At story level, if only 3 of 12 examples are Must, the remaining 9 can be deferred, keeping stories focused and deliverable within timeboxes. - -## Relevance - -Essential for Agile development, requirements prioritization, scope management, minimum viable product definition. Applied in Scrum, RAD, DSDM methodologies. Fundamental for timeboxed delivery and preventing feature creep in iterative development approaches. - -## Related Research - -Connects to (Kano et al., 1984) on alternative prioritization methods. Part of broader Agile methodology alongside user stories and timeboxing. Related to scope management, minimum viable product concepts, and iterative development frameworks. diff --git a/docs/research/software-engineering/process/fagan_1976.md b/docs/research/software-engineering/process/fagan_1976.md deleted file mode 100644 index bcc624aa..00000000 --- a/docs/research/software-engineering/process/fagan_1976.md +++ /dev/null @@ -1,45 +0,0 @@ -# Design and Code Inspections (Fagan, 1976) - -## Citation - -Fagan, M. E. (1976). "Design and Code Inspections to Reduce Errors in Program Development." *IBM Systems Journal*, 15(3), 182–211. - -## Source Type - -Academic Paper - -## Method - -Experiment - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Structured inspections using checklists detect 60-90% of defects before testing, far more than unstructured walkthroughs by forcing reviewers to articulate specific failures. - -## Core Findings - -1. **Defect Detection Rate**: Structured inspections detect 60-90% of defects before testing phase -2. **Cost Effectiveness**: Fixing defects in early phases costs 10-100x less than fixing in maintenance phase -3. **Six-Phase Process**: Planning, Overview, Preparation, Inspection meeting, Rework, Follow-up -4. **Role-Based Review**: Author, Reader, Reviewers, Moderator, Recorder each have specific responsibilities -5. **Checklist-Driven**: Systematic checking against specific quality attributes prevents confirmation bias - -## Mechanism - -Fagan inspections constrain reviewer attention to overcome confirmation bias. Unstructured reviews allow skimming and overlooking defects through expectation confirmation. Structured inspection requires checking each quality attribute individually, forcing System 2 thinking. Self-declaration checklists (AGREE/DISAGREE criteria) prevent vague "looks good" approvals that hide defects. - -## Relevance - -Essential for code quality assurance, defect prevention, software inspection processes. Applied in formal review procedures, quality gates, peer review systems. Foundational for static analysis, code review practices, and quality assurance in software development lifecycle. - -## Related Research - -Connects to (Tversky & Kahneman, 1974) on confirmation bias, (Kahneman, 2011) on System 1/2 thinking. Part of broader software quality methodologies alongside testing, static analysis. Related to inspection techniques, peer review processes, and formal verification approaches. \ No newline at end of file diff --git a/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md b/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md deleted file mode 100644 index d3fcc863..00000000 --- a/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md +++ /dev/null @@ -1,63 +0,0 @@ -# flowr 1.0.0: Non-Deterministic State Machine Specification for Workflow Kneading - -## Citation - -nullhack/flowr. (2026). flowr v1.0.0. GitHub. https://github.com/nullhack/flowr - -## Source Type - -Software Release / Specification - -## Method - -Specification Review (official documentation at https://nullhack.github.io/flowr/) - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -flowr 1.0.0 is the first stable release of the non-deterministic state machine specification. It formalises the YAML format with a complete specification document, formal syntax grammar, conformance levels (MUST/SHOULD/MAY), extension field semantics, and reserved key registry. The specification defines what a workflow IS (structure, states, transitions, guards) not what it DOES (no execution engine, no side effects). - -## Core Findings - -1. **Formal Specification**: v1.0.0 introduces a complete specification with RFC 2119 key words (MUST, SHOULD, MAY), formal syntax grammar, normative examples, and visual reference diagrams. The specification is the contract; the CLI is a reference implementation. - -2. **Condition Operators**: The `~=` (approximate match) operator is removed. Supported operators: `==`, `!=`, `>=`, `<=`, `>`, `<`. Plain values without operator prefix are implicit `==`. Numeric extraction applies to both sides (e.g., `>=80%` vs `75%` compares 80 vs 75). - -3. **`when` Forms**: The `when` field on transitions accepts three forms: a dict (inline condition-map), a string (reference to a named condition group), or a list (mix of named refs and inline dicts). All conditions are AND-combined. - -4. **Named Condition Groups**: States define `conditions:` blocks with reusable condition sets. Transitions reference them by name in `when:` clauses. Unknown references to groups defined on other states are validation errors. - -5. **Extension Fields and Reserved Keys**: Flow definitions MAY contain non-reserved fields that the validator ignores. Reserved keys: `flow`, `version`, `params`, `exits`, `attrs`, `states`, `id`, `next`, `to`, `when`, `conditions`, `flow-version`. The `attrs` field is the designated extension point for implementation-specific data. - -6. **Params with Defaults**: `params` supports both simple string lists (required) and objects with `name` and optional `default` fields. Params without defaults must be provided at invocation time. - -7. **Conformance Levels**: MUST (required for all conforming implementations), SHOULD (recommended, optional), MAY (optional extension). Conforming implementations must satisfy all MUST rules. - -8. **Validation Rules**: Seven MUST-level checks at load time: every `next` target resolves, no ambiguous targets, parent `next` keys match child `exits`, no cross-flow cycles, exit names referenced by at least one state, named condition references resolve, params without defaults provided. - -9. **Subflow Semantics**: `flow:` on a state makes it a subflow invocation. `flow-version` constrains compatible child versions via semver ranges. Parent `next` keys must match child `exits` exactly. Call-stack push on entry, pop on exit. Cross-flow cycles forbidden, within-flow cycles allowed. - -10. **Session Model**: Sessions track `flow`, `state`, `name`, `created_at`, `updated_at`, `stack`, `params`. Atomic writes (temp-file-then-rename). Filesystem is the source of truth. - -11. **Semver Conventions**: Adding a new exit is a minor bump. Adding states is a patch. Removing or renaming exits is a major (breaking) change. - -12. **CLI Reference**: Commands include `validate`, `states`, `check`, `next`, `transition`, `mermaid`, `config`, and session subcommands (`init`, `show`, `set-state`, `list`). All commands output JSON by default with `--text` for human-readable. `--session` flag makes any command session-aware. - -## Mechanism - -flowr defines what a workflow IS, not what it DOES. No execution engine, no side effects, no opinions about retries, timeouts, or error handling. A YAML file declares structure. A validator checks integrity. Tools query, track, and visualise. The format is the foundation. By giving a precise definition to the format, shared tooling (validators, editors, visualisers, session trackers) works across any project that adopts the specification. - -## Relevance - -flowr is the workflow engine that powers temple8's flow-based delivery system. The 1.0.0 release stabilises the specification that the golden rules depend on: session management replaces manual session editing (Rule 1), flow name resolution simplifies CLI usage, configuration from pyproject.toml removes hardcoded paths, and the formal validation rules enforce structural integrity at load time. - -## Related Research - -Connects to finite state machine theory (Harel, 1987), workflow management patterns (Russell et al., 2006), and the temple8 knowledge files on flowr specification and operations. diff --git a/docs/research/software-engineering/process/preston-werner_2013.md b/docs/research/software-engineering/process/preston-werner_2013.md deleted file mode 100644 index 69a2520e..00000000 --- a/docs/research/software-engineering/process/preston-werner_2013.md +++ /dev/null @@ -1,45 +0,0 @@ -# Semantic Versioning 2.0.0 (Preston-Werner, 2013) - -## Citation - -Preston-Werner, T. (2013). Semantic Versioning 2.0.0. https://semver.org - -## Source Type - -Specification - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Version numbers follow MAJOR.MINOR.PATCH format encoding compatibility intent to enable automated dependency resolution and prevent dependency hell. - -## Core Findings - -1. **Three-Part Versioning**: MAJOR.MINOR.PATCH where MAJOR for incompatible API changes, MINOR for backward-compatible additions, PATCH for backward-compatible bug fixes -2. **Build Metadata Independence**: Build metadata (after `+`) provides arbitrary information without affecting version precedence - `1.0.0+20260430` and `1.0.0` have same precedence -3. **Pre-release Ordering**: Pre-release versions (after `-`) have lower precedence than normal versions: `1.0.0-alpha < 1.0.0` -4. **Dependency Resolution**: Enables automated package management with range specifications like `>=3.1.0 <4.0.0` preventing dependency hell -5. **Public API Declaration**: Requires clear, precise public API definition as foundation for meaningful version communication - -## Mechanism - -SemVer encodes compatibility intent in version number itself. MAJOR increments signal breaking changes requiring consumer updates; MINOR increments signal safe additions; PATCH increments signal safe fixes. Build metadata suffix (§10) allows arbitrary data (dates, commit hashes) without affecting dependency solver precedence calculations. - -## Relevance - -De facto standard for software versioning, essential for package management systems (npm, pip, Maven), continuous integration, API evolution communication. Foundational for dependency resolution algorithms, semantic release automation, software distribution strategies. - -## Related Research - -Created by Tom Preston-Werner (GitHub co-founder, Gravatar inventor) in 2013. Based on widespread existing practices in open/closed-source software. Influences modern package managers, CI/CD systems, release automation tools. Licensed under Creative Commons CC BY 3.0, maintained as open specification. \ No newline at end of file diff --git a/docs/research/software-engineering/process/procedural_checklists_synthesis.md b/docs/research/software-engineering/process/procedural_checklists_synthesis.md deleted file mode 100644 index 9bd2a345..00000000 --- a/docs/research/software-engineering/process/procedural_checklists_synthesis.md +++ /dev/null @@ -1,52 +0,0 @@ -# Procedural Checklists and Initiation Anchors (Synthesis, 2026) - -## Citation - -- Federal Aviation Administration. (2017). *Checklist Design* (AC 120-71b). U.S. Department of Transportation. -- Gawande, A. (2009). *The Checklist Manifesto: How to Get Things Right*. Metropolitan Books. -- World Health Organization. (2008). *WHO Surgical Safety Checklist Implementation Manual* (1st ed.). -- Haynes, A. B., et al. (2009). A surgical safety checklist to reduce morbidity and mortality in a global population. *New England Journal of Medicine*, 360, 491–499. -- Finley, J. R. (2018). Self-Generated Memory Cues: Effective Tools for Learning, Training, and Remembering. *Policy Insights from the Behavioral and Brain Sciences*, 5(2), 189–197. - -## Source Type - -Industry Standard - -## Method - -Aviation incident analysis (Boeing 299 crash, 1935), prospective sequential time-series study (8 hospitals, WHO SSC), regulatory guidance synthesis (FAA AC 120-71b) - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Checklists must be anchored to clear external cues that cannot be forgotten, and each gate requires explicit challenge-response confirmation before proceeding. Floating initiation and collapsed phases are the primary failure modes. - -## Core Findings - -1. **Initiation anchors prevent skip failures.** FAA AC 120-71b §5.1.5: checklist initiation must be anchored to a clear external cue (e.g., reaching 2,000 feet before hold-short line). "Floating" initiation (no external trigger) has high risk of being forgotten entirely. -2. **Challenge-response ensures explicit confirmation.** Aviation uses two-person read-respond. WHO SSC uses three phases (Sign In, Time Out, Sign Out) with a coordinator who must confirm completion before the team proceeds. -3. **Interruption recovery requires restarting.** FAA AC 120-71b §5.2.3: if a checklist is interrupted and position is unclear, the section must be reaccomplished from the beginning. Partial completion is never trusted. -4. **Cue distinctiveness prevents overload.** Finley (2018): effective cues are distinctive (single mapping), encoding-specific (overlap with task context), and stable (consistent across environments). Cue overload degrades reliability. -5. **Structured pause points drive the effect.** Haynes et al. (2009): WHO SSC reduced complications 11.0%→7.0% and mortality 1.5%→0.8%. The mechanism was not individual items but forced communication at phase transitions. -6. **Multi-phase collapse loses fail-fast.** Collapsing checklist phases (e.g., running all review tiers in one pass) eliminates independent gates. Each phase can fail independently and should stop the sequence. - -## Mechanism - -Checklists work by externalizing procedural memory into explicit confirmation steps at phase boundaries. The initiation anchor creates a reliable trigger that cannot be forgotten. Challenge-response forces attention reset at each item. Interruption recovery prevents partial-completion confidence. Together these prevent the three main failure modes: forgetting to start, skipping items, and trusting incomplete sequences. - -## Relevance - -Applied to agentic workflow orchestration: the `[~]` anchor item in the todo template is the initiation anchor for state exit. The 6-point anchor checklist (dispatch completed, single-state scope, flowr next checked, transition executed, todo rewritten, no state skipped) is the challenge-response gate. The single-dispatch rule prevents multi-state collapse. If the anchor reveals a problem, the state is reaccomplished from the beginning (interruption recovery). This maps directly to FAA AC 120-71b's pattern of flow → checklist → confirmation at each phase boundary. - -## Related Research - -- [[software-craft/tdd]]: two-phase quality gate (design-phase: test-fast only; convention-phase: lint/format) -- [[workflow/flowr-operations]]: flowr commands for state transitions -- [[requirements/pre-mortem]]: pre-mortem analysis as a checklist item before example writing diff --git a/docs/research/software-engineering/process/reinertsen_2009.md b/docs/research/software-engineering/process/reinertsen_2009.md deleted file mode 100644 index 1b7ebacd..00000000 --- a/docs/research/software-engineering/process/reinertsen_2009.md +++ /dev/null @@ -1,45 +0,0 @@ -# The Principles of Product Development Flow (WSJF) (Reinertsen, 2009) - -## Citation - -Reinertsen, D. G. (2009). *The Principles of Product Development Flow: Second Generation Lean Product Development*. Celeritas Publishing. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Weighted Shortest Job First (WSJF), calculated as Cost of Delay divided by Duration, optimizes product development work sequencing by prioritizing items where delay is most costly relative to implementation time. - -## Core Findings - -1. **WSJF Formula**: Cost of Delay ÷ Duration provides quantitative ranking replacing subjective prioritization -2. **Cost of Delay Quantification**: "One thing" to quantify - partial derivative of total expected value with respect to time ($/time units) -3. **CD3 Algorithm**: "Cost of Delay Divided by Duration" maximizes total value delivered by scarce development capacity -4. **Manager Knowledge Gap**: ~85% of product managers don't know their Cost of Delay -5. **Intuition Failure**: Intuitive Cost of Delay estimates differ by 50:1 ratio, making quantification essential - -## Mechanism - -WSJF transforms subjective prioritization into quantitative ranking. Cost of Delay captures economic impact of not doing work now. Duration normalizes for effort. The ratio identifies work delivering most value per unit time invested. "CD3" scheduling algorithm maximizes value in any given time period. - -## Relevance - -Essential for product management, agile prioritization, lean development. Applied in feature prioritization, backlog management, resource allocation. Foundational for SAFe (Scaled Agile Framework) prioritization and quantitative product development flow optimization. - -## Related Research - -Created by Donald G. Reinertsen, author of "Managing the Design Factory" (1997). Cost of Delay concept described as "golden key that unlocks many doors" with "astonishing power to transform development organization mindset." Adopted in SAFe methodology and lean-agile practices worldwide. diff --git a/docs/research/software-engineering/quality/bay_2008.md b/docs/research/software-engineering/quality/bay_2008.md deleted file mode 100644 index 51c3515d..00000000 --- a/docs/research/software-engineering/quality/bay_2008.md +++ /dev/null @@ -1,46 +0,0 @@ -# Object Calisthenics (Bay, 2008) - -## Citation - -Bay, J. (2008). "Object Calisthenics." In *The ThoughtWorks Anthology*, pp. 65–78. Pragmatic Bookshelf. - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -Moderate - -## Key Insight - -Nine syntactic constraints force developers to distribute behavior rather than centralize data, producing significantly better object-oriented designs through structural pressure. - -## Core Findings - -1. **Extreme constraints methodology**: Nine rules including "no more than two instance variables per class" and "no getters/setters/properties" create structural pressure toward better designs. -2. **Anti-pattern prevention**: "No more than two instance variables" prevents god-object anti-pattern by making it impossible to hold all related data in one class, forcing decomposition into collaborating objects. -3. **Training wheels philosophy**: Constraints are intentionally extreme - they are temporary training tools, not permanent rules - but design habits they produce persist after constraints are relaxed. -4. **Behavior distribution**: Forces small, focused classes with clear responsibilities and behavior-rich objects rather than data containers. -5. **ThoughtWorks methodology**: Published as part of ThoughtWorks Anthology, reflecting company's agile software development practices and expertise. - -## Mechanism - -Constraints create structural pressure toward small, focused classes with clear responsibilities. Extreme limitations make poor design choices impossible, forcing developers to find alternative approaches that result in better object-oriented structure. Design habits developed under constraints (small classes, behavior-rich objects, encapsulated data) persist after constraints are relaxed. - -## Relevance - -Valuable training methodology for developing better object-oriented design skills. Useful for teams struggling with large classes, anemic domain models, or excessive coupling. Educational tool for understanding principles behind good OOP design through extreme application. - -## Related Research - -- (Martin, 2000): SOLID principles providing theoretical foundation for good OOP design -- (Fowler, 1999): Refactoring techniques for improving object-oriented design incrementally \ No newline at end of file diff --git a/docs/research/software-engineering/quality/beck_2002.md b/docs/research/software-engineering/quality/beck_2002.md deleted file mode 100644 index 890372bf..00000000 --- a/docs/research/software-engineering/quality/beck_2002.md +++ /dev/null @@ -1,48 +0,0 @@ -# Test-Driven Development (Beck, 2002) - -## Citation - -Beck, K. (2002). *Test-Driven Development: By Example*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The RED-GREEN-REFACTOR cycle (write a failing test, write the minimum code to pass it, then improve the structure while keeping all tests green) drives better design by forcing each unit of behaviour to be specified before it is implemented. - -## Core Findings - -1. Tests written first act as specifications, not verification, preventing over-engineering and ensuring every piece of code has a reason to exist -2. The RED phase forces developers to articulate what they want before building it -3. The GREEN phase constrains implementation to the minimum that satisfies the specification, preventing speculative generalisation -4. The REFACTOR phase is safe because all existing tests remain green, providing a regression net -5. The cycle produces small, focused, well-tested units of code because each unit must be both specifiable (testable) and minimal (just enough to pass) -6. Two basic rules: (1) Never write a single line of code unless you have a failing automated test, (2) Eliminate duplication - -## Mechanism - -TDD works by inverting the traditional development flow. Instead of writing code then testing it, developers first write failing tests that specify desired behavior. This forces clear thinking about requirements and interfaces before implementation. The requirement to make tests pass with minimal code prevents over-engineering, while the refactoring phase improves design quality under the safety net of comprehensive test coverage. - -## Relevance - -Foundational methodology for software quality assurance and design. TDD has become a cornerstone practice in agile development, influencing modern software engineering through improved code quality, better design, and increased developer confidence in changes. Essential for understanding test-first approaches and the relationship between testing and design. - -## Related Research - -- (Beck, 1999) - Extreme Programming Explained, which introduced TDD as part of XP practices -- (Fowler et al., 1999) - Refactoring book co-authored by Beck, providing systematic approach to code improvement -- (Beck & Gamma, 2004) - JUnit framework implementation demonstrating TDD principles in practice \ No newline at end of file diff --git a/docs/research/software-engineering/quality/boehm_1981.md b/docs/research/software-engineering/quality/boehm_1981.md deleted file mode 100644 index 107b1025..00000000 --- a/docs/research/software-engineering/quality/boehm_1981.md +++ /dev/null @@ -1,48 +0,0 @@ -# Software Engineering Economics (Boehm, 1981) - -## Citation - -Boehm, B. W. (1981). *Software Engineering Economics*. Englewood Cliffs, NJ: Prentice-Hall. ISBN 0-13-822122-7. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -The cost of fixing a software defect escalates by roughly an order of magnitude at each subsequent lifecycle phase, from 1× during requirements to 100× after deployment. - -## Core Findings - -1. **Phase-dependent cost escalation**: Based on TRW and IBM project data, the relative cost to fix a defect grows exponentially with phase: requirements (1×), design (~5×), implementation (~10×), unit test (~20×), acceptance test (~50×), and operations (~100–1000×). -2. **Quantified defect origin**: Roughly 60–80% of defects originate in requirements and design, yet the majority of fix effort is expended during later phases when those defects are discovered. -3. **Early investment leverage**: Investing in requirements verification and design reviews yields disproportionately high returns because each defect caught early avoids the multiplicative cost of late-phase remediation. -4. **COCOMO foundation**: The data underpins the Constructive Cost Model (COCOMO), which quantifies how project attributes (complexity, team capability, schedule pressure) affect effort and defect rates. -5. **Software cost dominance**: Boehm demonstrated that software costs (not hardware) would dominate system budgets, reversing the prevailing assumption of his era. - -## Mechanism - -The exponential cost curve arises because late-phase defect fixes require re-traversing all upstream work: re-specifying, re-designing, re-implementing, and re-verifying. A requirements error found in operations forces revisiting every downstream artifact, whereas catching it during requirements review costs only the specification revision. The mechanism is compounding rework. Each phase that passes with an undetected defect adds a layer of dependent decisions and artifacts that must also be corrected. - -## Relevance - -Directly justifies investment in upfront specification (event storming, domain modeling, ubiquitous language) and early validation (BDD scenarios, TDD) in our workflow. The 10× per phase curve means that a defect caught in review costs 1× what it would cost in production, validating the economic case for design-phase quality gates and the "shift left" principle embedded in our flow. - -## Related Research - -- (Boehm, 1991): Risk management framework building on COCOMO cost data -- (Fagan, 1976): Code inspection as a cost-effective early detection technique -- (Beck, 2002): TDD as a practice that shifts defect detection leftward -- (Boehm & Basili, 2005): Condensed "Top 10 Defect Reduction" list restating the 100× cost ratio with updated data \ No newline at end of file diff --git a/docs/research/software-engineering/quality/demillo_lipton_sayward_1978.md b/docs/research/software-engineering/quality/demillo_lipton_sayward_1978.md deleted file mode 100644 index 38d45c4d..00000000 --- a/docs/research/software-engineering/quality/demillo_lipton_sayward_1978.md +++ /dev/null @@ -1,45 +0,0 @@ -# Mutation Testing (DeMillo, Lipton & Sayward, 1978) - -## Citation - -DeMillo, R. A., Lipton, R. J., & Sayward, F. G. (1978). "Hints on test data selection: Help for the practicing programmer." *Computer*, 11(4), 34–41. - -## Source Type - -Academic Paper - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -A meaningful test fails when a mutation (small deliberate code change) is introduced - if test survives every mutation without failing, it tests nothing useful. - -## Core Findings - -1. **Competent Programmer Hypothesis**: Competent programmers write programs close to being correct behaviorally -2. **Coupling Effect**: Simple faults cascade to form other emergent faults, so detecting simple mutations catches complex bugs -3. **RIP Model**: Tests must Reach mutated statement, Infect program state, and Propagate incorrect state to output -4. **Equivalent Mutants Problem**: Some mutants produce behaviorally equivalent programs, creating analysis challenges -5. **Quality Measurement**: Mutation score (mutants killed / total mutants) provides objective test quality metric - -## Mechanism - -Mutation testing systematically introduces small bugs into code using mutation operators (arithmetic/relational/logical changes) and checks whether tests detect them. Tests failing to catch artificial bugs indicate weak test quality or missing edge cases. Strong mutation requires full RIP model satisfaction; weak mutation only requires reach/infect. - -## Relevance - -Essential for test quality assessment, TDD validation, regression testing. Applied in modern tools (PITest, Stryker, mutmut, cosmic-ray). Fundamental for measuring test effectiveness beyond code coverage, ensuring tests constrain actual behavior rather than implementation details. - -## Related Research - -Originally proposed by Richard Lipton (1971), developed by DeMillo, Lipton & Sayward (1978). First implementation by Timothy Budd (1980). Connects to (Jia & Harman, 2011) comprehensive survey. Modern applications in security testing, object-oriented mutation operators, higher-order mutants research. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/feathers_2004.md b/docs/research/software-engineering/quality/feathers_2004.md deleted file mode 100644 index 580f6f64..00000000 --- a/docs/research/software-engineering/quality/feathers_2004.md +++ /dev/null @@ -1,46 +0,0 @@ -# Working Effectively with Legacy Code (Feathers, 2004) - -## Citation - -Feathers, M. (2004). *Working Effectively with Legacy Code*. Prentice Hall. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Legacy code is code without tests - the safest way to modify it is to first write characterization tests that capture current behavior, then refactor under the safety net of those tests. - -## Core Findings - -1. **Legacy code definition**: Code without automated tests, making it dangerous to modify and prone to introducing bugs during changes. -2. **Characterization tests methodology**: Tests that document what code currently does (not what it should do) - essential when modifying untested code to create regression safety net. -3. **Seam-based approach**: Seams (parameter seams, link seams, preprocessing seams, object seams) are points where behavior can be varied without editing code - primary mechanism for getting legacy code under test. -4. **Test-first modification**: Process is identify seam, get code under test by writing characterization test at that seam, then refactor safely. -5. **"Edit and pray" elimination**: Replaces dangerous "modify and hope nothing breaks" approach with disciplined "test, then modify, then verify" cycle. - -## Mechanism - -Characterization tests differ from specification tests: they document what code currently does, not what it should do. This creates regression protection before any changes are made. Seams allow injecting test doubles at specific points without modifying production code. Process: identify seam, get code under test, write characterization test, then refactor. Avoids dangerous untested modifications. - -## Relevance - -Essential methodology for working with legacy codebases safely. Critical for organizations maintaining large existing systems without comprehensive test coverage. Foundational approach for incremental improvement of legacy systems and technical debt reduction. - -## Related Research - -- (Beck, 2002): Test-driven development providing methodology for new code development with tests -- (Fowler, 1999): Refactoring techniques that require test safety net provided by characterization tests \ No newline at end of file diff --git a/docs/research/software-engineering/quality/fowler_1999.md b/docs/research/software-engineering/quality/fowler_1999.md deleted file mode 100644 index 6770bdf3..00000000 --- a/docs/research/software-engineering/quality/fowler_1999.md +++ /dev/null @@ -1,46 +0,0 @@ -# Refactoring: Improving the Design of Existing Code (Fowler, 1999) - -## Citation - -Fowler, M. (1999). *Refactoring: Improving the Design of Existing Code*. Addison-Wesley. Second edition 2018 with K. Beck, J. Brant, W. Opdyke, D. Roberts. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Refactoring is disciplined technique for restructuring existing code without changing external behavior, done in small steps each verified by tests. - -## Core Findings - -1. **Catalog methodology**: 66 named transformations (Extract Method, Move Field, Replace Conditional with Polymorphism, etc.) each with known pre-condition, mechanic, and effect on code structure. -2. **Code smell diagnostics**: Diagnostic indicators (Long Method, Feature Envy, Switch Statements, etc.) signal when refactoring is needed and point to specific techniques. -3. **Test-driven safety**: Small, test-verified steps ensure restructuring doesn't introduce bugs while improving design quality. -4. **Behavior preservation**: External functionality remains unchanged while internal structure improves through systematic transformations. -5. **Design emergence**: Better design emerges through incremental improvements rather than upfront architectural decisions. - -## Mechanism - -Each refactoring has known pre-condition (when safe to apply), step-by-step mechanic (the transformation), and guaranteed post-condition (what improves). By applying refactorings in small, test-verified steps, developer can restructure code safely without introducing bugs. Code smells serve as diagnostic indicators pointing to specific refactoring technique most likely to improve structure. The smell identifies problem; refactoring provides solution. - -## Relevance - -Foundational methodology for systematic code improvement and design evolution. Essential practice for maintaining code quality, reducing technical debt, and enabling sustainable software development. Widely adopted as core agile development practice. - -## Related Research - -- (Beck, 2002): Test-driven development methodology supporting refactoring safety -- (Shvets, 2014): Comprehensive online refactoring catalog building on Fowler's work \ No newline at end of file diff --git a/docs/research/software-engineering/quality/freeman_pryce_2009.md b/docs/research/software-engineering/quality/freeman_pryce_2009.md deleted file mode 100644 index 1018ec31..00000000 --- a/docs/research/software-engineering/quality/freeman_pryce_2009.md +++ /dev/null @@ -1,45 +0,0 @@ -# GOOS: Growing Object-Oriented Software, Guided by Tests (Freeman & Pryce, 2009) - -## Citation - -Freeman, S., & Pryce, N. (2009). *Growing Object-Oriented Software, Guided by Tests*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Acceptance tests and unit tests operate at two separate nested timescales - outer loop writes failing acceptance tests before implementation; inner loop drives implementation with unit-level Red-Green-Refactor cycles. - -## Core Findings - -1. **Double Loop TDD**: Outer loop (acceptance tests) provides direction (what to build); inner loop (unit tests) provides momentum (how to build it) -2. **Nested Timescales**: Acceptance test stays red throughout all inner cycles and goes green only when feature is complete -3. **Direction vs Momentum**: Acceptance tests prevent over-engineering by defining "done"; unit tests drive good internal design -4. **Integration Safety**: Acceptance tests catch integration issues early while unit tests provide rapid feedback -5. **Mock Objects**: Use test doubles to maintain fast, isolated unit tests while preserving design feedback - -## Mechanism - -Outer loop begins with failing acceptance test for next feature, then enters inner loop of Red-Green-Refactor unit test cycles. Inner loop repeats (write failing unit test, make it pass with minimal code, refactor) until acceptance test passes. This structure provides safety nets at both levels for refactoring and ensures comprehensive test coverage. - -## Relevance - -Essential for advanced TDD practices, BDD implementation, acceptance test-driven development. Applied in enterprise software development, continuous integration, behavior-driven development. Foundational for understanding relationship between unit and acceptance testing in agile methodologies. - -## Related Research - -Connects to (Beck, 2002) on TDD fundamentals, (North, 2006) on BDD practices. Part of broader testing methodologies alongside ATDD, specification by example. Related to mock object patterns and test double strategies for maintainable test suites. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/gamma_et_al_1994.md b/docs/research/software-engineering/quality/gamma_et_al_1994.md deleted file mode 100644 index bfb50977..00000000 --- a/docs/research/software-engineering/quality/gamma_et_al_1994.md +++ /dev/null @@ -1,46 +0,0 @@ -# Design Patterns: Elements of Reusable Object-Oriented Software (Gamma, Helm, Johnson, Vlissides, 1994) - -## Citation - -Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Design patterns provide reusable solutions to recurring design problems by naming proven structural approaches that teams can communicate at higher abstraction level. - -## Core Findings - -1. **Pattern catalog**: 23 design patterns divided into three categories by intent: Creational (abstracting object creation), Structural (composing classes/objects into larger structures), Behavioral (allocating responsibility between objects). -2. **Communication abstraction**: Patterns name recurring design structures enabling teams to communicate at higher level - saying "Strategy pattern" conveys entire structural solution. -3. **Problem-solution mapping**: Each pattern captures proven solution to specific class of design problem - Strategy eliminates type-switching, Observer decouples event sources from handlers, State replaces conditional state machines. -4. **Foundational principles**: "Program to interface, not implementation" and "Favor object composition over class inheritance" guide pattern application. -5. **Massive influence**: Over 500,000 copies sold in 14 languages, ACM SIGPLAN Programming Languages Achievement Award 2005, foundational for object-oriented design. - -## Mechanism - -Patterns work by naming recurring design structures so teams can communicate at higher level of abstraction. Each pattern captures proven solution to specific class of design problem. Patterns should be applied only when code smell triggers them, never speculatively. The smell identifies the gap; the pattern provides structural solution. - -## Relevance - -Foundational reference for object-oriented design and software architecture. Essential vocabulary for software development teams and architectural decision-making. Widely adopted across programming languages and frameworks for systematic design improvement. - -## Related Research - -- (Fowler, 1999): Refactoring methodology that prepares code for pattern application -- (Shvets, 2014): Modern catalog connecting code smells to appropriate patterns \ No newline at end of file diff --git a/docs/research/software-engineering/quality/google_testing_2013.md b/docs/research/software-engineering/quality/google_testing_2013.md deleted file mode 100644 index 5a663d8a..00000000 --- a/docs/research/software-engineering/quality/google_testing_2013.md +++ /dev/null @@ -1,45 +0,0 @@ -# Test-Behavior Alignment (Google Testing Blog, 2013) - -## Citation - -Google Testing Blog. (2013). "Testing on the Toilet: Test Behavior, Not Implementation." By Andrew Trenk. *Google Testing Blog*. - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Test setup may need to change if implementation changes, but the actual test assertion should not need to change if the code's user-facing behavior doesn't change. - -## Core Findings - -1. **Implementation Independence**: Tests should focus on testing code's public API, not internal implementation details -2. **Maintenance Benefits**: Tests independent of implementation details are easier to maintain since they don't need changes with each implementation change -3. **Documentation Value**: Behavior-focused tests act as code samples showing different ways class methods can be used -4. **Setup vs Assertion**: Test setup may change with implementation (e.g., new constructor dependencies) but assertions should remain stable -5. **Brittleness Prevention**: Tests tightly coupled to implementation details break during refactoring and become drag on design improvement - -## Mechanism - -Implementation-focused tests verify internal structure (method calls, object creation, internal state) creating brittleness. Behavior-focused tests verify observable outcomes that users can witness, providing stability. Former creates maintenance overhead; latter provides lasting value through internal rewrites. - -## Relevance - -Essential for maintainable test suites, refactoring safety, TDD practices. Applied in contract testing, behavior-driven development, test design principles. Foundational for writing tests from caller's perspective without knowledge of internal implementation mechanics. - -## Related Research - -Connects to (Freeman & Pryce, 2009) on GOOS principles, (Fowler, 2018) on Test Pyramid. Part of broader testing methodologies alongside TDD, BDD, contract testing. Related to mock object patterns and test double strategies for behavior verification. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/maciver_2016.md b/docs/research/software-engineering/quality/maciver_2016.md deleted file mode 100644 index adf97ebf..00000000 --- a/docs/research/software-engineering/quality/maciver_2016.md +++ /dev/null @@ -1,47 +0,0 @@ -# Property-Based Testing (MacIver, 2016) - -## Citation - -MacIver, D. R. (2016). "What is Property Based Testing?" *Hypothesis*. https://hypothesis.works/articles/what-is-property-based-testing/ - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Property-based testing constructs tests such that when these tests are fuzzed with generated inputs, failures reveal problems that could not have been revealed by direct fuzzing alone. - -## Core Findings - -1. Meaningful property tests assert invariants: things that must always be true about the contract -2. Tautological tests assert reconstruction patterns that merely verify the implementation without constraining behavior -3. Property tests generate diverse inputs to verify that certain properties hold across the entire input space -4. This approach discovers edge cases that example-based tests typically miss and provides stronger confidence in correctness -5. Property-based testing complements example-based BDD scenarios by providing broader coverage of the input space - -## Mechanism - -Property tests work by generating diverse inputs to verify that certain properties (invariants) hold across the entire input space. Unlike example-based tests that check specific scenarios, property tests explore the full domain of possible inputs, automatically discovering edge cases that developers typically miss. The key is focusing on behavioral contracts rather than implementation details. - -## Relevance - -Essential for comprehensive test coverage in software quality assurance. Property-based testing complements traditional BDD scenarios by providing mathematical rigor to test validation. Particularly valuable for testing complex algorithms, data transformations, and API contracts where exhaustive example-based testing is impractical. - -## Related Research - -- (Claessen & Hughes, 2000) - Original QuickCheck paper establishing property-based testing foundations -- (Fink & Bishop, 1997) - Early work on property-based testing for software assurance -- (MacIver et al., 2019) - Hypothesis library implementation extending QuickCheck concepts to Python \ No newline at end of file diff --git a/docs/research/software-engineering/quality/martin_2000_solid.md b/docs/research/software-engineering/quality/martin_2000_solid.md deleted file mode 100644 index db20dade..00000000 --- a/docs/research/software-engineering/quality/martin_2000_solid.md +++ /dev/null @@ -1,47 +0,0 @@ -# SOLID Principles (Martin, 2000) - -## Citation - -Martin, R. C. (2000). Design Principles and Design Patterns. Object Mentor. [PDF archived at Internet Archive] - -## Source Type - -Practitioner Book - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Five object-oriented design principles that reduce coupling and increase maintainability when applied together. - -## Core Findings - -1. **Single Responsibility Principle (SRP)**: A class should have only one reason to change. Each class should have only one responsibility. -2. **Open-Closed Principle (OCP)**: Software entities should be open for extension but closed for modification. -3. **Liskov Substitution Principle (LSP)**: Derived classes must be substitutable for their base classes without altering program correctness. -4. **Interface Segregation Principle (ISP)**: Clients should not be forced to depend on interface methods they don't use. -5. **Dependency Inversion Principle (DIP)**: Depend on abstractions, not concrete implementations. -6. The SOLID acronym was coined around 2004 by Michael Feathers to make these principles memorable. - -## Mechanism - -Each principle addresses specific coupling pathologies: SRP prevents god-objects by enforcing single responsibility; OCP prevents modification cascades by enabling extension over modification; LSP prevents behavioral contract violations in inheritance hierarchies; ISP prevents fat interfaces that force unnecessary dependencies; DIP enables loose coupling by inverting dependencies toward abstractions. Together they reduce change propagation and make systems more testable. - -## Relevance - -Foundational for modern software architecture and clean code practices. Directly applicable to module design, interface definitions, and refactoring strategies. Essential for creating maintainable codebases that can evolve without breaking existing functionality. - -## Related Research - -- (Fowler, 1999): Refactoring patterns that support SOLID principles -- (Beck, 2002): Test-driven development practices that reinforce these design principles \ No newline at end of file diff --git a/docs/research/software-engineering/quality/martin_2017_first_class_tests.md b/docs/research/software-engineering/quality/martin_2017_first_class_tests.md deleted file mode 100644 index 92ded35c..00000000 --- a/docs/research/software-engineering/quality/martin_2017_first_class_tests.md +++ /dev/null @@ -1,45 +0,0 @@ -# Test Contra-variance (First-Class Tests) (Martin, 2017) - -## Citation - -Martin, R. C. (2017). "Test Contra-variance." *Clean Coder Blog*, October 3, 2017. - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Tests should be treated as first-class citizens with independent structural design - not coupled mirror images of production code structure. - -## Core Findings - -1. **Structural Contra-variance**: Test structure should not mirror production code structure (one test class per production class creates fragile coupling) -2. **Behavioral Contra-variance**: As tests become more specific, production code becomes more generic, moving in opposite directions along generality axis -3. **Fragile Test Problem**: Covariant test structure causes large test changes from small production changes, breaking refactoring workflows -4. **Decoupling Through Generalization**: Generalizing production code to satisfy test specifications creates behavioral decoupling while maintaining correctness -5. **Independent Test Design**: Tests need their own architectural design to minimize coupling while maintaining behavioral verification - -## Mechanism - -Covariant test structure (mirroring production classes) creates tight coupling preventing safe refactoring. Contra-variant approach: tests maintain stable public API focus while production code extracts classes/methods behind interface. Tests become increasingly specific behavioral specifications; production code generalizes to satisfy broader spectrum of behaviors than tests specify. - -## Relevance - -Essential for sustainable TDD practices, refactoring safety, test maintenance. Applied in contract testing, API design, behavior-driven development. Fundamental for writing tests that enable rather than obstruct design improvements and architectural evolution. - -## Related Research - -Part of Robert C. Martin's Clean Code philosophy. Connects to (Beck, 2002) TDD principles, (Freeman & Pryce, 2009) GOOS methodology. Related to test design patterns, mock object strategies, behavioral specification approaches. Foundational for understanding test-production code relationships. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/meszaros_2007.md b/docs/research/software-engineering/quality/meszaros_2007.md deleted file mode 100644 index cfde2b8c..00000000 --- a/docs/research/software-engineering/quality/meszaros_2007.md +++ /dev/null @@ -1,46 +0,0 @@ -# xUnit Test Patterns (Meszaros, 2007) - -## Citation - -Meszaros, G. (2007). *xUnit Test Patterns: Refactoring Test Code*. Addison-Wesley. - -## Source Type - -Practitioner Book - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Tests should specify observable behavior, not verify implementation - coupling to internal details creates brittle tests that break during refactoring even when behavior is preserved. - -## Core Findings - -1. **Test coupling spectrum**: Four levels from most resilient to most brittle: end-to-end tests (highest), unit contract tests, property-based tests, and white-box tests (lowest, avoid). -2. **Implementation coupling danger**: Tests coupled to implementation details break when code is refactored even when behavior is preserved, producing false negatives that erode trust in test suite. -3. **Semantic alignment rule**: Tests must operate at same abstraction level as acceptance criterion they verify - if criterion says "user presses W," test sends W through actual input mechanism, not internal method call. -4. **Observable behavior focus**: Decoupled tests use public interfaces and assert on observable outcomes, remaining green through refactoring because they verify what system does, not how it does it. -5. **Test pattern catalog**: Comprehensive patterns for test organization, fixture management, result verification, and test code maintainability in xUnit frameworks. - -## Mechanism - -Test coupling arises when test depends on how system works internally rather than what it does externally. Coupled tests use private methods, internal state, or implementation-specific assertions. When implementation changes (even if behavior is identical), coupled tests fail, creating noise that trains developers to ignore test failures. Decoupled tests use public interfaces and assert on observable outcomes, remaining green through refactoring. - -## Relevance - -Essential reference for writing maintainable test code in xUnit frameworks (JUnit, NUnit, etc.). Foundational for test-driven development practices and ensuring tests support rather than hinder refactoring. Widely used for improving test suite quality and reducing test maintenance burden. - -## Related Research - -- (Beck, 2002): Test-driven development methodology using xUnit frameworks -- (Fowler, 1999): Refactoring techniques that tests must support without breaking \ No newline at end of file diff --git a/docs/research/software-engineering/quality/north_2006.md b/docs/research/software-engineering/quality/north_2006.md deleted file mode 100644 index 10f04e28..00000000 --- a/docs/research/software-engineering/quality/north_2006.md +++ /dev/null @@ -1,45 +0,0 @@ -# Behaviour-Driven Development (North, 2006) - -## Citation - -North, D. (2006). "Introducing BDD." *Better Software Magazine*, March 2006. Originally published at dannorth.net. - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -BDD refines TDD by writing tests in domain language of business (Given/When/Then), making them specifications rather than verification tools. - -## Core Findings - -1. **Test Method Names as Sentences**: Using "should" template (The class *should* do something) keeps tests focused and creates readable documentation -2. **Behaviour vs Test Vocabulary**: Word "behaviour" eliminates TDD coaching confusion - what to test, when to delete tests, test naming becomes clear -3. **Given/When/Then Template**: Structured format captures acceptance criteria as executable specifications that business stakeholders can validate -4. **Ubiquitous Language for Analysis**: BDD provides consistent vocabulary bridging technical and business domains throughout entire analysis process -5. **Business Value Focus**: "What's the next most important thing the system doesn't do?" drives feature prioritization and development direction - -## Mechanism - -By requiring tests written in domain vocabulary (not implementation language), BDD forces shared understanding between domain experts and developers. "Given a registered user / When user logs in / Then user sees welcome message" specifies observable behaviour stakeholders care about, not technical implementation steps. Eliminates implementation coupling from specifications. - -## Relevance - -Foundational for behavior-driven development practices, acceptance test-driven development, specification by example. Essential for bridging business-technical communication gaps, creating living documentation, automated acceptance testing frameworks like Cucumber. - -## Related Research - -Created by Dan North, influenced by Eric Evans' Domain-Driven Design ubiquitous language concept, Chris Matts' business value focus. Led to development of JBehave framework, Ruby RSpec project, Cucumber framework. Foundational for modern BDD tools and practices, specification by example methodologies. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/shvets_2014.md b/docs/research/software-engineering/quality/shvets_2014.md deleted file mode 100644 index b83463fe..00000000 --- a/docs/research/software-engineering/quality/shvets_2014.md +++ /dev/null @@ -1,46 +0,0 @@ -# Refactoring.Guru (Shvets, 2014) - -## Citation - -Shvets, A. (2014–present). *Refactoring.Guru*. https://refactoring.guru/ - -## Source Type - -Blog/Article - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Refactoring follows systematic catalog of 66 techniques triggered by 21 code smells, creating diagnostic chain from problem identification to pattern application. - -## Core Findings - -1. **Smell-first methodology**: 21 code smells organized into 5 categories (Bloaters, OO Abusers, Change Preventers, Dispensables, Couplers) drive refactoring decisions. -2. **Systematic technique catalog**: 66 refactoring techniques organized into 6 categories (Composing Methods, Moving Features between Objects, Organizing Data, Simplifying Conditional Expressions, Simplifying Method Calls, Dealing with Generalization). -3. **Pattern-smell connection**: Each of 22 GoF design patterns triggered by specific code smell, creating motivation for pattern application. -4. **Diagnostic methodology**: Smell → refactoring technique → design pattern progression prevents speculative application. -5. **Visual learning approach**: Comprehensive illustrations and examples make complex concepts accessible to practitioners. - -## Mechanism - -The catalog provides smell-first approach: identify code smell, then apply corresponding refactoring technique or design pattern. Five smell categories group related pathologies: Bloaters (structures grown too large), OO Abusers (misapplied OOP), Change Preventers (changes that ripple), Dispensables (dead weight), Couplers (excessive inter-object dependency). Each smell entry links to refactoring techniques that resolve it, and each pattern entry explains which smell triggers it. Creates diagnostic chain where each step is motivated by previous one rather than applied speculatively. - -## Relevance - -Essential reference for code quality improvement, refactoring practice, and design pattern application. Widely used by developers for systematic code improvement and architectural decision-making. Provides practical methodology for identifying and resolving code quality issues. - -## Related Research - -- (Fowler, 1999): Foundational refactoring catalog and methodology -- (Gamma et al., 1995): Original Gang of Four design patterns catalog \ No newline at end of file diff --git a/docs/research/software-engineering/quality/wlaschin_2014.md b/docs/research/software-engineering/quality/wlaschin_2014.md deleted file mode 100644 index f24b55e8..00000000 --- a/docs/research/software-engineering/quality/wlaschin_2014.md +++ /dev/null @@ -1,50 +0,0 @@ -# Choosing Properties for Property-Based Testing (Wlaschin, 2014) - -## Citation - -Wlaschin, S. (2014). "Choosing properties for property-based testing" *F# for Fun and Profit*. https://fsharpforfunandprofit.com/posts/property-based-testing-2/ - -## Source Type - -Blog/Article - -## Method - -Theoretical with practical examples - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Seven recurring patterns help developers discover testable properties when they cannot think of any: "Different paths, same destination" (commutative diagram), "There and back again" (inverse function), "Some things never change" (invariant under transformation), "The more things change, the more they stay the same" (idempotence), "Solve a smaller problem first" (structural induction), "Hard to prove, easy to verify", and "The test oracle". - -## Core Findings - -1. The universal problem with property-based testing is not tooling but discovering what properties to test — developers stare at a blank screen unable to think of properties -2. Seven patterns cover most common cases: commutative operations, inverse pairs, invariants, idempotence, structural induction, easy-verification, and test oracles -3. "Different paths, same destination" applies when two operation sequences should produce the same result (e.g., addition is commutative) -4. "There and back again" applies when an operation and its inverse return to the starting state (e.g., serialize/deserialize) -5. "Some things never change" applies when a transformation preserves an invariant (e.g., sort preserves multiset of elements) -6. "Hard to prove, easy to verify" applies when finding the answer is complex but checking it is simple (e.g., prime factorisation — hard to find, easy to multiply back) -7. "The test oracle" applies when an alternate (simpler, slower) implementation exists to verify the production implementation -8. Model-based testing is a variant of the test oracle pattern: a simplified model runs in parallel with the system under test, and states are compared after each operation - -## Mechanism - -Rather than trying to enumerate all possible properties of a system, developers apply each of the seven patterns as lenses to examine the system's behaviour. Each pattern asks a different question: "Are there two ways to get the same result?" "Is there an inverse?" "What stays the same?" "What happens if I do it twice?" "Can I break it into smaller parts?" "Is the answer easy to check?" "Is there a reference implementation?" This structured approach overcomes the "blank screen" problem by providing concrete starting points for property discovery. - -## Relevance - -Essential for BDD example creation: the seven patterns provide a systematic method for deciding whether a Rule should use simple Examples or Scenario Outlines with parameterised inputs. When a pattern applies, it reveals which input combinations matter and whether the behaviour holds across a range of inputs. This directly informs the Example-vs-Scenario-Outline decision in the write-bdd-features skill. The patterns also surface missing Examples: if a pattern applies to a Rule but no Example covers the revealed combination, the specification is incomplete. - -## Related Research - -- (Claessen & Hughes, 2000) - QuickCheck: automatic testing of Haskell programs -- (MacIver, 2016) - Hypothesis library extending property-based testing to Python -- (Tillmann & Schulte, 2005) - PEX team at Microsoft compiled a complementary list of property patterns diff --git a/docs/research/software-engineering/requirements/christel_kang_1992.md b/docs/research/software-engineering/requirements/christel_kang_1992.md deleted file mode 100644 index 54d66bd1..00000000 --- a/docs/research/software-engineering/requirements/christel_kang_1992.md +++ /dev/null @@ -1,45 +0,0 @@ -# Issues in Requirements Elicitation (Christel & Kang, 1992) - -## Citation - -Christel, M. G., & Kang, K. C. (1992). *Issues in Requirements Elicitation*. CMU/SEI-92-TR-012. Software Engineering Institute, Carnegie Mellon University. https://www.sei.cmu.edu/library/abstracts/reports/92tr012.cfm - -## Source Type - -Academic Paper - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Stakeholders have three structural problems making direct questioning insufficient: omitting "obvious" information, trouble articulating unarticulated needs, not knowing what they want until seeing what they don't want. - -## Core Findings - -1. **Three Stakeholder Problems**: Omit obvious information, difficulty articulating tacit knowledge, discover needs reactively -2. **Expert Knowledge Nature**: Largely procedural and tacit - experts describe beliefs about what happens, not actual reality -3. **Elicitation Activities**: Fact-finding, requirements gathering, evaluation and rationalization, prioritization, integration -4. **Gap-Finding Necessity**: Required techniques that bypass expert's mental schema to uncover actual vs. perceived processes -5. **Specification vs. Elicitation**: Most tools focus on representation (specification) rather than discovery (elicitation) - -## Mechanism - -Expert knowledge is largely procedural and tacit. When asked "how does the system work?", experts describe their beliefs about what happens rather than observing actual processes. Gap-finding techniques are required because they bypass the expert's mental schema and reveal discrepancies between perceived and actual workflows. - -## Relevance - -Essential for requirements engineering, systems analysis, stakeholder interviews, business analysis. Applied in software development, system design, process improvement. Foundational for understanding why traditional interviewing fails and why observational techniques are necessary. - -## Related Research - -Connects to (Flanagan, 1954) on Critical Incident Technique for elicitation, (Fisher & Geiselman, 1987) on Enhanced Cognitive Interview methods. Part of broader requirements engineering methodology alongside prototyping and use case analysis. Related to tacit knowledge research and cognitive interview techniques. diff --git a/docs/research/software-engineering/requirements/cohn_2004.md b/docs/research/software-engineering/requirements/cohn_2004.md deleted file mode 100644 index b328cc30..00000000 --- a/docs/research/software-engineering/requirements/cohn_2004.md +++ /dev/null @@ -1,45 +0,0 @@ -# User Stories Applied (Cohn, 2004) - -## Citation - -Cohn, M. (2004). *User Stories Applied: For Agile Software Development*. Addison-Wesley. - -## Source Type - -Book - -## Method - -Industry practice synthesis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -User stories are a lightweight requirements format optimized for conversation rather than documentation. Story writing workshops produce initial coarse stories that are refined just-in-time during iteration planning. - -## Core Findings - -1. **Story Writing Workshops**: A collaborative session where the team identifies stories for the entire product. Stories start as brief titles on cards. Detailed acceptance criteria come later. -2. **Conditions of Satisfaction**: Each story has a list of conditions that must be true for the story to be complete. These are the precursor to Given/When/Then examples. -3. **Just-In-Time Detail**: Stories are deliberately vague at creation. Detail is added during backlog refinement and iteration planning, not during initial discovery. -4. **Story Splitting Patterns**: Complex stories are split using patterns: by data boundary, by operation, by business rule, by workflow step. Each split must produce independently valuable stories. -5. **INVEST Before Committing**: Stories must pass INVEST criteria before being committed to an iteration. Stories that fail are split or reworked. - -## Mechanism - -Stories are conversation placeholders, not specification documents. The card (title) serves as a commitment to have a conversation. The conversation fills in details. The confirmation (acceptance criteria) captures the agreement. This three-C model (Card, Conversation, Confirmation) prevents premature specification while ensuring shared understanding. - -## Relevance - -Cohn's story writing workshops are the mechanism for feature discovery: a collaborative session that produces coarse stories for all features. The conditions of satisfaction map to the `Rules (Business)` section in the feature template. The just-in-time refinement maps to the planning-flow's `feature-breakdown` state. - -## Related Research - -Popularized the Connextra user story template ("As a... I want... So that..."). Influenced by Beck's XP (1999) planning practices. Complements Patton's story mapping (2014): Cohn describes the story format and splitting patterns, Patton describes the mapping and prioritization process. diff --git a/docs/research/software-engineering/requirements/kano_et_al_1984.md b/docs/research/software-engineering/requirements/kano_et_al_1984.md deleted file mode 100644 index 13d0f777..00000000 --- a/docs/research/software-engineering/requirements/kano_et_al_1984.md +++ /dev/null @@ -1,45 +0,0 @@ -# Attractive Quality and Must-Be Quality (Kano Model) (Kano et al., 1984) - -## Citation - -Kano, N., Seraku, N., Takahashi, F., & Tsuji, S. (1984). "Attractive quality and must-be quality." *Journal of the Japanese Society for Quality Control*, 14(2), 39–48. - -## Source Type - -Academic Paper - -## Method - -Observational - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Customer satisfaction is not unidimensional - features fall into asymmetric categories enabling differentiated prioritization strategies. - -## Core Findings - -1. **Five Feature Categories**: Must-be (expected baseline), One-dimensional (more is better), Attractive (delighters), Indifferent (no impact), Reverse (negative impact) -2. **Asymmetric Satisfaction**: Must-be features don't increase satisfaction when present but cause dissatisfaction when absent; Attractive features delight when present but don't dissatisfy when absent -3. **Strategic Prioritization**: First ensure Must-be features exist, then maximize One-dimensional features, then selectively invest in Attractive features -4. **Temporal Evolution**: Features migrate from Attractive → One-dimensional → Must-be over time as customer expectations evolve -5. **Empirical Measurement**: Standardized functional/dysfunctional questionnaire pairs enable systematic feature classification - -## Mechanism - -Must-be features form satisfaction baseline - presence doesn't increase satisfaction but absence causes dissatisfaction. Attractive features provide asymmetric delight - presence surprises positively but absence goes unnoticed. This asymmetry enables strategic resource allocation focusing first on preventing dissatisfaction, then creating satisfaction. - -## Relevance - -Essential for product management, requirements prioritization, customer satisfaction strategy. Applied in Quality Function Deployment (QFD), feature roadmapping, competitive analysis. Foundational for understanding satisfaction drivers beyond linear assumptions in product development. - -## Related Research - -Developed by Noriaki Kano building on Herzberg's two-factor theory. Connects to (Herzberg, 1959) on hygiene vs motivator factors. Applied in Quality Function Deployment methodologies and modern product management frameworks. Related to Jobs-to-be-Done theory and customer outcome prioritization. diff --git a/docs/research/software-engineering/requirements/patton_2014.md b/docs/research/software-engineering/requirements/patton_2014.md deleted file mode 100644 index 13b53bbc..00000000 --- a/docs/research/software-engineering/requirements/patton_2014.md +++ /dev/null @@ -1,46 +0,0 @@ -# User Story Mapping (Patton, 2014) - -## Citation - -Patton, J. (2014). *User Story Mapping: Discover the Whole Story, Build the Right Product*. O'Reilly Media. - -## Source Type - -Book - -## Method - -Industry practice synthesis - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Story mapping is a collaborative discovery workshop that produces a two-dimensional map of user activities (backbone) and user tasks (stories). The map reveals the whole product at a glance, enabling prioritization and release slicing that flat backlogs cannot achieve. - -## Core Findings - -1. **Backbone First**: Map user activities (high-level workflows) as the top row before adding any stories. Activities correspond to bounded contexts or major product areas. -2. **Stories Are Discovered, Not Written**: Stories emerge from mapping user tasks beneath activities. The mapping workshop IS the discovery process. It replaces separate specification interviews for initial story creation. -3. **Release Slicing**: Horizontal cuts across the map define releases. The minimum viable product is the thinnest horizontal slice that covers all activities. -4. **Coarse Then Detailed**: Stories start as brief titles (one-line descriptions). Full "As a / I want / So that" format comes later during backlog refinement, not during mapping. -5. **Whole Product View**: A flat backlog hides dependencies and gaps. The two-dimensional map makes missing functionality, duplicate stories, and ordering dependencies visible. -6. **Collaborative Workshop**: Story mapping is a facilitated workshop with stakeholders, not a solo documentation exercise. The conversation IS the specification. - -## Mechanism - -The two-dimensional structure (activities × tasks) activates spatial memory and pattern recognition. Participants see gaps and dependencies that flat lists conceal. The act of placing stories physically (or digitally) triggers discussion about what's missing or redundant. Prioritization emerges naturally from ordering stories top-to-bottom within each activity. - -## Relevance - -Story mapping bridges Event Storming (which surfaces bounded contexts and domain events) and BDD (which specifies concrete scenarios). After Event Storming identifies bounded contexts, story mapping decomposes each context into features and stories. The delivery order in the product definition maps to horizontal release slices across the story map. - -## Related Research - -Builds on agile user stories (Cohn, 2004), influenced by design thinking's emphasis on whole-product understanding. Complements Event Storming (Brandolini, 2012): storming produces events and contexts, mapping produces stories and releases. Patton explicitly credits Constantine's usage-centered design as a precursor. diff --git a/docs/research/software-engineering/requirements/wake_2003.md b/docs/research/software-engineering/requirements/wake_2003.md deleted file mode 100644 index a32599bc..00000000 --- a/docs/research/software-engineering/requirements/wake_2003.md +++ /dev/null @@ -1,45 +0,0 @@ -# INVEST in Good Stories (Wake, 2003) - -## Citation - -Wake, B. (2003). *INVEST in Good Stories, and SMART Tasks*. XP123.com. - -## Source Type - -Blog/Article - -## Method - -Theoretical - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Stories that are Independent, Negotiable, Valuable, Estimable, Small, and Testable produce fewer downstream defects and smoother development cycles. - -## Core Findings - -1. **INVEST Acronym**: Independent (no overlap, any order), Negotiable (details co-created), Valuable (to customer), Estimable (sized appropriately), Small (few person-weeks), Testable (clear acceptance criteria) -2. **Vertical Slicing**: Split stories vertically through all layers (network/persistence/logic/presentation) rather than horizontally by layer -3. **Testable Forces Clarity**: "Testable" forces Product Owner to express observable outcomes, directly enabling Given/When/Then format -4. **Size Impact**: Smaller stories get more accurate estimates; above few person-weeks becomes too hard to scope -5. **SMART Tasks Extension**: Specific, Measurable, Achievable, Relevant, Time-boxed tasks complement INVEST stories - -## Mechanism - -"Testable" forces PO to express observable outcomes directly enabling Given/When/Then. "Small" forces decomposition preventing scope creep. "Independent" prevents hidden ordering dependencies. "Valuable" ensures customer-centric vertical slicing through technical layers. - -## Relevance - -Foundational for agile user story writing, product backlog management, acceptance criteria definition. Applied in Scrum, XP, SAFe methodologies. Essential for Product Owners, Business Analysts, development teams writing effective requirements. - -## Related Research - -Created by Bill Wake (XP123.com) in 2003. Consciously developed by clustering story attributes and finding memorable acronym. Widely adopted in agile methodologies. Complements (Cohn, 2004) user story practices and (North, 2006) BDD Given/When/Then format. diff --git a/docs/research/software-engineering/requirements/wynne_2015.md b/docs/research/software-engineering/requirements/wynne_2015.md deleted file mode 100644 index 69a8b209..00000000 --- a/docs/research/software-engineering/requirements/wynne_2015.md +++ /dev/null @@ -1,45 +0,0 @@ -# Example Mapping (Wynne, 2015) - -## Citation - -Wynne, M. (2015). "Introducing Example Mapping." *Cucumber Blog*. https://cucumber.io/blog/bdd/example-mapping-introduction/ - -## Source Type - -Blog/Article - -## Method - -Case Study - -## Verification Status - -Verified - -## Confidence - -High - -## Key Insight - -Inserting a "rules" layer between stories and examples prevents redundant or contradictory acceptance criteria - visual arrangement reveals story complexity and knowledge gaps before development begins. - -## Core Findings - -1. **Four Card Types**: Story (yellow), Rules (blue), Examples (green), Questions (red) using colored index cards in visual mapping -2. **Quality Signals**: Many rules → story needs splitting; many examples per rule → rule too complex; many red cards → story not ready; no red cards → conversation may be insufficient -3. **Time-boxed Process**: Well-understood, well-sized story should map in ~25 minutes with thumb-vote to determine development readiness -4. **Rules Layer Value**: Groups related examples under business rules they illustrate, preventing duplicated logic and making business constraints explicit -5. **"Friends Episode" Naming**: Rough examples using informal names ("The one where customer forgot receipt") instead of formal Gherkin during mapping - -## Mechanism - -Collaborative session involves stakeholders placing colored cards on table/wall. Visual arrangement provides instant feedback on story complexity. Rules layer acts as intermediary between high-level stories and concrete examples, preventing redundancy and revealing natural slicing points. - -## Relevance - -Essential for BDD story refinement, three amigos sessions, backlog grooming. Applied in agile requirements discovery, acceptance criteria definition, story sizing. Foundational technique for preventing oversized stories entering sprints and discovering unknown unknowns systematically. - -## Related Research - -Created by Matt Wynne (Cucumber Project Lead) in 2015. Builds on (North, 2006) BDD practices and three amigos concept. Complements (Wake, 2003) INVEST criteria by providing structured discovery technique. Part of broader BDD ecosystem alongside Gherkin, specification workshops, deliberate discovery practices. \ No newline at end of file diff --git a/docs/spec/.gitkeep b/docs/spec/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/pyproject.toml b/pyproject.toml index dcc1d4f8..b7f9d6bb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,6 +12,7 @@ maintainers = [ { name = "eol", email = "nullhack@users.noreply.github.com" } ] dependencies = [ + "flowr>=1.2.1", ] [project.urls] @@ -26,13 +27,14 @@ dev = [ "pytest-cov>=6.1.1", "pytest-html>=4.0.0", "pytest-mock>=3.14.0", + "pytest-vcr>=1.0.2", + "vcrpy>=6.0.1", "ruff>=0.11.5", "taskipy>=1.14.1", "hypothesis>=6.148.4", "pyright>=1.1.407", + "mypy>=1.13.0", "ghp-import>=2.1.0", - "flowr>=1.2.0", - "beehave>=1.0.0", "pytest-beehave>=1.0.0", "safety>=3.7.0", ] @@ -40,7 +42,7 @@ dev = [ [tool.flowr] flows_dir = ".flowr/flows" sessions_dir = ".cache/sessions" -default_flow = "define-flow" +default_flow = "pipeline-flow" default_session = "default" [tool.beehave] @@ -70,6 +72,7 @@ select = [ "G", "LOG", "PT", + "PYI", "RUF", "S", "SIM", @@ -77,7 +80,6 @@ select = [ ] preview = true mccabe.max-complexity = 10 -pydocstyle.convention = "google" [tool.ruff.lint.per-file-ignores] "tests/**" = ["S101", "S404", "ANN", "D"] @@ -89,6 +91,7 @@ markers = [ "slow: marks tests as slow (deselect with '-m \"not slow\"')", "deprecated: marks tests for deprecated AC; automatically skipped by pytest-beehave (deselect with '-m \"not deprecated\"')", "bug: marks tests that reproduce a reported defect (deselect with '-m \"not bug\"')", + "pending: contract test defined in discovery but not yet implemented; auto-skipped (the backlog). Remove the marker to activate (red). Query with: -m pending", ] addopts = """ --maxfail=10 \ @@ -134,7 +137,7 @@ pytest \ test-fast = "pytest -m \"not slow\" -q --no-header --tb=no" test-slow = "pytest -m slow" ruff-check = "ruff check ." -conventions = "ruff check . --select A,ANN,ASYNC,B,C4,C9,D,DTZ,E,ERA,F,FURB,G,I,ICN,LOG,N,NPY,PD,PT,PTH,RUF,S,SIM,T20,TD,W" +conventions = "ruff check . --select A,ANN,ASYNC,B,C4,C9,DTZ,E,ERA,F,FURB,G,I,ICN,LOG,N,NPY,PD,PT,PTH,PYI,RUF,S,SIM,T20,TD,W" ruff-format = "ruff format ." ruff-format-check = "ruff format . --check" lint = "task ruff-check && task ruff-format-check" @@ -151,8 +154,9 @@ pytest \ """ doc-publish = "task doc-build && ghp-import -n -p -f docs" static-check = "pyright app tests" +stubtest = "python -m mypy.stubtest app tests" validate-flows = "bash -c 'for f in .flowr/flows/*.yaml; do python -m flowr validate \"$f\"; done'" -release-check = "task conventions && task static-check && task test && task doc-build" +release-check = "task conventions && task static-check && task stubtest && task test && task doc-build" diff --git a/template-config.yaml b/template-config.yaml deleted file mode 100644 index 264e6929..00000000 --- a/template-config.yaml +++ /dev/null @@ -1,113 +0,0 @@ -# Template configuration — single source of truth for project setup. -# Read by the setup-project agent. The "defaults" section reflects the current -# template values. The "substitutions" section maps every literal string in every -# template file to its replacement pattern, using {variable} tokens. -# -# After running @setup-project the defaults section is updated with the values -# the user provided. -# -# Parameter descriptions: -# github_username — GitHub handle used in URLs and git remote -# project_name — kebab-case repository name (e.g. my-awesome-project) -# package_name — snake_case Python package directory (e.g. my_awesome_project) -# project_description — one sentence describing what the project does -# author_name — author's full name -# author_email — author's email address - -defaults: - github_username: nullhack - project_name: temple8 - package_name: app - project_description: "Python template with some awesome tools to quickstart any Python project" - author_name: eol - author_email: nullhack@users.noreply.github.com - -# Substitution map — every file the setup agent must edit. -# Each entry has: -# old: literal string currently in the file -# new: replacement string with {variable} tokens -# count: expected number of replacements (for agent verification) - -substitutions: - pyproject.toml: - - old: 'name = "temple8"' - new: 'name = "{project_name}"' - count: 1 - - old: '"Python template with some awesome tools to quickstart any Python project"' - new: '"{project_description}"' - count: 1 - - old: '{ name = "eol", email = "nullhack@users.noreply.github.com" }' - new: '{{ name = "{author_name}", email = "{author_email}" }}' - count: 2 - - old: "https://github.com/nullhack/temple8" - new: "https://github.com/{github_username}/{project_name}" - count: 2 - - old: 'packages = ["app"]' - new: 'packages = ["{package_name}"]' - count: 1 - - old: "python -m app" - new: "python -m {package_name}" - count: 1 - - old: "--cov=app" - new: "--cov={package_name}" - count: 2 - - old: "pdoc ./app" - new: "pdoc ./{package_name}" - count: 2 - - old: 'version = "8.0.0"' - new: 'version = "0.1.0"' - count: 1 - # Version: set to 0.1.0 in pyproject.toml (pure semver, no date — see [[software-craft/versioning]]) - - README.md: - - old: "nullhack" - new: "{github_username}" - count: many - - old: "temple8" - new: "{project_name}" - count: many - - old: "eol" - new: "{author_name}" - count: 1 - note: "only the author credit line — do not replace occurrences in other contexts" - - .github/workflows/ci.yml: - - old: "import app" - new: "import {package_name}" - count: 2 - - old: 'href="api/app.html"' - new: 'href="api/{package_name}.html"' - count: 1 - - LICENSE: - - old: "Copyright (c) 2026, eol" - new: "Copyright (c) 2026, {author_name}" - count: 1 - - tests/unit/main_test.py: - - old: "from app.__main__ import" - new: "from {package_name}.__main__ import" - count: 1 - - CHANGELOG.md: - note: "Overwrite entire file from .templates/CHANGELOG.md.template, replacing {project_name} and {YYYYMMDD} tokens. No find-replace substitutions — the template replaces all content." - - template-config.yaml: - - old: "github_username: nullhack" - new: "github_username: {github_username}" - count: 1 - - old: "project_name: temple8" - new: "project_name: {project_name}" - count: 1 - - old: "package_name: app" - new: "package_name: {package_name}" - count: 1 - - old: '"Python template with some awesome tools to quickstart any Python project"' - new: '"{project_description}"' - count: 1 - - old: "author_name: eol" - new: "author_name: {author_name}" - count: 1 - - old: "author_email: nullhack@users.noreply.github.com" - new: "author_email: {author_email}" - count: 1 diff --git a/tests/__init__.py b/tests/__init__.py deleted file mode 100644 index f1b390f8..00000000 --- a/tests/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""Tests module.""" diff --git a/tests/conftest.py b/tests/conftest.py deleted file mode 100644 index 8b0dcb0d..00000000 --- a/tests/conftest.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Tests module.""" - -import pytest - - -@pytest.hookimpl(hookwrapper=True, tryfirst=True) -def pytest_terminal_summary(terminalreporter, exitstatus, config): - if not getattr(config.option, "cov_source", None): - yield - return - - cov_report = getattr(config.option, "cov_report", None) or [] - if any(r and r.startswith("term") for r in cov_report): - yield - return - - captured = [] - orig_write = terminalreporter.write - orig_sep = terminalreporter.write_sep - - def _cap(*a, **kw): - captured.append(("w", a, kw)) - - def _sep(*a, **kw): - captured.append(("s", a, kw)) - - terminalreporter.write = _cap - terminalreporter.write_sep = _sep - yield - terminalreporter.write = orig_write - terminalreporter.write_sep = orig_sep - - if exitstatus != 0: - for kind, args, kwargs in captured: - (orig_write if kind == "w" else orig_sep)(*args, **kwargs) diff --git a/tests/features/cli_entrypoint/__init__.py b/tests/features/cli_entrypoint/__init__.py deleted file mode 100644 index 336b04e0..00000000 --- a/tests/features/cli_entrypoint/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""CLI entrypoint feature tests.""" diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py deleted file mode 100644 index e0310a01..00000000 --- a/tests/unit/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""Unit tests.""" diff --git a/tests/unit/main_test.py b/tests/unit/main_test.py deleted file mode 100644 index 5a6f35dd..00000000 --- a/tests/unit/main_test.py +++ /dev/null @@ -1,44 +0,0 @@ -"""Unit tests for app.__main__ — in-process coverage.""" - -import argparse -import importlib.metadata -import sys - -import pytest - -from app.__main__ import build_parser, main - - -def test_build_parser_returns_argument_parser() -> None: - """build_parser returns a configured ArgumentParser instance.""" - parser = build_parser() - assert isinstance(parser, argparse.ArgumentParser) - - -def test_build_parser_description_matches_package_metadata() -> None: - """build_parser sets description from package metadata Summary.""" - parser = build_parser() - expected = importlib.metadata.metadata("temple8")["Summary"] - assert parser.description == expected - - -def test_main_exits_0_with_no_args(monkeypatch: pytest.MonkeyPatch) -> None: - """main() with no argv exits cleanly (code 0).""" - monkeypatch.setattr(sys, "argv", ["app"]) - main() - - -def test_main_exits_0_with_help(monkeypatch: pytest.MonkeyPatch) -> None: - """main() with --help exits with SystemExit(0).""" - monkeypatch.setattr(sys, "argv", ["app", "--help"]) - with pytest.raises(SystemExit) as exc_info: - main() - assert exc_info.value.code == 0 - - -def test_main_exits_0_with_version(monkeypatch: pytest.MonkeyPatch) -> None: - """main() with --version exits with SystemExit(0).""" - monkeypatch.setattr(sys, "argv", ["app", "--version"]) - with pytest.raises(SystemExit) as exc_info: - main() - assert exc_info.value.code == 0 diff --git a/uv.lock b/uv.lock index f3d7d615..1ca6c4f1 100644 --- a/uv.lock +++ b/uv.lock @@ -1,6 +1,10 @@ version = 1 revision = 3 requires-python = ">=3.14" +resolution-markers = [ + "python_full_version >= '3.15'", + "python_full_version < '3.15'", +] [[package]] name = "annotated-doc" @@ -22,27 +26,67 @@ wheels = [ [[package]] name = "anyio" -version = "4.13.0" +version = "4.14.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "idna" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/3b/72/5562aabb8dd7181e8e860622a38bea08d17842b99ecd4c91f84ac95251b0/anyio-4.14.1.tar.gz", hash = "sha256:8d648a3544c1a700e3ff78615cd679e4c5c3f149904287e73687b2596963629e", size = 254831, upload-time = "2026-06-24T20:56:06.017Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b0/7b/90df4a0a816d98d6ea26f559d87836d494a2cf1fcf063be67df50a7bcc30/anyio-4.14.1-py3-none-any.whl", hash = "sha256:4e5533c5b8ff0a24f5d7a176cbe6877129cd183893f66b537f8f227d10527d72", size = 124875, upload-time = "2026-06-24T20:56:04.413Z" }, +] + +[[package]] +name = "ast-serialize" +version = "0.5.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/81/9d/09e27731bd5864a9ce04e3244074e674bb8936bf62b45e0357248717adac/ast_serialize-0.5.0.tar.gz", hash = "sha256:5880091bfe6f4f986f22866375c2e884843e7a0b6343ae41aeea659613d879b6", size = 61157, upload-time = "2026-05-17T17:48:29.429Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c0/9a/13dde51ba9e15f8b97957ab7cb0120d0e381524d651c6bd630b9c359227f/ast_serialize-0.5.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8f5c14f169eb0972c0c21bada5358b23d6047c76583b005234f865b11f1fa00a", size = 1183520, upload-time = "2026-05-17T17:47:30.831Z" }, + { url = "https://files.pythonhosted.org/packages/37/de/5a7f0a9fe68944f536632a5af84676739c7d2582be42deb082634bf3a754/ast_serialize-0.5.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7d1a2de9de5be04652f0ed60738356ef94f66db37924a9499fffe98dc491aa0b", size = 1175779, upload-time = "2026-05-17T17:47:32.551Z" }, + { url = "https://files.pythonhosted.org/packages/9c/81/0bb853e76e4f6e9a1855d569003c59e19ffac45f7079d91505d1bb212f92/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:be5173fb66f9b49026d9d5a2ff0fc7c7009077107c0eb285b2d60fdf1fe10bd1", size = 1233750, upload-time = "2026-05-17T17:47:34.731Z" }, + { url = "https://files.pythonhosted.org/packages/e5/d3/4cf705beeccc08754d0bbda99aefff26110e209b9a07ac8a6b60eec48531/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f8015cd071ac1339924ee2b8098c93e00e155f30a16f40ec9816fcf84f4753f6", size = 1235942, upload-time = "2026-05-17T17:47:36.287Z" }, + { url = "https://files.pythonhosted.org/packages/26/c8/ee097e437ea27dd2b8b227865c875492b585650a5802a22d82b304c8201b/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5499e8797edff2a9186aa313ed382c6b422e798e9332d9953badcee6e69a88f2", size = 1442517, upload-time = "2026-05-17T17:47:38.17Z" }, + { url = "https://files.pythonhosted.org/packages/ff/bd/68063442838f1ba68ec72b5436430bc75b3bb17a1a3c3063f09b0c05ae2b/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6848f2a093fb5548751a9a09bff8fcd229e2bbeb0e3331f391b6ae6d26cd9903", size = 1254081, upload-time = "2026-05-17T17:47:39.826Z" }, + { url = "https://files.pythonhosted.org/packages/50/e2/1e520793bc6a4e4524a6ab022391e827825eaa0c3811828bfdc6852eca26/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:832d4c998e0b091fd60a6d6bceee535483c4d490de9ba85003af835225719261", size = 1259910, upload-time = "2026-05-17T17:47:41.369Z" }, + { url = "https://files.pythonhosted.org/packages/4e/e1/49b60f467979979cfe6913b43948ff25bca971ad0591d181812f163a988e/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:16db7c62ec0b8efe1d7afd283a388d8f74f2605d56032e5a37747d2de8dba027", size = 1250678, upload-time = "2026-05-17T17:47:43.702Z" }, + { url = "https://files.pythonhosted.org/packages/74/ba/66ab9555de6275677566f6574e5ef6c29cb185ea866f643bc06f8280a8ee/ast_serialize-0.5.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:baf5eb061eb5bccade4128ad42da33787d72f6013809cd1b590376ece8b3c937", size = 1301603, upload-time = "2026-05-17T17:47:46.256Z" }, + { url = "https://files.pythonhosted.org/packages/66/42/6aca9b9abc710014b2be9059689e5dd1679339e78f567ffb4d255a9e2050/ast_serialize-0.5.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:104e4a35bd7c124173c41760ef9aaea17ddb3f86c65cb643671d59afbe3ee94c", size = 1410332, upload-time = "2026-05-17T17:47:47.899Z" }, + { url = "https://files.pythonhosted.org/packages/47/68/2f76594432a22581ecf878b5e75a9b8601c24b2241cf0bbeb1e21fcf370c/ast_serialize-0.5.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:36be371028fc1675acb38a331bde160dbab7ff907fdf00b67eb6911aa106951b", size = 1509979, upload-time = "2026-05-17T17:47:50.942Z" }, + { url = "https://files.pythonhosted.org/packages/40/ac/a93c9b58292653f6c595752f677a08e608f903b710594909e9231a389b3b/ast_serialize-0.5.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:061ee58bdb52341c8201a6df41182a977736bae3b7ded87ca7176ca25a8a47ab", size = 1505002, upload-time = "2026-05-17T17:47:54.093Z" }, + { url = "https://files.pythonhosted.org/packages/14/2e/b278f68c497ee2f1d1576cbbef8db5281cd4a5f2db040537592ac9c8862e/ast_serialize-0.5.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:b15219e9cdc9f53f6f4cb51c009203507228226148c05c5e8fe451c28b435eb3", size = 1456231, upload-time = "2026-05-17T17:47:56.311Z" }, + { url = "https://files.pythonhosted.org/packages/0b/43/419be1c566a4c504cd8fd60ce2f84e790f295495c0f327cfaeadf3d51012/ast_serialize-0.5.0-cp314-cp314t-win32.whl", hash = "sha256:842d1c004bb466c7df036f95fabef789570541922b10976b12f5592a69cf0b38", size = 1058668, upload-time = "2026-05-17T17:47:58.305Z" }, + { url = "https://files.pythonhosted.org/packages/03/6f/c9d4d549295ed05111aeb8853232d1afd9d0a179fddb01eeffbb3a4a6842/ast_serialize-0.5.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b0c06d760909b095cc466356dfccd05a1c7233a6ca191c020dca2c6a6f16c24c", size = 1101075, upload-time = "2026-05-17T17:48:00.35Z" }, + { url = "https://files.pythonhosted.org/packages/d0/8e/d00c5ab30c58222e07d62956fca86c59d91b9ad32997e633c38b526623a3/ast_serialize-0.5.0-cp314-cp314t-win_arm64.whl", hash = "sha256:787baedb0262cc49e8ce37cc15c00ae818e46a165a3b36f5e21ed174998104cb", size = 1075347, upload-time = "2026-05-17T17:48:01.753Z" }, + { url = "https://files.pythonhosted.org/packages/e0/9e/dc2530acb3a60dc6e46d65abf27d1d9f86721694757906a148d90a6860de/ast_serialize-0.5.0-cp39-abi3-macosx_10_12_x86_64.whl", hash = "sha256:0668aa9459cfa8c9c49ddd2163ebcf43088ba045ef7492af6fe22e0098303101", size = 1191380, upload-time = "2026-05-17T17:48:03.738Z" }, + { url = "https://files.pythonhosted.org/packages/26/0a/bd3d18a582f273d6c843d16bb9e22e9e16365ff7991e92f18f798e9f1224/ast_serialize-0.5.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:bf683d6363edf2b39eed6b6d4fe22d34b6203867a67e27134d9e2a2680c4bc4a", size = 1183879, upload-time = "2026-05-17T17:48:05.463Z" }, + { url = "https://files.pythonhosted.org/packages/40/ae/1f919100f8620887af58fcc381c61a1f218cdf89c6e155f87b213e61010a/ast_serialize-0.5.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9cc22cf0c9be65e71cf88fda130af60d61eb4a79370ad4cfe7900d48a4aa2211", size = 1244529, upload-time = "2026-05-17T17:48:07.008Z" }, + { url = "https://files.pythonhosted.org/packages/c6/ca/6376559dcce707cdbc1d0d9a13c8d3baaaa501e949ce0ebdc4230cd881aa/ast_serialize-0.5.0-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f66173891548c9f2726bf27957b41cabce12fa679dc6da505ddbde4d4b3b31cf", size = 1240560, upload-time = "2026-05-17T17:48:08.46Z" }, + { url = "https://files.pythonhosted.org/packages/35/b2/a620e206b5aeb7efbf2710336df57d457cffbb3991076bbcc1147ef9abd4/ast_serialize-0.5.0-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e42d729ef2be96a14efbad355093284739e3670ece3e534f82cc8832790911d9", size = 1451172, upload-time = "2026-05-17T17:48:09.922Z" }, + { url = "https://files.pythonhosted.org/packages/fa/e0/4ad5c04c24a40481b2935ce9a0ccdb6023dc8b667167d06ae530cc3512f2/ast_serialize-0.5.0-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b725026bafa801dbd7310eb13a75f0a2e370e7e51b2cb225f9d21fcfadf919ee", size = 1265072, upload-time = "2026-05-17T17:48:11.469Z" }, + { url = "https://files.pythonhosted.org/packages/b2/71/4d1d479aa56d0101c40e17720c3d6ac2af7269ea0487a80b18e7bfd1a5b7/ast_serialize-0.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b54f60c1d78767a53b67eaa663f0dfac3afe606aa07f1301572f588b73d64809", size = 1270488, upload-time = "2026-05-17T17:48:13.575Z" }, + { url = "https://files.pythonhosted.org/packages/6d/4f/0de1bbe06f6edef9fde4ed12ca8e7b3ec7e6e2bd4e672c5af487f7957665/ast_serialize-0.5.0-cp39-abi3-manylinux_2_31_riscv64.whl", hash = "sha256:27d51654fc240a1e87e742d353d98eb45b75f62f129086b3596ab53df2ac2a43", size = 1260702, upload-time = "2026-05-17T17:48:15.141Z" }, + { url = "https://files.pythonhosted.org/packages/75/61/e00872439cfdddcc3c1b6cdaa6e5d904ba8e26a18807c67c4e14409d0ca8/ast_serialize-0.5.0-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c36237c46dd1674542f2109740ea5ea485a169bf1431939ada0434e17934", size = 1311182, upload-time = "2026-05-17T17:48:16.779Z" }, + { url = "https://files.pythonhosted.org/packages/76/8e/699a5b955f7926956c95e9e1d74132acad73c2fe7a426f94da89123c20aa/ast_serialize-0.5.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:1943db345233cc7194a470f13afa9c59772c0b123dea0c9414c4d4ca54369759", size = 1421410, upload-time = "2026-05-17T17:48:18.527Z" }, + { url = "https://files.pythonhosted.org/packages/a9/ae/d5b7626874478997adc7a29ab28accf21e596fb590c944290401dfd0b29e/ast_serialize-0.5.0-cp39-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:df1c00022cbbcb064bfaa505aa9c9295362443ce5dacb459d1331d3da353f887", size = 1516587, upload-time = "2026-05-17T17:48:20.133Z" }, + { url = "https://files.pythonhosted.org/packages/0c/ce/b59e02a82d9c4244d64cde502e0b00e83e38816abe19155ceb5437402c7f/ast_serialize-0.5.0-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:cae65289fc456fde04af979a2be09302ef5d8ab92ef23e596d6746dc267ada27", size = 1515171, upload-time = "2026-05-17T17:48:21.921Z" }, + { url = "https://files.pythonhosted.org/packages/8b/38/d8d90042747d05aa08d4efcf1c99035a5f670a6bf4c214d31644392afbca/ast_serialize-0.5.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:239a4c354e8d676e9d94631d1d4a64edc6b266f86ff3a5a80aedd344f342c01d", size = 1464668, upload-time = "2026-05-17T17:48:23.544Z" }, + { url = "https://files.pythonhosted.org/packages/dd/51/5b840c4df7334104cecffa28f23904fe81ca89ca223d2450e288de39fd3c/ast_serialize-0.5.0-cp39-abi3-win32.whl", hash = "sha256:143a4ef63285a075871908fda3672dc21864b83a8ec3ee12304aa3e4c5387b9a", size = 1068311, upload-time = "2026-05-17T17:48:25.027Z" }, + { url = "https://files.pythonhosted.org/packages/41/11/ca5672c7d491825bc4cd6702dea106a6b60d928707712ec257c7833ae476/ast_serialize-0.5.0-cp39-abi3-win_amd64.whl", hash = "sha256:cf25572c526add400f26a4750dc6ce0c3bb93fc1f75e7ae0cad4ce4f2cd5c590", size = 1108931, upload-time = "2026-05-17T17:48:26.591Z" }, + { url = "https://files.pythonhosted.org/packages/45/19/cc8bd127d28a43da249aa955cfd164cf8fd534e79e42cea96c4854d72fd0/ast_serialize-0.5.0-cp39-abi3-win_arm64.whl", hash = "sha256:92a31c9c20d25a076edaeec76b128a3535d74a24f340b9a8a7e96c9b86dc9642", size = 1081181, upload-time = "2026-05-17T17:48:28.122Z" }, ] [[package]] name = "authlib" -version = "1.7.1" +version = "1.7.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "cryptography" }, { name = "joserfc" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/3c/f2/e05664d5275ce811fd4e9df0a2b3f0086ee19a8a80358d95499fa82fd50c/authlib-1.7.1.tar.gz", hash = "sha256:8c09b0f9d080c823e594b52316af70f79a1fa4eed64d0363a076233c04ef063a", size = 175884, upload-time = "2026-05-04T08:11:25.033Z" } +sdist = { url = "https://files.pythonhosted.org/packages/36/98/7d93f30d029643c0275dbc0bd6d5a6f670661ee6c9a94d93af7ab4887600/authlib-1.7.2.tar.gz", hash = "sha256:2cea25fefcd4e7173bdf1372c0afc265c8034b23a8cd5dcb6a9164b826c64231", size = 176511, upload-time = "2026-05-06T08:10:23.116Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/e0/82/730650ee5e5b598b7bfdc291b784bc2f6fe02a5671695485403365101088/authlib-1.7.1-py2.py3-none-any.whl", hash = "sha256:8470f4aa6b5590ac41bd81d6e6ee12448ce36a0da0af19bbed69fb53fb4e8ad9", size = 258826, upload-time = "2026-05-04T08:11:23.208Z" }, + { url = "https://files.pythonhosted.org/packages/fb/95/adcb68e20c34162e9135f370d6e31737719c2b6f94bc953fe7ed1f10fe21/authlib-1.7.2-py2.py3-none-any.whl", hash = "sha256:3e1faedc9d87e7d56a164eca3ccb6ace0d61b94abe83e92242f8dc8bba9b4a9f", size = 259548, upload-time = "2026-05-06T08:10:21.436Z" }, ] [[package]] @@ -59,11 +103,11 @@ wheels = [ [[package]] name = "certifi" -version = "2026.2.25" +version = "2026.6.17" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c9/c7/424b75da314c1045981bd9777432fad05a9e0c69daa4ed7e308bbaffe405/certifi-2026.6.17.tar.gz", hash = "sha256:024c88eeec92ca068db80f02b8b07c9cef7b9fe261d1d535abfd5abd6f6af432", size = 134594, upload-time = "2026-06-17T10:31:07.894Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" }, + { url = "https://files.pythonhosted.org/packages/ef/2f/c5464532e965badff2f4c4c1a3a83f5697f0d7c407ed0cda44aaa99bb451/certifi-2026.6.17-py3-none-any.whl", hash = "sha256:2227dcbaafe0d2f59279d1762ddddc37783ed4354594f194ffc31d20f41fc3db", size = 133289, upload-time = "2026-06-17T10:31:06.348Z" }, ] [[package]] @@ -99,57 +143,16 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" }, ] -[[package]] -name = "charset-normalizer" -version = "3.4.7" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz", hash = "sha256:ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5", size = 144271, upload-time = "2026-04-02T09:28:39.342Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/97/c8/c67cb8c70e19ef1960b97b22ed2a1567711de46c4ddf19799923adc836c2/charset_normalizer-3.4.7-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:c36c333c39be2dbca264d7803333c896ab8fa7d4d6f0ab7edb7dfd7aea6e98c0", size = 309234, upload-time = "2026-04-02T09:27:07.194Z" }, - { url = "https://files.pythonhosted.org/packages/99/85/c091fdee33f20de70d6c8b522743b6f831a2f1cd3ff86de4c6a827c48a76/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2aed2e5e41f24ea8ef1590b8e848a79b56f3a5564a65ceec43c9d692dc7d8a", size = 208042, upload-time = "2026-04-02T09:27:08.749Z" }, - { url = "https://files.pythonhosted.org/packages/87/1c/ab2ce611b984d2fd5d86a5a8a19c1ae26acac6bad967da4967562c75114d/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:54523e136b8948060c0fa0bc7b1b50c32c186f2fceee897a495406bb6e311d2b", size = 228706, upload-time = "2026-04-02T09:27:09.951Z" }, - { url = "https://files.pythonhosted.org/packages/a8/29/2b1d2cb00bf085f59d29eb773ce58ec2d325430f8c216804a0a5cd83cbca/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:715479b9a2802ecac752a3b0efa2b0b60285cf962ee38414211abdfccc233b41", size = 224727, upload-time = "2026-04-02T09:27:11.175Z" }, - { url = "https://files.pythonhosted.org/packages/47/5c/032c2d5a07fe4d4855fea851209cca2b6f03ebeb6d4e3afdb3358386a684/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bd6c2a1c7573c64738d716488d2cdd3c00e340e4835707d8fdb8dc1a66ef164e", size = 215882, upload-time = "2026-04-02T09:27:12.446Z" }, - { url = "https://files.pythonhosted.org/packages/2c/c2/356065d5a8b78ed04499cae5f339f091946a6a74f91e03476c33f0ab7100/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_armv7l.whl", hash = "sha256:c45e9440fb78f8ddabcf714b68f936737a121355bf59f3907f4e17721b9d1aae", size = 200860, upload-time = "2026-04-02T09:27:13.721Z" }, - { url = "https://files.pythonhosted.org/packages/0c/cd/a32a84217ced5039f53b29f460962abb2d4420def55afabe45b1c3c7483d/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3534e7dcbdcf757da6b85a0bbf5b6868786d5982dd959b065e65481644817a18", size = 211564, upload-time = "2026-04-02T09:27:15.272Z" }, - { url = "https://files.pythonhosted.org/packages/44/86/58e6f13ce26cc3b8f4a36b94a0f22ae2f00a72534520f4ae6857c4b81f89/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e8ac484bf18ce6975760921bb6148041faa8fef0547200386ea0b52b5d27bf7b", size = 211276, upload-time = "2026-04-02T09:27:16.834Z" }, - { url = "https://files.pythonhosted.org/packages/8f/fe/d17c32dc72e17e155e06883efa84514ca375f8a528ba2546bee73fc4df81/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:a5fe03b42827c13cdccd08e6c0247b6a6d4b5e3cdc53fd1749f5896adcdc2356", size = 201238, upload-time = "2026-04-02T09:27:18.229Z" }, - { url = "https://files.pythonhosted.org/packages/6a/29/f33daa50b06525a237451cdb6c69da366c381a3dadcd833fa5676bc468b3/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:2d6eb928e13016cea4f1f21d1e10c1cebd5a421bc57ddf5b1142ae3f86824fab", size = 230189, upload-time = "2026-04-02T09:27:19.445Z" }, - { url = "https://files.pythonhosted.org/packages/b6/6e/52c84015394a6a0bdcd435210a7e944c5f94ea1055f5cc5d56c5fe368e7b/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:e74327fb75de8986940def6e8dee4f127cc9752bee7355bb323cc5b2659b6d46", size = 211352, upload-time = "2026-04-02T09:27:20.79Z" }, - { url = "https://files.pythonhosted.org/packages/8c/d7/4353be581b373033fb9198bf1da3cf8f09c1082561e8e922aa7b39bf9fe8/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:d6038d37043bced98a66e68d3aa2b6a35505dc01328cd65217cefe82f25def44", size = 227024, upload-time = "2026-04-02T09:27:22.063Z" }, - { url = "https://files.pythonhosted.org/packages/30/45/99d18aa925bd1740098ccd3060e238e21115fffbfdcb8f3ece837d0ace6c/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:7579e913a5339fb8fa133f6bbcfd8e6749696206cf05acdbdca71a1b436d8e72", size = 217869, upload-time = "2026-04-02T09:27:23.486Z" }, - { url = "https://files.pythonhosted.org/packages/5c/05/5ee478aa53f4bb7996482153d4bfe1b89e0f087f0ab6b294fcf92d595873/charset_normalizer-3.4.7-cp314-cp314-win32.whl", hash = "sha256:5b77459df20e08151cd6f8b9ef8ef1f961ef73d85c21a555c7eed5b79410ec10", size = 148541, upload-time = "2026-04-02T09:27:25.146Z" }, - { url = "https://files.pythonhosted.org/packages/48/77/72dcb0921b2ce86420b2d79d454c7022bf5be40202a2a07906b9f2a35c97/charset_normalizer-3.4.7-cp314-cp314-win_amd64.whl", hash = "sha256:92a0a01ead5e668468e952e4238cccd7c537364eb7d851ab144ab6627dbbe12f", size = 159634, upload-time = "2026-04-02T09:27:26.642Z" }, - { url = "https://files.pythonhosted.org/packages/c6/a3/c2369911cd72f02386e4e340770f6e158c7980267da16af8f668217abaa0/charset_normalizer-3.4.7-cp314-cp314-win_arm64.whl", hash = "sha256:67f6279d125ca0046a7fd386d01b311c6363844deac3e5b069b514ba3e63c246", size = 148384, upload-time = "2026-04-02T09:27:28.271Z" }, - { url = "https://files.pythonhosted.org/packages/94/09/7e8a7f73d24dba1f0035fbbf014d2c36828fc1bf9c88f84093e57d315935/charset_normalizer-3.4.7-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:effc3f449787117233702311a1b7d8f59cba9ced946ba727bdc329ec69028e24", size = 330133, upload-time = "2026-04-02T09:27:29.474Z" }, - { url = "https://files.pythonhosted.org/packages/8d/da/96975ddb11f8e977f706f45cddd8540fd8242f71ecdb5d18a80723dcf62c/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fbccdc05410c9ee21bbf16a35f4c1d16123dcdeb8a1d38f33654fa21d0234f79", size = 216257, upload-time = "2026-04-02T09:27:30.793Z" }, - { url = "https://files.pythonhosted.org/packages/e5/e8/1d63bf8ef2d388e95c64b2098f45f84758f6d102a087552da1485912637b/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:733784b6d6def852c814bce5f318d25da2ee65dd4839a0718641c696e09a2960", size = 234851, upload-time = "2026-04-02T09:27:32.44Z" }, - { url = "https://files.pythonhosted.org/packages/9b/40/e5ff04233e70da2681fa43969ad6f66ca5611d7e669be0246c4c7aaf6dc8/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a89c23ef8d2c6b27fd200a42aa4ac72786e7c60d40efdc76e6011260b6e949c4", size = 233393, upload-time = "2026-04-02T09:27:34.03Z" }, - { url = "https://files.pythonhosted.org/packages/be/c1/06c6c49d5a5450f76899992f1ee40b41d076aee9279b49cf9974d2f313d5/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6c114670c45346afedc0d947faf3c7f701051d2518b943679c8ff88befe14f8e", size = 223251, upload-time = "2026-04-02T09:27:35.369Z" }, - { url = "https://files.pythonhosted.org/packages/2b/9f/f2ff16fb050946169e3e1f82134d107e5d4ae72647ec8a1b1446c148480f/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:a180c5e59792af262bf263b21a3c49353f25945d8d9f70628e73de370d55e1e1", size = 206609, upload-time = "2026-04-02T09:27:36.661Z" }, - { url = "https://files.pythonhosted.org/packages/69/d5/a527c0cd8d64d2eab7459784fb4169a0ac76e5a6fc5237337982fd61347e/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3c9a494bc5ec77d43cea229c4f6db1e4d8fe7e1bbffa8b6f0f0032430ff8ab44", size = 220014, upload-time = "2026-04-02T09:27:38.019Z" }, - { url = "https://files.pythonhosted.org/packages/7e/80/8a7b8104a3e203074dc9aa2c613d4b726c0e136bad1cc734594b02867972/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8d828b6667a32a728a1ad1d93957cdf37489c57b97ae6c4de2860fa749b8fc1e", size = 218979, upload-time = "2026-04-02T09:27:39.37Z" }, - { url = "https://files.pythonhosted.org/packages/02/9a/b759b503d507f375b2b5c153e4d2ee0a75aa215b7f2489cf314f4541f2c0/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:cf1493cd8607bec4d8a7b9b004e699fcf8f9103a9284cc94962cb73d20f9d4a3", size = 209238, upload-time = "2026-04-02T09:27:40.722Z" }, - { url = "https://files.pythonhosted.org/packages/c2/4e/0f3f5d47b86bdb79256e7290b26ac847a2832d9a4033f7eb2cd4bcf4bb5b/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0c96c3b819b5c3e9e165495db84d41914d6894d55181d2d108cc1a69bfc9cce0", size = 236110, upload-time = "2026-04-02T09:27:42.33Z" }, - { url = "https://files.pythonhosted.org/packages/96/23/bce28734eb3ed2c91dcf93abeb8a5cf393a7b2749725030bb630e554fdd8/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:752a45dc4a6934060b3b0dab47e04edc3326575f82be64bc4fc293914566503e", size = 219824, upload-time = "2026-04-02T09:27:43.924Z" }, - { url = "https://files.pythonhosted.org/packages/2c/6f/6e897c6984cc4d41af319b077f2f600fc8214eb2fe2d6bcb79141b882400/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:8778f0c7a52e56f75d12dae53ae320fae900a8b9b4164b981b9c5ce059cd1fcb", size = 233103, upload-time = "2026-04-02T09:27:45.348Z" }, - { url = "https://files.pythonhosted.org/packages/76/22/ef7bd0fe480a0ae9b656189ec00744b60933f68b4f42a7bb06589f6f576a/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ce3412fbe1e31eb81ea42f4169ed94861c56e643189e1e75f0041f3fe7020abe", size = 225194, upload-time = "2026-04-02T09:27:46.706Z" }, - { url = "https://files.pythonhosted.org/packages/c5/a7/0e0ab3e0b5bc1219bd80a6a0d4d72ca74d9250cb2382b7c699c147e06017/charset_normalizer-3.4.7-cp314-cp314t-win32.whl", hash = "sha256:c03a41a8784091e67a39648f70c5f97b5b6a37f216896d44d2cdcb82615339a0", size = 159827, upload-time = "2026-04-02T09:27:48.053Z" }, - { url = "https://files.pythonhosted.org/packages/7a/1d/29d32e0fb40864b1f878c7f5a0b343ae676c6e2b271a2d55cc3a152391da/charset_normalizer-3.4.7-cp314-cp314t-win_amd64.whl", hash = "sha256:03853ed82eeebbce3c2abfdbc98c96dc205f32a79627688ac9a27370ea61a49c", size = 174168, upload-time = "2026-04-02T09:27:49.795Z" }, - { url = "https://files.pythonhosted.org/packages/de/32/d92444ad05c7a6e41fb2036749777c163baf7a0301a040cb672d6b2b1ae9/charset_normalizer-3.4.7-cp314-cp314t-win_arm64.whl", hash = "sha256:c35abb8bfff0185efac5878da64c45dafd2b37fb0383add1be155a763c1f083d", size = 153018, upload-time = "2026-04-02T09:27:51.116Z" }, - { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" }, -] - [[package]] name = "click" -version = "8.3.2" +version = "8.4.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/57/75/31212c6bf2503fdf920d87fee5d7a86a2e3bcf444984126f13d8e4016804/click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5", size = 302856, upload-time = "2026-04-03T19:14:45.118Z" } +sdist = { url = "https://files.pythonhosted.org/packages/76/d4/81420972a676e8ffea40450d8c8c92943e7218a78fe9b64359836cc9876b/click-8.4.2.tar.gz", hash = "sha256:9a6cea6e60b17ebe0a44c5cc636d94f09bd66142c1cd7d8b4cd731c4917a15f6", size = 338000, upload-time = "2026-06-24T17:45:15.148Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/e4/20/71885d8b97d4f3dde17b1fdb92dbd4908b00541c5a3379787137285f602e/click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d", size = 108379, upload-time = "2026-04-03T19:14:43.505Z" }, + { url = "https://files.pythonhosted.org/packages/fb/e2/79c688af8b210d232694e31e59da9f6ec747bae31c3f5946e4e9b98860d5/click-8.4.2-py3-none-any.whl", hash = "sha256:e6f9f66136c816745b9d65817da91d61d957fb16e02e4dcd0552553c5a197b76", size = 119243, upload-time = "2026-06-24T17:45:13.73Z" }, ] [[package]] @@ -163,94 +166,91 @@ wheels = [ [[package]] name = "coverage" -version = "7.13.5" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/9d/e0/70553e3000e345daff267cec284ce4cbf3fc141b6da229ac52775b5428f1/coverage-7.13.5.tar.gz", hash = "sha256:c81f6515c4c40141f83f502b07bbfa5c240ba25bbe73da7b33f1e5b6120ff179", size = 915967, upload-time = "2026-03-17T10:33:18.341Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/8e/77/39703f0d1d4b478bfd30191d3c14f53caf596fac00efb3f8f6ee23646439/coverage-7.13.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fbabfaceaeb587e16f7008f7795cd80d20ec548dc7f94fbb0d4ec2e038ce563f", size = 219621, upload-time = "2026-03-17T10:32:08.589Z" }, - { url = "https://files.pythonhosted.org/packages/e2/3e/51dff36d99ae14639a133d9b164d63e628532e2974d8b1edb99dd1ebc733/coverage-7.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9bb2a28101a443669a423b665939381084412b81c3f8c0fcfbac57f4e30b5b8e", size = 219953, upload-time = "2026-03-17T10:32:10.507Z" }, - { url = "https://files.pythonhosted.org/packages/6a/6c/1f1917b01eb647c2f2adc9962bd66c79eb978951cab61bdc1acab3290c07/coverage-7.13.5-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bd3a2fbc1c6cccb3c5106140d87cc6a8715110373ef42b63cf5aea29df8c217a", size = 250992, upload-time = "2026-03-17T10:32:12.41Z" }, - { url = "https://files.pythonhosted.org/packages/22/e5/06b1f88f42a5a99df42ce61208bdec3bddb3d261412874280a19796fc09c/coverage-7.13.5-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6c36ddb64ed9d7e496028d1d00dfec3e428e0aabf4006583bb1839958d280510", size = 253503, upload-time = "2026-03-17T10:32:14.449Z" }, - { url = "https://files.pythonhosted.org/packages/80/28/2a148a51e5907e504fa7b85490277734e6771d8844ebcc48764a15e28155/coverage-7.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:380e8e9084d8eb38db3a9176a1a4f3c0082c3806fa0dc882d1d87abc3c789247", size = 254852, upload-time = "2026-03-17T10:32:16.56Z" }, - { url = "https://files.pythonhosted.org/packages/61/77/50e8d3d85cc0b7ebe09f30f151d670e302c7ff4a1bf6243f71dd8b0981fa/coverage-7.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e808af52a0513762df4d945ea164a24b37f2f518cbe97e03deaa0ee66139b4d6", size = 257161, upload-time = "2026-03-17T10:32:19.004Z" }, - { url = "https://files.pythonhosted.org/packages/3b/c4/b5fd1d4b7bf8d0e75d997afd3925c59ba629fc8616f1b3aae7605132e256/coverage-7.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e301d30dd7e95ae068671d746ba8c34e945a82682e62918e41b2679acd2051a0", size = 251021, upload-time = "2026-03-17T10:32:21.344Z" }, - { url = "https://files.pythonhosted.org/packages/f8/66/6ea21f910e92d69ef0b1c3346ea5922a51bad4446c9126db2ae96ee24c4c/coverage-7.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:800bc829053c80d240a687ceeb927a94fd108bbdc68dfbe505d0d75ab578a882", size = 252858, upload-time = "2026-03-17T10:32:23.506Z" }, - { url = "https://files.pythonhosted.org/packages/9e/ea/879c83cb5d61aa2a35fb80e72715e92672daef8191b84911a643f533840c/coverage-7.13.5-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0b67af5492adb31940ee418a5a655c28e48165da5afab8c7fa6fd72a142f8740", size = 250823, upload-time = "2026-03-17T10:32:25.516Z" }, - { url = "https://files.pythonhosted.org/packages/8a/fb/616d95d3adb88b9803b275580bdeee8bd1b69a886d057652521f83d7322f/coverage-7.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c9136ff29c3a91e25b1d1552b5308e53a1e0653a23e53b6366d7c2dcbbaf8a16", size = 255099, upload-time = "2026-03-17T10:32:27.944Z" }, - { url = "https://files.pythonhosted.org/packages/1c/93/25e6917c90ec1c9a56b0b26f6cad6408e5f13bb6b35d484a0d75c9cf000d/coverage-7.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:cff784eef7f0b8f6cb28804fbddcfa99f89efe4cc35fb5627e3ac58f91ed3ac0", size = 250638, upload-time = "2026-03-17T10:32:29.914Z" }, - { url = "https://files.pythonhosted.org/packages/fc/7b/dc1776b0464145a929deed214aef9fb1493f159b59ff3c7eeeedf91eddd0/coverage-7.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:68a4953be99b17ac3c23b6efbc8a38330d99680c9458927491d18700ef23ded0", size = 252295, upload-time = "2026-03-17T10:32:31.981Z" }, - { url = "https://files.pythonhosted.org/packages/ea/fb/99cbbc56a26e07762a2740713f3c8f9f3f3106e3a3dd8cc4474954bccd34/coverage-7.13.5-cp314-cp314-win32.whl", hash = "sha256:35a31f2b1578185fbe6aa2e74cea1b1d0bbf4c552774247d9160d29b80ed56cc", size = 222360, upload-time = "2026-03-17T10:32:34.233Z" }, - { url = "https://files.pythonhosted.org/packages/8d/b7/4758d4f73fb536347cc5e4ad63662f9d60ba9118cb6785e9616b2ce5d7fa/coverage-7.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:2aa055ae1857258f9e0045be26a6d62bdb47a72448b62d7b55f4820f361a2633", size = 223174, upload-time = "2026-03-17T10:32:36.369Z" }, - { url = "https://files.pythonhosted.org/packages/2c/f2/24d84e1dfe70f8ac9fdf30d338239860d0d1d5da0bda528959d0ebc9da28/coverage-7.13.5-cp314-cp314-win_arm64.whl", hash = "sha256:1b11eef33edeae9d142f9b4358edb76273b3bfd30bc3df9a4f95d0e49caf94e8", size = 221739, upload-time = "2026-03-17T10:32:38.736Z" }, - { url = "https://files.pythonhosted.org/packages/60/5b/4a168591057b3668c2428bff25dd3ebc21b629d666d90bcdfa0217940e84/coverage-7.13.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10a0c37f0b646eaff7cce1874c31d1f1ccb297688d4c747291f4f4c70741cc8b", size = 220351, upload-time = "2026-03-17T10:32:41.196Z" }, - { url = "https://files.pythonhosted.org/packages/f5/21/1fd5c4dbfe4a58b6b99649125635df46decdfd4a784c3cd6d410d303e370/coverage-7.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b5db73ba3c41c7008037fa731ad5459fc3944cb7452fc0aa9f822ad3533c583c", size = 220612, upload-time = "2026-03-17T10:32:43.204Z" }, - { url = "https://files.pythonhosted.org/packages/d6/fe/2a924b3055a5e7e4512655a9d4609781b0d62334fa0140c3e742926834e2/coverage-7.13.5-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:750db93a81e3e5a9831b534be7b1229df848b2e125a604fe6651e48aa070e5f9", size = 261985, upload-time = "2026-03-17T10:32:45.514Z" }, - { url = "https://files.pythonhosted.org/packages/d7/0d/c8928f2bd518c45990fe1a2ab8db42e914ef9b726c975facc4282578c3eb/coverage-7.13.5-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9ddb4f4a5479f2539644be484da179b653273bca1a323947d48ab107b3ed1f29", size = 264107, upload-time = "2026-03-17T10:32:47.971Z" }, - { url = "https://files.pythonhosted.org/packages/ef/ae/4ae35bbd9a0af9d820362751f0766582833c211224b38665c0f8de3d487f/coverage-7.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d8a7a2049c14f413163e2bdabd37e41179b1d1ccb10ffc6ccc4b7a718429c607", size = 266513, upload-time = "2026-03-17T10:32:50.1Z" }, - { url = "https://files.pythonhosted.org/packages/9c/20/d326174c55af36f74eac6ae781612d9492f060ce8244b570bb9d50d9d609/coverage-7.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1c85e0b6c05c592ea6d8768a66a254bfb3874b53774b12d4c89c481eb78cb90", size = 267650, upload-time = "2026-03-17T10:32:52.391Z" }, - { url = "https://files.pythonhosted.org/packages/7a/5e/31484d62cbd0eabd3412e30d74386ece4a0837d4f6c3040a653878bfc019/coverage-7.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:777c4d1eff1b67876139d24288aaf1817f6c03d6bae9c5cc8d27b83bcfe38fe3", size = 261089, upload-time = "2026-03-17T10:32:54.544Z" }, - { url = "https://files.pythonhosted.org/packages/e9/d8/49a72d6de146eebb0b7e48cc0f4bc2c0dd858e3d4790ab2b39a2872b62bd/coverage-7.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6697e29b93707167687543480a40f0db8f356e86d9f67ddf2e37e2dfd91a9dab", size = 263982, upload-time = "2026-03-17T10:32:56.803Z" }, - { url = "https://files.pythonhosted.org/packages/06/3b/0351f1bd566e6e4dd39e978efe7958bde1d32f879e85589de147654f57bb/coverage-7.13.5-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8fdf453a942c3e4d99bd80088141c4c6960bb232c409d9c3558e2dbaa3998562", size = 261579, upload-time = "2026-03-17T10:32:59.466Z" }, - { url = "https://files.pythonhosted.org/packages/5d/ce/796a2a2f4017f554d7810f5c573449b35b1e46788424a548d4d19201b222/coverage-7.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:32ca0c0114c9834a43f045a87dcebd69d108d8ffb666957ea65aa132f50332e2", size = 265316, upload-time = "2026-03-17T10:33:01.847Z" }, - { url = "https://files.pythonhosted.org/packages/3d/16/d5ae91455541d1a78bc90abf495be600588aff8f6db5c8b0dae739fa39c9/coverage-7.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8769751c10f339021e2638cd354e13adeac54004d1941119b2c96fe5276d45ea", size = 260427, upload-time = "2026-03-17T10:33:03.945Z" }, - { url = "https://files.pythonhosted.org/packages/48/11/07f413dba62db21fb3fad5d0de013a50e073cc4e2dc4306e770360f6dfc8/coverage-7.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cec2d83125531bd153175354055cdb7a09987af08a9430bd173c937c6d0fba2a", size = 262745, upload-time = "2026-03-17T10:33:06.285Z" }, - { url = "https://files.pythonhosted.org/packages/91/15/d792371332eb4663115becf4bad47e047d16234b1aff687b1b18c58d60ae/coverage-7.13.5-cp314-cp314t-win32.whl", hash = "sha256:0cd9ed7a8b181775459296e402ca4fb27db1279740a24e93b3b41942ebe4b215", size = 223146, upload-time = "2026-03-17T10:33:08.756Z" }, - { url = "https://files.pythonhosted.org/packages/db/51/37221f59a111dca5e85be7dbf09696323b5b9f13ff65e0641d535ed06ea8/coverage-7.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:301e3b7dfefecaca37c9f1aa6f0049b7d4ab8dd933742b607765d757aca77d43", size = 224254, upload-time = "2026-03-17T10:33:11.174Z" }, - { url = "https://files.pythonhosted.org/packages/54/83/6acacc889de8987441aa7d5adfbdbf33d288dad28704a67e574f1df9bcbb/coverage-7.13.5-cp314-cp314t-win_arm64.whl", hash = "sha256:9dacc2ad679b292709e0f5fc1ac74a6d4d5562e424058962c7bb0c658ad25e45", size = 222276, upload-time = "2026-03-17T10:33:13.466Z" }, - { url = "https://files.pythonhosted.org/packages/9e/ee/a4cf96b8ce1e566ed238f0659ac2d3f007ed1d14b181bcb684e19561a69a/coverage-7.13.5-py3-none-any.whl", hash = "sha256:34b02417cf070e173989b3db962f7ed56d2f644307b2cf9d5a0f258e13084a61", size = 211346, upload-time = "2026-03-17T10:33:15.691Z" }, +version = "7.14.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b4/91/0a7c28934e50d8ac9a7b117712d176f2953c3170bccced5eaacfa3e96175/coverage-7.14.3.tar.gz", hash = "sha256:1a7563a443f3d53fdeb040ec8c9f7466aed7ca3dc5891aa09d3ca3625fa4387f", size = 924398, upload-time = "2026-06-22T23:10:25.584Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/61/56/14e3b97facbfa1304dd19e676e26599ad359f04714bed32f7f1c5a88efdc/coverage-7.14.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:605ab2b566a22bd94834529d66d295c364aba84afd3e5498285c7a524017b1fc", size = 220741, upload-time = "2026-06-22T23:09:21.616Z" }, + { url = "https://files.pythonhosted.org/packages/12/1d/db378b5cca433b90b893f26dab728b280ddd89f272a1fdfed4aeaa05c686/coverage-7.14.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a3c2134809e80fac091bfed18a6991b5a5eb5df5ae32b17ac4f4f99864b73dd7", size = 221068, upload-time = "2026-06-22T23:09:23.452Z" }, + { url = "https://files.pythonhosted.org/packages/47/f0/3f8421b20d9c4fcd39be9a8ca3c3fda8bc204b44efbd09fede153afd3e2f/coverage-7.14.3-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c02efd507227bde9969cab0db8f48890eb3b5dcad6afac57a4792df4133543ce", size = 252117, upload-time = "2026-06-22T23:09:25.458Z" }, + { url = "https://files.pythonhosted.org/packages/27/ca/59ea35fb99743549ec8b37eff141ece4431fea590c89e536ed8032ef45cf/coverage-7.14.3-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:1bb93c2aa61d2a5b38f1526546d95cf4132cb681e541a337bf8dfd092be816e5", size = 254622, upload-time = "2026-06-22T23:09:27.523Z" }, + { url = "https://files.pythonhosted.org/packages/c8/25/ec6de51ae7493b92a1cf74d1b763121c29636759167e2a593ba4db5881e4/coverage-7.14.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f502e948e03e866538048bba081c075caaa62e5bda6ea5b7432e45f587eb462a", size = 255968, upload-time = "2026-06-22T23:09:29.43Z" }, + { url = "https://files.pythonhosted.org/packages/5d/05/c8bfc77823f42b4664fb25842f13b567022f6f84a4c83c8ecbb16734b7cb/coverage-7.14.3-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9973ef2463f8e6cfb61a6324126bb3e17d67a85f22f58d856e583ea2e3ca6501", size = 258284, upload-time = "2026-06-22T23:09:31.397Z" }, + { url = "https://files.pythonhosted.org/packages/f6/15/1d1b242027124a32b26ef01f82018b8c4ef34ef174aa6aeba7b1eeef48e8/coverage-7.14.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9be4e7d4c5ca0427889f8f9d614bd630c2be741b1de7699bca3b2b6c0e41003e", size = 252143, upload-time = "2026-06-22T23:09:33.256Z" }, + { url = "https://files.pythonhosted.org/packages/74/b6/d2a9842fd2a5d7d27f1ac851c043a734a494ad75402c5331db3da79ed691/coverage-7.14.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a574912f3bde4b0619f6e97d01aa590b70998859244793769eb3a6df78ee56d3", size = 253976, upload-time = "2026-06-22T23:09:35.351Z" }, + { url = "https://files.pythonhosted.org/packages/fd/30/e1600ddf7e226db5558bb5323d2186fff00f505c4b764643ec89ce5d8175/coverage-7.14.3-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:e343fb086c9cd780b38622fea7c369acd64c1a0724312149b5d769c387a2b1f5", size = 251942, upload-time = "2026-06-22T23:09:37.313Z" }, + { url = "https://files.pythonhosted.org/packages/d9/2c/9159de64f9dd648e324328d588a44cfab1e331eb5259ce1141afe2a92dfb/coverage-7.14.3-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:3c68df8e61f1e09633fefc7538297145623957a048534368c9d212782aa5e845", size = 256220, upload-time = "2026-06-22T23:09:39.165Z" }, + { url = "https://files.pythonhosted.org/packages/91/67/b7f536cc2c124f48e91b22fbb741d2261f4e3d310faf6f76007f47566e5d/coverage-7.14.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:3e5b550a128419373c2f6cec28a244207013ef15f5cbcff6a5ca09d1dfaaf027", size = 251756, upload-time = "2026-06-22T23:09:41.056Z" }, + { url = "https://files.pythonhosted.org/packages/dd/ec/f3718038e2d4860c715a55428377ca7f6c75872caf98cabd982e1d76967d/coverage-7.14.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2bfc4dd0a912329eccc7484a7d0b2a38032b38c40663b1e1ac595f10c457954b", size = 253413, upload-time = "2026-06-22T23:09:43.306Z" }, + { url = "https://files.pythonhosted.org/packages/b8/a5/91f11efeef89b3cc9b30461128db15b0511ef813ab889a7b7ab636b3a497/coverage-7.14.3-cp314-cp314-win32.whl", hash = "sha256:0423d64c013057a06e70f070f073cec4b0cbc7d2b27f3c7007292f2ff1d52965", size = 222946, upload-time = "2026-06-22T23:09:45.261Z" }, + { url = "https://files.pythonhosted.org/packages/58/fd/98ac9f524d9ec378de831c034dbdeb544ca7ef7d2d9c9996daf232a037fd/coverage-7.14.3-cp314-cp314-win_amd64.whl", hash = "sha256:92c22e19ce64ca3f2ad751f16f14df1468b4c231bd6af97185063a9c292a0cb3", size = 223436, upload-time = "2026-06-22T23:09:47.177Z" }, + { url = "https://files.pythonhosted.org/packages/b4/a0/7cd612d650a772a0ae80144443406bf61981c896c3d57c9e6e79fb2cdbd1/coverage-7.14.3-cp314-cp314-win_arm64.whl", hash = "sha256:41de778bd41780586e2b04912079c73089ab5d839624e28db3bdb26de638da92", size = 222861, upload-time = "2026-06-22T23:09:49.384Z" }, + { url = "https://files.pythonhosted.org/packages/55/57/017353fab573779c0d00448e47d102edd36c792f7b6f233a4d89a7a08384/coverage-7.14.3-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:8427f370ca67db4c975d2a26acfc0e5783ca0b52444dbc50278ace0f35445949", size = 221474, upload-time = "2026-06-22T23:09:51.417Z" }, + { url = "https://files.pythonhosted.org/packages/69/92/90cf1f1a5c468a9c1b7ba2716e0e205293ad9b02f5f573a6de4318b15ba1/coverage-7.14.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d8e88f335544a47e22ae2e45b344772925ec65166555c958720d5ed971880891", size = 221738, upload-time = "2026-06-22T23:09:53.487Z" }, + { url = "https://files.pythonhosted.org/packages/a4/c0/4df964fa539f8399fd7679c09c472d73744de334686fd3f01e3a2465ce4e/coverage-7.14.3-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:beaab199b9e5ceaf5a225e16a9d4df136f2a1eae0a5c20de1e277c8a5225f388", size = 263101, upload-time = "2026-06-22T23:09:55.895Z" }, + { url = "https://files.pythonhosted.org/packages/06/76/e5d33b2576ae3bf2be2058cd1cae57774b61e400f2c3c58f3783dc2ffb4a/coverage-7.14.3-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b3ff255799f5a1676c71c1c32ec01fd043aa09d57b3d95764b24992757184784", size = 265225, upload-time = "2026-06-22T23:09:57.904Z" }, + { url = "https://files.pythonhosted.org/packages/61/d2/e52419afe391a39ba27fdefaf0737d8e34bf03faef6ab3b3006545bbd0d0/coverage-7.14.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:878832eaac515b62decfa76965aed558775f86bf1fc8cca76993c0c84ae31aed", size = 267643, upload-time = "2026-06-22T23:09:59.938Z" }, + { url = "https://files.pythonhosted.org/packages/58/7a/f2625d8d5006b6b20fba5afaef00b24a763fe96476ea798a3076cbc1f84e/coverage-7.14.3-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:611e62cb9386096d81b63e0a05330750268617231e7bd598e1fe77482a2c58a5", size = 268762, upload-time = "2026-06-22T23:10:01.943Z" }, + { url = "https://files.pythonhosted.org/packages/7d/bf/908024006bba57127354d74e938954b9c3cd765cc2e0412dc9c37b415cda/coverage-7.14.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:02c41de2a88011b893050fc9830267d927a50a215f7ad5ec17349db7090ccf26", size = 262208, upload-time = "2026-06-22T23:10:03.954Z" }, + { url = "https://files.pythonhosted.org/packages/34/a0/d4f9296441b909817442fdb26bd77a698f08272ec683a7394b00eb2e47a0/coverage-7.14.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:526ce9721116af23b1065089f0b75046fe521e7772ab94b641cd66b7a0421889", size = 265096, upload-time = "2026-06-22T23:10:05.936Z" }, + { url = "https://files.pythonhosted.org/packages/e8/da/4ae4f3f4e477b56a4ce1e5c48a35eff38a94b50130ce5bdc897024741cfc/coverage-7.14.3-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:e4ed44705ca4bead6fc977a8b741f2145608289b33c8a9b42a95d0f15aedbf4d", size = 262699, upload-time = "2026-06-22T23:10:07.973Z" }, + { url = "https://files.pythonhosted.org/packages/d8/7a/6927148073ff32856d78baa77b4ddc07a9be7e90020f9db0661c4ca523a1/coverage-7.14.3-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:2415902f385a23dcc4ccd26e0ba803249a169af6a930c003a4c715eeb9a5444e", size = 266433, upload-time = "2026-06-22T23:10:10.145Z" }, + { url = "https://files.pythonhosted.org/packages/f7/a7/774f658dbe9c4c3f5daa86a87e0459ac3832e4e3cc67affe078547f727b9/coverage-7.14.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:b75ee850fc2d7c831e883220c445b035f2224de2ba6103f1e56dbd237ab913f7", size = 261547, upload-time = "2026-06-22T23:10:12.191Z" }, + { url = "https://files.pythonhosted.org/packages/3d/14/a0c18c0376c43cbf973f43ef6ca20019c950597180e6396232f7b6a27102/coverage-7.14.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:dc9b4e35e7c3920e925ba7f14886fd5fbe481232754624e832ddba66c7535635", size = 263859, upload-time = "2026-06-22T23:10:14.492Z" }, + { url = "https://files.pythonhosted.org/packages/10/ac/43a3d0f460af524b131a6191805bc5d18b806ab4e828fbf82e8c8c3af446/coverage-7.14.3-cp314-cp314t-win32.whl", hash = "sha256:7b27c822a8161afbe48e99f1adfb098d270ae7e0f7d7b0555ce110529bdb69cc", size = 223250, upload-time = "2026-06-22T23:10:16.758Z" }, + { url = "https://files.pythonhosted.org/packages/3f/5f/d5e5c56b0712e96ce8f69fe7dbf229ff938b437bc50862743c8a0d2cea84/coverage-7.14.3-cp314-cp314t-win_amd64.whl", hash = "sha256:39e1dbbb6ff2c338e0196a482558a792a1de3aa64261196f5cdb3da016ad9cda", size = 224082, upload-time = "2026-06-22T23:10:19.23Z" }, + { url = "https://files.pythonhosted.org/packages/62/35/947cbd5be1d3bcbbdc43d6791de8a56c6501903311d42915ae06a82815f0/coverage-7.14.3-cp314-cp314t-win_arm64.whl", hash = "sha256:68520c90babfa2d560eca6d497921ed3a4f469623bd709733124491b2aa8ef3f", size = 223400, upload-time = "2026-06-22T23:10:21.24Z" }, + { url = "https://files.pythonhosted.org/packages/eb/e3/a0aa32bfa3a081951f60a23bc0e7b512891ef0eecda1153cf1d8ba36c6b1/coverage-7.14.3-py3-none-any.whl", hash = "sha256:fb7e18afb6e903c1a92401a2f0501ac277dca527bb9ca6fe1f691a8a0026a0e8", size = 212469, upload-time = "2026-06-22T23:10:23.405Z" }, ] [[package]] name = "cryptography" -version = "46.0.7" +version = "49.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "cffi", marker = "platform_python_implementation != 'PyPy'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/47/93/ac8f3d5ff04d54bc814e961a43ae5b0b146154c89c61b47bb07557679b18/cryptography-46.0.7.tar.gz", hash = "sha256:e4cfd68c5f3e0bfdad0d38e023239b96a2fe84146481852dffbcca442c245aa5", size = 750652, upload-time = "2026-04-08T01:57:54.692Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/0b/5d/4a8f770695d73be252331e60e526291e3df0c9b27556a90a6b47bccca4c2/cryptography-46.0.7-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:ea42cbe97209df307fdc3b155f1b6fa2577c0defa8f1f7d3be7d31d189108ad4", size = 7179869, upload-time = "2026-04-08T01:56:17.157Z" }, - { url = "https://files.pythonhosted.org/packages/5f/45/6d80dc379b0bbc1f9d1e429f42e4cb9e1d319c7a8201beffd967c516ea01/cryptography-46.0.7-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b36a4695e29fe69215d75960b22577197aca3f7a25b9cf9d165dcfe9d80bc325", size = 4275492, upload-time = "2026-04-08T01:56:19.36Z" }, - { url = "https://files.pythonhosted.org/packages/4a/9a/1765afe9f572e239c3469f2cb429f3ba7b31878c893b246b4b2994ffe2fe/cryptography-46.0.7-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5ad9ef796328c5e3c4ceed237a183f5d41d21150f972455a9d926593a1dcb308", size = 4426670, upload-time = "2026-04-08T01:56:21.415Z" }, - { url = "https://files.pythonhosted.org/packages/8f/3e/af9246aaf23cd4ee060699adab1e47ced3f5f7e7a8ffdd339f817b446462/cryptography-46.0.7-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:73510b83623e080a2c35c62c15298096e2a5dc8d51c3b4e1740211839d0dea77", size = 4280275, upload-time = "2026-04-08T01:56:23.539Z" }, - { url = "https://files.pythonhosted.org/packages/0f/54/6bbbfc5efe86f9d71041827b793c24811a017c6ac0fd12883e4caa86b8ed/cryptography-46.0.7-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:cbd5fb06b62bd0721e1170273d3f4d5a277044c47ca27ee257025146c34cbdd1", size = 4928402, upload-time = "2026-04-08T01:56:25.624Z" }, - { url = "https://files.pythonhosted.org/packages/2d/cf/054b9d8220f81509939599c8bdbc0c408dbd2bdd41688616a20731371fe0/cryptography-46.0.7-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:420b1e4109cc95f0e5700eed79908cef9268265c773d3a66f7af1eef53d409ef", size = 4459985, upload-time = "2026-04-08T01:56:27.309Z" }, - { url = "https://files.pythonhosted.org/packages/f9/46/4e4e9c6040fb01c7467d47217d2f882daddeb8828f7df800cb806d8a2288/cryptography-46.0.7-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:24402210aa54baae71d99441d15bb5a1919c195398a87b563df84468160a65de", size = 3990652, upload-time = "2026-04-08T01:56:29.095Z" }, - { url = "https://files.pythonhosted.org/packages/36/5f/313586c3be5a2fbe87e4c9a254207b860155a8e1f3cca99f9910008e7d08/cryptography-46.0.7-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:8a469028a86f12eb7d2fe97162d0634026d92a21f3ae0ac87ed1c4a447886c83", size = 4279805, upload-time = "2026-04-08T01:56:30.928Z" }, - { url = "https://files.pythonhosted.org/packages/69/33/60dfc4595f334a2082749673386a4d05e4f0cf4df8248e63b2c3437585f2/cryptography-46.0.7-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:9694078c5d44c157ef3162e3bf3946510b857df5a3955458381d1c7cfc143ddb", size = 4892883, upload-time = "2026-04-08T01:56:32.614Z" }, - { url = "https://files.pythonhosted.org/packages/c7/0b/333ddab4270c4f5b972f980adef4faa66951a4aaf646ca067af597f15563/cryptography-46.0.7-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:42a1e5f98abb6391717978baf9f90dc28a743b7d9be7f0751a6f56a75d14065b", size = 4459756, upload-time = "2026-04-08T01:56:34.306Z" }, - { url = "https://files.pythonhosted.org/packages/d2/14/633913398b43b75f1234834170947957c6b623d1701ffc7a9600da907e89/cryptography-46.0.7-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:91bbcb08347344f810cbe49065914fe048949648f6bd5c2519f34619142bbe85", size = 4410244, upload-time = "2026-04-08T01:56:35.977Z" }, - { url = "https://files.pythonhosted.org/packages/10/f2/19ceb3b3dc14009373432af0c13f46aa08e3ce334ec6eff13492e1812ccd/cryptography-46.0.7-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:5d1c02a14ceb9148cc7816249f64f623fbfee39e8c03b3650d842ad3f34d637e", size = 4674868, upload-time = "2026-04-08T01:56:38.034Z" }, - { url = "https://files.pythonhosted.org/packages/1a/bb/a5c213c19ee94b15dfccc48f363738633a493812687f5567addbcbba9f6f/cryptography-46.0.7-cp311-abi3-win32.whl", hash = "sha256:d23c8ca48e44ee015cd0a54aeccdf9f09004eba9fc96f38c911011d9ff1bd457", size = 3026504, upload-time = "2026-04-08T01:56:39.666Z" }, - { url = "https://files.pythonhosted.org/packages/2b/02/7788f9fefa1d060ca68717c3901ae7fffa21ee087a90b7f23c7a603c32ae/cryptography-46.0.7-cp311-abi3-win_amd64.whl", hash = "sha256:397655da831414d165029da9bc483bed2fe0e75dde6a1523ec2fe63f3c46046b", size = 3488363, upload-time = "2026-04-08T01:56:41.893Z" }, - { url = "https://files.pythonhosted.org/packages/7b/56/15619b210e689c5403bb0540e4cb7dbf11a6bf42e483b7644e471a2812b3/cryptography-46.0.7-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:d151173275e1728cf7839aaa80c34fe550c04ddb27b34f48c232193df8db5842", size = 7119671, upload-time = "2026-04-08T01:56:44Z" }, - { url = "https://files.pythonhosted.org/packages/74/66/e3ce040721b0b5599e175ba91ab08884c75928fbeb74597dd10ef13505d2/cryptography-46.0.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:db0f493b9181c7820c8134437eb8b0b4792085d37dbb24da050476ccb664e59c", size = 4268551, upload-time = "2026-04-08T01:56:46.071Z" }, - { url = "https://files.pythonhosted.org/packages/03/11/5e395f961d6868269835dee1bafec6a1ac176505a167f68b7d8818431068/cryptography-46.0.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ebd6daf519b9f189f85c479427bbd6e9c9037862cf8fe89ee35503bd209ed902", size = 4408887, upload-time = "2026-04-08T01:56:47.718Z" }, - { url = "https://files.pythonhosted.org/packages/40/53/8ed1cf4c3b9c8e611e7122fb56f1c32d09e1fff0f1d77e78d9ff7c82653e/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:b7b412817be92117ec5ed95f880defe9cf18a832e8cafacf0a22337dc1981b4d", size = 4271354, upload-time = "2026-04-08T01:56:49.312Z" }, - { url = "https://files.pythonhosted.org/packages/50/46/cf71e26025c2e767c5609162c866a78e8a2915bbcfa408b7ca495c6140c4/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:fbfd0e5f273877695cb93baf14b185f4878128b250cc9f8e617ea0c025dfb022", size = 4905845, upload-time = "2026-04-08T01:56:50.916Z" }, - { url = "https://files.pythonhosted.org/packages/c0/ea/01276740375bac6249d0a971ebdf6b4dc9ead0ee0a34ef3b5a88c1a9b0d4/cryptography-46.0.7-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:ffca7aa1d00cf7d6469b988c581598f2259e46215e0140af408966a24cf086ce", size = 4444641, upload-time = "2026-04-08T01:56:52.882Z" }, - { url = "https://files.pythonhosted.org/packages/3d/4c/7d258f169ae71230f25d9f3d06caabcff8c3baf0978e2b7d65e0acac3827/cryptography-46.0.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:60627cf07e0d9274338521205899337c5d18249db56865f943cbe753aa96f40f", size = 3967749, upload-time = "2026-04-08T01:56:54.597Z" }, - { url = "https://files.pythonhosted.org/packages/b5/2a/2ea0767cad19e71b3530e4cad9605d0b5e338b6a1e72c37c9c1ceb86c333/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:80406c3065e2c55d7f49a9550fe0c49b3f12e5bfff5dedb727e319e1afb9bf99", size = 4270942, upload-time = "2026-04-08T01:56:56.416Z" }, - { url = "https://files.pythonhosted.org/packages/41/3d/fe14df95a83319af25717677e956567a105bb6ab25641acaa093db79975d/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:c5b1ccd1239f48b7151a65bc6dd54bcfcc15e028c8ac126d3fada09db0e07ef1", size = 4871079, upload-time = "2026-04-08T01:56:58.31Z" }, - { url = "https://files.pythonhosted.org/packages/9c/59/4a479e0f36f8f378d397f4eab4c850b4ffb79a2f0d58704b8fa0703ddc11/cryptography-46.0.7-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d5f7520159cd9c2154eb61eb67548ca05c5774d39e9c2c4339fd793fe7d097b2", size = 4443999, upload-time = "2026-04-08T01:57:00.508Z" }, - { url = "https://files.pythonhosted.org/packages/28/17/b59a741645822ec6d04732b43c5d35e4ef58be7bfa84a81e5ae6f05a1d33/cryptography-46.0.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fcd8eac50d9138c1d7fc53a653ba60a2bee81a505f9f8850b6b2888555a45d0e", size = 4399191, upload-time = "2026-04-08T01:57:02.654Z" }, - { url = "https://files.pythonhosted.org/packages/59/6a/bb2e166d6d0e0955f1e9ff70f10ec4b2824c9cfcdb4da772c7dd69cc7d80/cryptography-46.0.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:65814c60f8cc400c63131584e3e1fad01235edba2614b61fbfbfa954082db0ee", size = 4655782, upload-time = "2026-04-08T01:57:04.592Z" }, - { url = "https://files.pythonhosted.org/packages/95/b6/3da51d48415bcb63b00dc17c2eff3a651b7c4fed484308d0f19b30e8cb2c/cryptography-46.0.7-cp314-cp314t-win32.whl", hash = "sha256:fdd1736fed309b4300346f88f74cd120c27c56852c3838cab416e7a166f67298", size = 3002227, upload-time = "2026-04-08T01:57:06.91Z" }, - { url = "https://files.pythonhosted.org/packages/32/a8/9f0e4ed57ec9cebe506e58db11ae472972ecb0c659e4d52bbaee80ca340a/cryptography-46.0.7-cp314-cp314t-win_amd64.whl", hash = "sha256:e06acf3c99be55aa3b516397fe42f5855597f430add9c17fa46bf2e0fb34c9bb", size = 3475332, upload-time = "2026-04-08T01:57:08.807Z" }, - { url = "https://files.pythonhosted.org/packages/a7/7f/cd42fc3614386bc0c12f0cb3c4ae1fc2bbca5c9662dfed031514911d513d/cryptography-46.0.7-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:462ad5cb1c148a22b2e3bcc5ad52504dff325d17daf5df8d88c17dda1f75f2a4", size = 7165618, upload-time = "2026-04-08T01:57:10.645Z" }, - { url = "https://files.pythonhosted.org/packages/a5/d0/36a49f0262d2319139d2829f773f1b97ef8aef7f97e6e5bd21455e5a8fb5/cryptography-46.0.7-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:84d4cced91f0f159a7ddacad249cc077e63195c36aac40b4150e7a57e84fffe7", size = 4270628, upload-time = "2026-04-08T01:57:12.885Z" }, - { url = "https://files.pythonhosted.org/packages/8a/6c/1a42450f464dda6ffbe578a911f773e54dd48c10f9895a23a7e88b3e7db5/cryptography-46.0.7-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:128c5edfe5e5938b86b03941e94fac9ee793a94452ad1365c9fc3f4f62216832", size = 4415405, upload-time = "2026-04-08T01:57:14.923Z" }, - { url = "https://files.pythonhosted.org/packages/9a/92/4ed714dbe93a066dc1f4b4581a464d2d7dbec9046f7c8b7016f5286329e2/cryptography-46.0.7-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:5e51be372b26ef4ba3de3c167cd3d1022934bc838ae9eaad7e644986d2a3d163", size = 4272715, upload-time = "2026-04-08T01:57:16.638Z" }, - { url = "https://files.pythonhosted.org/packages/b7/e6/a26b84096eddd51494bba19111f8fffe976f6a09f132706f8f1bf03f51f7/cryptography-46.0.7-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:cdf1a610ef82abb396451862739e3fc93b071c844399e15b90726ef7470eeaf2", size = 4918400, upload-time = "2026-04-08T01:57:19.021Z" }, - { url = "https://files.pythonhosted.org/packages/c7/08/ffd537b605568a148543ac3c2b239708ae0bd635064bab41359252ef88ed/cryptography-46.0.7-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:1d25aee46d0c6f1a501adcddb2d2fee4b979381346a78558ed13e50aa8a59067", size = 4450634, upload-time = "2026-04-08T01:57:21.185Z" }, - { url = "https://files.pythonhosted.org/packages/16/01/0cd51dd86ab5b9befe0d031e276510491976c3a80e9f6e31810cce46c4ad/cryptography-46.0.7-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:cdfbe22376065ffcf8be74dc9a909f032df19bc58a699456a21712d6e5eabfd0", size = 3985233, upload-time = "2026-04-08T01:57:22.862Z" }, - { url = "https://files.pythonhosted.org/packages/92/49/819d6ed3a7d9349c2939f81b500a738cb733ab62fbecdbc1e38e83d45e12/cryptography-46.0.7-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:abad9dac36cbf55de6eb49badd4016806b3165d396f64925bf2999bcb67837ba", size = 4271955, upload-time = "2026-04-08T01:57:24.814Z" }, - { url = "https://files.pythonhosted.org/packages/80/07/ad9b3c56ebb95ed2473d46df0847357e01583f4c52a85754d1a55e29e4d0/cryptography-46.0.7-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:935ce7e3cfdb53e3536119a542b839bb94ec1ad081013e9ab9b7cfd478b05006", size = 4879888, upload-time = "2026-04-08T01:57:26.88Z" }, - { url = "https://files.pythonhosted.org/packages/b8/c7/201d3d58f30c4c2bdbe9b03844c291feb77c20511cc3586daf7edc12a47b/cryptography-46.0.7-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:35719dc79d4730d30f1c2b6474bd6acda36ae2dfae1e3c16f2051f215df33ce0", size = 4449961, upload-time = "2026-04-08T01:57:29.068Z" }, - { url = "https://files.pythonhosted.org/packages/a5/ef/649750cbf96f3033c3c976e112265c33906f8e462291a33d77f90356548c/cryptography-46.0.7-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7bbc6ccf49d05ac8f7d7b5e2e2c33830d4fe2061def88210a126d130d7f71a85", size = 4401696, upload-time = "2026-04-08T01:57:31.029Z" }, - { url = "https://files.pythonhosted.org/packages/41/52/a8908dcb1a389a459a29008c29966c1d552588d4ae6d43f3a1a4512e0ebe/cryptography-46.0.7-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:a1529d614f44b863a7b480c6d000fe93b59acee9c82ffa027cfadc77521a9f5e", size = 4664256, upload-time = "2026-04-08T01:57:33.144Z" }, - { url = "https://files.pythonhosted.org/packages/4b/fa/f0ab06238e899cc3fb332623f337a7364f36f4bb3f2534c2bb95a35b132c/cryptography-46.0.7-cp38-abi3-win32.whl", hash = "sha256:f247c8c1a1fb45e12586afbb436ef21ff1e80670b2861a90353d9b025583d246", size = 3013001, upload-time = "2026-04-08T01:57:34.933Z" }, - { url = "https://files.pythonhosted.org/packages/d2/f1/00ce3bde3ca542d1acd8f8cfa38e446840945aa6363f9b74746394b14127/cryptography-46.0.7-cp38-abi3-win_amd64.whl", hash = "sha256:506c4ff91eff4f82bdac7633318a526b1d1309fc07ca76a3ad182cb5b686d6d3", size = 3472985, upload-time = "2026-04-08T01:57:36.714Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/1f/99/d1c90d6041656cc6ee229dc99cd67fd0cd5aec3c5f7d72fffc27cc750054/cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493", size = 854345, upload-time = "2026-06-12T20:02:30.512Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9b/22/adf66990e63584a68dfb50c24f48a125c07b1699899381c8151e63ed458c/cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db", size = 4032100, upload-time = "2026-06-12T20:02:32.143Z" }, + { url = "https://files.pythonhosted.org/packages/09/41/3797cfaf69cae04a13ee78ebd83f0678d9c02b4779d21ce24445326f1a69/cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db", size = 4692978, upload-time = "2026-06-12T20:01:21.305Z" }, + { url = "https://files.pythonhosted.org/packages/e6/8b/43011f7ebe515a8aa20d61f290a326cd890c2e738e16e59eaff8d9c3a412/cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325", size = 4716422, upload-time = "2026-06-12T20:01:48.566Z" }, + { url = "https://files.pythonhosted.org/packages/4a/91/01ce7303a4579e6d3a6abef01bd322848e9ea7a219adcabc5048b9033571/cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2", size = 4700503, upload-time = "2026-06-12T20:02:47.091Z" }, + { url = "https://files.pythonhosted.org/packages/62/99/a2c95cf8293f07491e9e27c20cc4dcd18176d944e674679adeb1d0173fd6/cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b", size = 5309779, upload-time = "2026-06-12T20:02:08.987Z" }, + { url = "https://files.pythonhosted.org/packages/20/2c/0622f20ff02b2ef32558733443805dc82fd4c275be01b2d19d14676f3a1b/cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6", size = 4749683, upload-time = "2026-06-12T20:02:03.335Z" }, + { url = "https://files.pythonhosted.org/packages/a3/5b/c5246635d5fd3b64e0d45ae10e99fd32fe9676a79915ccfe5a61ba9af1a5/cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c", size = 4337874, upload-time = "2026-06-12T20:02:54.323Z" }, + { url = "https://files.pythonhosted.org/packages/6d/88/05563c7fe2e914e87d1a536d06fe83e66b4e1d95cb593e05aea375531da8/cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7", size = 4700283, upload-time = "2026-06-12T20:01:34.822Z" }, + { url = "https://files.pythonhosted.org/packages/c4/b6/d7696e4e890d6ae1469935164c9e5215c557671cb78d6e3f458ccceaa632/cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68", size = 5265844, upload-time = "2026-06-12T20:01:24.09Z" }, + { url = "https://files.pythonhosted.org/packages/a9/3c/f3ad17eecc1a57b0ba236dc01f90e783c51f4a2f35f64777cc4f47a184b2/cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9", size = 4749290, upload-time = "2026-06-12T20:01:30.848Z" }, + { url = "https://files.pythonhosted.org/packages/4f/01/339573cf1023163a400b0b5d16f6d507de413b9f60be6fd1b77feeaf6737/cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f", size = 4834612, upload-time = "2026-06-12T20:01:29.246Z" }, + { url = "https://files.pythonhosted.org/packages/71/fd/577302e213a1be9468f92d1afef66fcf1ef83d516819d9992ca547f592bd/cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459", size = 4980804, upload-time = "2026-06-12T20:01:42.853Z" }, + { url = "https://files.pythonhosted.org/packages/1f/09/f42b1d190c5ba75f72062a387f8030d1d75f6ab035788f1d9c4b01de6525/cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e", size = 3810026, upload-time = "2026-06-12T20:02:39.262Z" }, + { url = "https://files.pythonhosted.org/packages/ec/9e/db72b3ae7fc9cfad53e630e56c6ae83b9b6ff0bf3718ffb8012d20b3aabf/cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7", size = 4013892, upload-time = "2026-06-12T20:02:10.735Z" }, + { url = "https://files.pythonhosted.org/packages/86/12/c48a424f38db03027be9f7ed5c7dc5de9933dbee992865f98b13727a009d/cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d", size = 4678835, upload-time = "2026-06-12T20:02:48.743Z" }, + { url = "https://files.pythonhosted.org/packages/68/28/8a3ad4653662c93fc44dc4e5d8fd374c25c42e07b34bbfbadf49cf57a5a8/cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa", size = 4697239, upload-time = "2026-06-12T20:02:56.03Z" }, + { url = "https://files.pythonhosted.org/packages/a8/b2/2193fc74f81aee4f9b62733133b73b5176718932ed8f2e4b03fa040480a6/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb", size = 4685593, upload-time = "2026-06-12T20:02:50.666Z" }, + { url = "https://files.pythonhosted.org/packages/47/f1/1d3eaa243bfc5de4a187b22aa8c048b3e4980bfbe830ac46e6bac2e66947/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d", size = 5289961, upload-time = "2026-06-12T20:01:46.468Z" }, + { url = "https://files.pythonhosted.org/packages/58/39/2d51306721330c486495853eda1c567880ff036de15a14c4b74f399934af/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561", size = 4731145, upload-time = "2026-06-12T20:02:16.832Z" }, + { url = "https://files.pythonhosted.org/packages/17/50/983e838c7fd0d87fd8c969bcdd328edaf5f756e38df5281637424c155873/cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122", size = 4321719, upload-time = "2026-06-12T20:02:52.611Z" }, + { url = "https://files.pythonhosted.org/packages/a7/f5/8f571d7e27c55bce9f76f026143bcb1e040a4233149ecca0bea5fa5dd5f7/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505", size = 4685209, upload-time = "2026-06-12T20:02:07.282Z" }, + { url = "https://files.pythonhosted.org/packages/e7/84/0e27016a6fc5a0886f797018b26aa42f40c09a82332bff77822a451deaaa/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866", size = 5246285, upload-time = "2026-06-12T20:01:32.439Z" }, + { url = "https://files.pythonhosted.org/packages/11/2d/5e1fb307cb5931881516b464c98774b3f2c36b5d4bb9a2830253cf553cad/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8", size = 4730441, upload-time = "2026-06-12T20:02:01.469Z" }, + { url = "https://files.pythonhosted.org/packages/e4/c0/bff5a02ee731d207d6a1ed51732549d8c53d2bc8da1d10ec6f2844201d68/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3", size = 4815869, upload-time = "2026-06-12T20:01:36.574Z" }, + { url = "https://files.pythonhosted.org/packages/b9/26/814681d14248d95d73d5c3eea0c39a94eb8302df966f670a2c60de90974b/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27", size = 4960948, upload-time = "2026-06-12T20:02:18.688Z" }, + { url = "https://files.pythonhosted.org/packages/4c/fe/93ecac273d3738939d023612ad12cca9a3740a5345d69fda04134c43fd96/cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61", size = 3799153, upload-time = "2026-06-12T20:01:39.059Z" }, + { url = "https://files.pythonhosted.org/packages/19/2a/5bb823f5bedcf80718cea7fbc95ec5515cca3769633c4b01a32be7f30e7c/cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a", size = 4025947, upload-time = "2026-06-12T20:01:25.745Z" }, + { url = "https://files.pythonhosted.org/packages/3d/df/40577043ca124e17012f408ddddaeb213b856336ac82ddb3bc915f39e29f/cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4", size = 4692429, upload-time = "2026-06-12T20:01:53.628Z" }, + { url = "https://files.pythonhosted.org/packages/2c/99/2d13299eb3dd27b02dcfaafcc91d6b5cb3329f7cbd6d8f51921acd566c1a/cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18", size = 4700968, upload-time = "2026-06-12T20:02:45.383Z" }, + { url = "https://files.pythonhosted.org/packages/a5/4d/9c0cd02f95e2602dd5e563da149ee0830abef3537be8b34dc56281ebe27a/cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69", size = 4697758, upload-time = "2026-06-12T20:01:41.13Z" }, + { url = "https://files.pythonhosted.org/packages/24/01/186c825898477d77e2324d5360fefe622ff1d8d1963ec0554e2cada8ec77/cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64", size = 5298863, upload-time = "2026-06-12T20:02:24.579Z" }, + { url = "https://files.pythonhosted.org/packages/b8/7b/62cbbab75d0659865bf0273790031544a0b16c8072d258f9428dcd8190dc/cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21", size = 4735983, upload-time = "2026-06-12T20:01:50.14Z" }, + { url = "https://files.pythonhosted.org/packages/6c/72/3e798c064bc39e471008075d0f9bc9daf77a80879c092e4a8e170c585ed4/cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9", size = 4334173, upload-time = "2026-06-12T20:01:44.743Z" }, + { url = "https://files.pythonhosted.org/packages/f0/ee/6fca21d1ac73e06f8bef71940abfd4d2f6472b4bca284d770f32bd4086f6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc", size = 4697298, upload-time = "2026-06-12T20:02:20.918Z" }, + { url = "https://files.pythonhosted.org/packages/67/d0/a5fcd3515f0bae49a7b6d0413cc1bdccdcc1fc0047037a0d480642cdc5d6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8", size = 5254338, upload-time = "2026-06-12T20:02:22.737Z" }, + { url = "https://files.pythonhosted.org/packages/a0/84/84fe36f19caf857d61cb7fc9c63035a47ffabd84ea12d1d393148efa3615/cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36", size = 4735650, upload-time = "2026-06-12T20:02:41.389Z" }, + { url = "https://files.pythonhosted.org/packages/6c/a0/db537264e234f7273a73ec020873d6d6b39dfd8a53db78b550ca8320440e/cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e", size = 4834820, upload-time = "2026-06-12T20:01:51.847Z" }, + { url = "https://files.pythonhosted.org/packages/93/77/8df9eb486495979bccecd1062e2eaf435250e84437040295b57d09048b0b/cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b", size = 4967968, upload-time = "2026-06-12T20:02:12.524Z" }, + { url = "https://files.pythonhosted.org/packages/c2/e6/f60198ea8d9dfa15fff9ed4ca02ce362f6eadd9ba757dcc50634c4257b63/cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001", size = 3785547, upload-time = "2026-06-12T20:02:26.847Z" }, ] [[package]] @@ -267,7 +267,7 @@ wheels = [ [[package]] name = "fastapi" -version = "0.136.1" +version = "0.138.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "annotated-doc" }, @@ -276,30 +276,30 @@ dependencies = [ { name = "typing-extensions" }, { name = "typing-inspection" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/5d/45/c130091c2dfa061bbfe3150f2a5091ef1adf149f2a8d2ae769ecaf6e99a2/fastapi-0.136.1.tar.gz", hash = "sha256:7af665ad7acfa0a3baf8983d393b6b471b9da10ede59c60045f49fbc89a0fa7f", size = 397448, upload-time = "2026-04-23T16:49:44.046Z" } +sdist = { url = "https://files.pythonhosted.org/packages/0c/a9/9f8f7e00195c29836e9bf58bbbaf579e29878b8a67851efff93d9b6d4eb7/fastapi-0.138.2.tar.gz", hash = "sha256:6432359d067a432134620e7c5e4c6e5063e7f37815bbbbf20acef14b0d2e3fc8", size = 420423, upload-time = "2026-06-29T12:44:12.556Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5a/ff/2e4eca3ade2c22fe1dea7043b8ee9dabe47753349eb1b56a202de8af6349/fastapi-0.136.1-py3-none-any.whl", hash = "sha256:a6e9d7eeada96c93a4d69cb03836b44fa34e2854accb7244a1ece36cd4781c3f", size = 117683, upload-time = "2026-04-23T16:49:42.437Z" }, + { url = "https://files.pythonhosted.org/packages/f2/b3/38be2c074bdd0c986340db1d72d7b2321b805b1c5a68069aa00b5d31fd02/fastapi-0.138.2-py3-none-any.whl", hash = "sha256:db90c1ffb5517fba5d4a9f80e866daa008747e646310c9ce155c8c535f9d1615", size = 129271, upload-time = "2026-06-29T12:44:13.905Z" }, ] [[package]] name = "filelock" -version = "3.29.0" +version = "3.29.4" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/b5/fe/997687a931ab51049acce6fa1f23e8f01216374ea81374ddee763c493db5/filelock-3.29.0.tar.gz", hash = "sha256:69974355e960702e789734cb4871f884ea6fe50bd8404051a3530bc07809cf90", size = 57571, upload-time = "2026-04-19T15:39:10.068Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e6/dc/be6cbe99670cd6e4ad387123647cb08e0c32975e223f82551e914c5568a6/filelock-3.29.4.tar.gz", hash = "sha256:10cdb3656fc44541cdf30652a93fb10ec6b05325620eb316bd26893e4201538a", size = 63028, upload-time = "2026-06-13T16:12:00.744Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/81/47/dd9a212ef6e343a6857485ffe25bba537304f1913bdbed446a23f7f592e1/filelock-3.29.0-py3-none-any.whl", hash = "sha256:96f5f6344709aa1572bbf631c640e4ebeeb519e08da902c39a001882f30ac258", size = 39812, upload-time = "2026-04-19T15:39:08.752Z" }, + { url = "https://files.pythonhosted.org/packages/13/37/a065dc3bd6e49423a6532c642ca7378d3f467b1ef44c2800c937af7f9739/filelock-3.29.4-py3-none-any.whl", hash = "sha256:dac1648087d5115554850d113e7dd8c83ab2d38e3435dde2d4f163847e57b767", size = 42757, upload-time = "2026-06-13T16:11:59.582Z" }, ] [[package]] name = "flowr" -version = "1.2.0" +version = "1.2.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "pyyaml" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/16/34/2c6bdca43fa262323e54043a3413fcb7b3ce32c1aec638b70d0d7cfdc388/flowr-1.2.0.tar.gz", hash = "sha256:f78deed9984e524226e345d84c2a8f8b04bf44c99ec8b649663af25e3b05b8d9", size = 210725, upload-time = "2026-05-22T17:53:37.325Z" } +sdist = { url = "https://files.pythonhosted.org/packages/d2/78/3d282f91a177eb1e51826764ffa794894a28e08d1fbc1fd2de2b5a6e8849/flowr-1.2.1.tar.gz", hash = "sha256:0788f15599ba26992e2e691b6e9cebf294ecb88ccf4dbbb321270bff71fe9aed", size = 210796, upload-time = "2026-05-22T18:23:56.577Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/53/50/4b4093d9101fe854b1d59d253539baf3db70b9dd3c8c349c0106546d0406/flowr-1.2.0-py3-none-any.whl", hash = "sha256:058614aadb215d81246b802618817dd9d0f1ce93bb98c89e896881de8eb2d480", size = 214468, upload-time = "2026-05-22T17:53:35.791Z" }, + { url = "https://files.pythonhosted.org/packages/81/8f/bf95a539faac78a07c0e9c811756fd5529b2b0a4f63faf0e88eb8a1f3b2a/flowr-1.2.1-py3-none-any.whl", hash = "sha256:e3871ae0ab94e30c87f1f31362792257bb14ce584f5fb662964767f62862ffb7", size = 214708, upload-time = "2026-05-22T18:23:54.71Z" }, ] [package.optional-dependencies] @@ -310,14 +310,14 @@ viz = [ [[package]] name = "gherkin-official" -version = "39.0.0" +version = "41.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/2f/cf/8c0f7ec0e041c12ab59fae0c01b95ac69113a2fecb45618780525f8ca5ee/gherkin_official-39.0.0.tar.gz", hash = "sha256:675b9c6c0c342b0ec44bddf927de923adbd79879277816ce96bf248533677060", size = 33683, upload-time = "2026-03-01T16:46:42.382Z" } +sdist = { url = "https://files.pythonhosted.org/packages/4c/4f/525b5a98134a47e5009d910ed60e7e046d55be35796e34b6997ebf4d8241/gherkin_official-41.0.0.tar.gz", hash = "sha256:3e63a45c6daa43a25b159cdfd84c9703c2956c0736fe42119501a441c151b3db", size = 33992, upload-time = "2026-06-20T07:06:30.064Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/61/b3/743f97b16ef781283cde3c7b06a95b309a75ae2f4003a6611d35abc3c613/gherkin_official-39.0.0-py3-none-any.whl", hash = "sha256:1fd9b8709c00d946c0fd617a9834d4cb2af026213a2e8e7822fe24dd5064fe22", size = 38471, upload-time = "2026-03-01T16:46:43.308Z" }, + { url = "https://files.pythonhosted.org/packages/45/f5/2a8c9bc5a0e281f44d96316466e9181c2684e4f67154009a81948fab90d9/gherkin_official-41.0.0-py3-none-any.whl", hash = "sha256:e8c4ea8fee8350f22eacdf13ea5ac16e84273f95839b7c3fac600c3a4f1daca3", size = 38823, upload-time = "2026-06-20T07:06:28.812Z" }, ] [[package]] @@ -371,23 +371,23 @@ wheels = [ [[package]] name = "hypothesis" -version = "6.152.1" +version = "6.155.7" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "sortedcontainers" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/64/b1/c32bcddb9aab9e3abc700f1f56faf14e7655c64a16ca47701a57362276ea/hypothesis-6.152.1.tar.gz", hash = "sha256:4f4ed934eee295dd84ee97592477d23e8dc03e9f12ae0ee30a4e7c9ef3fca3b0", size = 465029, upload-time = "2026-04-14T22:29:24.062Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f2/55/983b6bc1b6b343a5ff6020388f9d0680ab477be59a731517e6c4a0387100/hypothesis-6.155.7.tar.gz", hash = "sha256:d8d6091753d0669db3c90c5e5b346cb37c72f3dd9378c8413acb1fd5da63f7ea", size = 478291, upload-time = "2026-06-21T05:54:31.573Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5d/83/860fb3075e00b0fc19a22a2301bc3c96f00437558c3911bdd0a3573a4a53/hypothesis-6.152.1-py3-none-any.whl", hash = "sha256:40a3619d9e0cb97b018857c7986f75cf5de2e5ec0fa8a0b172d00747758f749e", size = 530752, upload-time = "2026-04-14T22:29:20.893Z" }, + { url = "https://files.pythonhosted.org/packages/01/f8/c151e196d4f397ed9436a071e52666c70a2f021138dea828b0a461e245db/hypothesis-6.155.7-py3-none-any.whl", hash = "sha256:9f634bdb1f9e9b8ab6ba09431cf2deedb750c96978125a6fb3c5a0f6c6db4131", size = 544762, upload-time = "2026-06-21T05:54:29.506Z" }, ] [[package]] name = "idna" -version = "3.11" +version = "3.18" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" } +sdist = { url = "https://files.pythonhosted.org/packages/cd/63/9496c57188a2ee585e0f1db071d75089a11e98aa86eb99d9d7618fc1edce/idna-3.18.tar.gz", hash = "sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848", size = 196711, upload-time = "2026-06-02T14:34:07.794Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" }, + { url = "https://files.pythonhosted.org/packages/1e/5e/d4e9f1a599fb8e573b7b87160658329fbf28d19eac2718f51fc3def3aa5a/idna-3.18-py3-none-any.whl", hash = "sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2", size = 65455, upload-time = "2026-06-02T14:34:06.319Z" }, ] [[package]] @@ -422,26 +422,60 @@ wheels = [ [[package]] name = "joserfc" -version = "1.6.4" +version = "1.7.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "cryptography" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/de/c6/de8fdbdfa75c8ca04fead38a82d573df8a82906e984c349d58665f459558/joserfc-1.6.4.tar.gz", hash = "sha256:34ce5f499bfcc5e9ad4cc75077f9278ab3227b71da9aaf28f9ab705f8a560d3c", size = 231866, upload-time = "2026-04-13T13:15:40.632Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f1/26/abe1ad855eb334b5ebc9c6495d4798e12bee70e5e8e815d54570710b8312/joserfc-1.7.2.tar.gz", hash = "sha256:537ffb8888b2df039cb5b6d017d7cff6f09d521ce65d89cc9b8ab752b1cff947", size = 233183, upload-time = "2026-06-29T09:03:10.868Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b6/f7/210b27752e972edb36d239315b08d3eb6b14824cc4a590da2337d195260b/joserfc-1.6.4-py3-none-any.whl", hash = "sha256:3e4a22b509b41908989237a045e25c8308d5fd47ab96bdae2dd8057c6451003a", size = 70464, upload-time = "2026-04-13T13:15:39.259Z" }, + { url = "https://files.pythonhosted.org/packages/13/80/d1b30336582cced4dce0dae776508a6011723e32f907bc7a702c0b25890a/joserfc-1.7.2-py3-none-any.whl", hash = "sha256:ddd818c0ca9b4f17bbc2d72cb3966e6ded7502be089316c62c3cc64ae86132b5", size = 70426, upload-time = "2026-06-29T09:03:09.393Z" }, +] + +[[package]] +name = "librt" +version = "0.11.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/40/08/9e7f6b5d2b5bed6ad055cdd5925f192bb403a51280f86b56554d9d0699a2/librt-0.11.0.tar.gz", hash = "sha256:075dc3ef4458a278e0195cbf6ac9d38808d9b906c5a6c7f7f79c3888276a3fb1", size = 200139, upload-time = "2026-05-10T18:17:25.138Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/29/eb/dbce197da4e227779e56b5735f2decc3eb36e55a1cdbf1bd65d6639d76c1/librt-0.11.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:4a017a95e5837dc15a8c5661d60e05daa96b90908b1aa6b7acdf443cd25c8ebd", size = 143345, upload-time = "2026-05-10T18:16:30.674Z" }, + { url = "https://files.pythonhosted.org/packages/76/a3/254bebd0c11c8ba684018efb8006ff22e466abce445215cca6c778e7d9de/librt-0.11.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:b1ecbd9819deccc39b7542bf4d2a740d8a620694d39989e58661d3763458f8d4", size = 143131, upload-time = "2026-05-10T18:16:32.037Z" }, + { url = "https://files.pythonhosted.org/packages/f1/3f/f77d6122d21ac7bf6ae8a7dfced1bd2a7ac545d3273ebdcaf8042f6d619f/librt-0.11.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7da327dacd7be8f8ec36547373550744a3cc0e536d54665cd83f8bcd961200e8", size = 477024, upload-time = "2026-05-10T18:16:33.493Z" }, + { url = "https://files.pythonhosted.org/packages/ac/0a/2c996dadebaa7d9bbbd43ef2d4f3e66b6da545f838a41694ef6172cebec8/librt-0.11.0-cp314-cp314-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:0dc56b1f8d06e60db362cc3fdae206681817f86ce4725d34511473487f12a34b", size = 474221, upload-time = "2026-05-10T18:16:34.864Z" }, + { url = "https://files.pythonhosted.org/packages/0a/7e/f5d92af8486b8272c23b3e686b46ff72d89c8169585eb61eef01a2ac7147/librt-0.11.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:05fb8fb2ab90e21c8d12ea240d744ad514da9baf381ebfa70d91d20d21713175", size = 505174, upload-time = "2026-05-10T18:16:36.705Z" }, + { url = "https://files.pythonhosted.org/packages/af/1a/cb0734fe86398eb33193ab753b7326255c74cac5eb09e76b9b16536e7adb/librt-0.11.0-cp314-cp314-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cae74872be221df4374d10fec61f93ed1513b9546ea84f2c0bf73ab3e9bd0b03", size = 497216, upload-time = "2026-05-10T18:16:38.418Z" }, + { url = "https://files.pythonhosted.org/packages/18/06/094820f91558b66e29943c0ec41c9914f460f48dd51fc503c3101e10842d/librt-0.11.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:32bcc918c0148eb7e3d57385125bac7e5f9e4359d05f07448b09f6f778c2f31c", size = 513921, upload-time = "2026-05-10T18:16:39.848Z" }, + { url = "https://files.pythonhosted.org/packages/0b/c2/00de9018871a282f530cacb457d5ec0428f6ac7e6fedde9aff7468d9fb04/librt-0.11.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:f9743fc99135d5f78d2454435615f6dec0473ca507c26ce9d92b10b562a280d3", size = 520850, upload-time = "2026-05-10T18:16:41.471Z" }, + { url = "https://files.pythonhosted.org/packages/51/9d/64631832348fd1834fb3a61b996434edddaaf25a31d03b0a76273159d2cf/librt-0.11.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:5ba067f4aadae8fda802d91d2124c90c42195ff32d9161d3549e6d05cfe26f96", size = 504237, upload-time = "2026-05-10T18:16:43.15Z" }, + { url = "https://files.pythonhosted.org/packages/a5/ec/ae5525eb16edc827a044e7bb8777a455ff95d4bca9379e7e6bddd7383647/librt-0.11.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:de3bf945454d032f9e390b85c4072e0a0570bf825421c8be0e71209fa65e1abe", size = 546261, upload-time = "2026-05-10T18:16:44.408Z" }, + { url = "https://files.pythonhosted.org/packages/5a/09/adce371f27ca039411da9659f7430fcc2ba6cd0c7b3e4467a0f091be7fa9/librt-0.11.0-cp314-cp314-win32.whl", hash = "sha256:d2277a05f6dcb9fd13db9566aac4fabd68c3ea1ea46ee5567d4eef8efa495a2f", size = 96965, upload-time = "2026-05-10T18:16:46.039Z" }, + { url = "https://files.pythonhosted.org/packages/d6/ee/8ac720d98548f173c7ce2e632a7ca94673f74cacd5c8162a84af5b35958a/librt-0.11.0-cp314-cp314-win_amd64.whl", hash = "sha256:ab73e8db5e3f564d812c1f5c3a175930a5f9bc96ccb5e3b22a34d7858b401cf7", size = 115151, upload-time = "2026-05-10T18:16:47.133Z" }, + { url = "https://files.pythonhosted.org/packages/94/20/c900cf14efeb09b6bef2b2dff20779f73464b97fd58d1c6bccc379588ae3/librt-0.11.0-cp314-cp314-win_arm64.whl", hash = "sha256:aea3caa317752e3a466fa8af45d91ee0ea8c7fdd96e42b0a8dd9b76a7931eba1", size = 98850, upload-time = "2026-05-10T18:16:48.597Z" }, + { url = "https://files.pythonhosted.org/packages/0c/71/944bfe4b64e12abffcd3c15e1cce07f72f3d55655083786285f4dedeb532/librt-0.11.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:d1b36540d7aaf9b9101b3a6f376c8d8e9f7a9aec93ed05918f2c69d493ffef72", size = 151138, upload-time = "2026-05-10T18:16:49.839Z" }, + { url = "https://files.pythonhosted.org/packages/b6/10/99e64a5c86989357fda078c8143c533389585f6473b7439172dd8f3b3b2d/librt-0.11.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:efbb343ab2ce3540f4ecbe6315d677ed70f37cd9a72b1e58066c918ca83acbaa", size = 151976, upload-time = "2026-05-10T18:16:51.062Z" }, + { url = "https://files.pythonhosted.org/packages/21/31/5072ad880946d83e5ea4147d6d018c78eefce85b77819b19bdd0ee229435/librt-0.11.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:aa0dd688aab3f7914d3e6e5e3554978e0383312fb8e771d84be008a35b9ee548", size = 557927, upload-time = "2026-05-10T18:16:52.632Z" }, + { url = "https://files.pythonhosted.org/packages/5e/8d/70b5fb7cfbab60edbe7381614ab985da58e144fbf465c86d44c95f43cdca/librt-0.11.0-cp314-cp314t-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:f5fb36b8c6c63fdcbb1d526d94c0d1331610d43f4118cc1beb4efef4f3faacb2", size = 539698, upload-time = "2026-05-10T18:16:53.934Z" }, + { url = "https://files.pythonhosted.org/packages/fa/a3/ba3495a0b3edbd24a4cae0d1d3c64f39a9fc45d06e812101289b50c1a619/librt-0.11.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4a9a237d13addb93715b6fee74023d5ee3469b53fce527626c0e088aa585805f", size = 577162, upload-time = "2026-05-10T18:16:55.589Z" }, + { url = "https://files.pythonhosted.org/packages/f7/db/36e25fb81f99937ff1b96612a1dc9fd66f039cb9cc3aee12c01fac31aab9/librt-0.11.0-cp314-cp314t-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5ddd17bd87b2c56ddd60e546a7984a2e64c4e8eab92fb4cf3830a48ad5469d51", size = 566494, upload-time = "2026-05-10T18:16:56.975Z" }, + { url = "https://files.pythonhosted.org/packages/33/0d/3f622b47f0b013eeb9cf4cc07ae9bfe378d832a4eec998b2b209fe84244d/librt-0.11.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:bd43992b4473d42f12ff9e68326079f0696d9d4e6000e8f39a0238d482ba6ee2", size = 596858, upload-time = "2026-05-10T18:16:58.374Z" }, + { url = "https://files.pythonhosted.org/packages/a9/02/71b90bc93039c46a2000651f6ad60122b114c8f54c4ad306e0e96f5b75ad/librt-0.11.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:f8e3e8056dd674e279741485e2e512d6e9a751c7455809d0114e6ebf8d781085", size = 590318, upload-time = "2026-05-10T18:16:59.676Z" }, + { url = "https://files.pythonhosted.org/packages/04/04/418cb3f75621e2b761fb1ab0f017f4d70a1a72a6e7c74ee4f7e8d198c2f3/librt-0.11.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:c1f708d8ae9c56cf38a903c44297243d2ec83fd82b396b977e0144a3e76217e3", size = 575115, upload-time = "2026-05-10T18:17:01.007Z" }, + { url = "https://files.pythonhosted.org/packages/cc/2c/5a2183ac58dd911f26b5d7e7d7d8f1d87fcecdddd99d6c12169a258ff62c/librt-0.11.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:0add982e0e7b9fc14cf4b33789d5f13f66581889b88c2f58099f6ce8f92617bd", size = 617918, upload-time = "2026-05-10T18:17:02.682Z" }, + { url = "https://files.pythonhosted.org/packages/15/1f/dc6771a52592a4451be6effa200cbfc9cec61e4393d3033d81a9d307961d/librt-0.11.0-cp314-cp314t-win32.whl", hash = "sha256:2b481d846ac894c4e8403c5fd0e87c5d11d6499e404b474602508a224ff531c8", size = 103562, upload-time = "2026-05-10T18:17:03.99Z" }, + { url = "https://files.pythonhosted.org/packages/62/4a/7d1415567027286a75ba1093ec4aca11f073e0f559c530cf3e0a757ad55c/librt-0.11.0-cp314-cp314t-win_amd64.whl", hash = "sha256:28edb433edde181112a908c78907af28f964eabc15f4dd16c9d66c834302677c", size = 124327, upload-time = "2026-05-10T18:17:05.465Z" }, + { url = "https://files.pythonhosted.org/packages/ce/62/b40b382fa0c66fee1478073eb8db352a4a6beda4a1adccf1df911d8c289c/librt-0.11.0-cp314-cp314t-win_arm64.whl", hash = "sha256:dee008f20b542e3cd162ba338a7f9ec0f6d23d395f66fe8aeeec3c9d067ea253", size = 102572, upload-time = "2026-05-10T18:17:06.809Z" }, ] [[package]] name = "markdown-it-py" -version = "4.0.0" +version = "4.2.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "mdurl" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" } +sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, + { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" }, ] [[package]] @@ -510,6 +544,45 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/64/f2/66bd65ca0139675a0d7b18f0bada6e12b51a984e41a76dbe44761bf1b3ee/mslex-1.3.0-py3-none-any.whl", hash = "sha256:c7074b347201b3466fc077c5692fbce9b5f62a63a51f537a53fbbd02eff2eea4", size = 7820, upload-time = "2024-10-16T13:16:17.566Z" }, ] +[[package]] +name = "mypy" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "ast-serialize" }, + { name = "librt", marker = "platform_python_implementation != 'PyPy'" }, + { name = "mypy-extensions" }, + { name = "pathspec" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/82/15/cca9d88503549ed6fedeaa1d448cdddd542ee8a490232d732e278036fbf2/mypy-2.1.0.tar.gz", hash = "sha256:81e76ad12c2d804512e9b13240d1588316531bfba07558286078bfbce9613633", size = 3898359, upload-time = "2026-05-11T18:37:36.237Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b0/ca/b279a672e874aedd5498ae25f722dacc8aa86bbffb939b3f97cbb1cf6686/mypy-2.1.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:7354c5a7f69d9345c3d6e69921d57088eea3ddeeb6b20d34c1b3855b02c36ec2", size = 14848422, upload-time = "2026-05-11T18:35:45.984Z" }, + { url = "https://files.pythonhosted.org/packages/27/e6/3efe56c631d959b9b4454e208b0ac4b7f4f58b404c89f8bec7b49efdfc21/mypy-2.1.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:49890d4f76ac9e06ec117f9e09f3174da70a620a0c300953d8595c926e80947f", size = 13677374, upload-time = "2026-05-11T18:36:57.188Z" }, + { url = "https://files.pythonhosted.org/packages/84/7f/8107ea87a44fd1f1b59882442f033c9c3488c127201b1d1d15f1cbd6022e/mypy-2.1.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:761be68e023ef5d94678772396a8af1220030f80837a3afd8d0aef3b419666f4", size = 14055743, upload-time = "2026-05-11T18:35:18.361Z" }, + { url = "https://files.pythonhosted.org/packages/51/4d/b6d34db183133b83761b9199a82d31557cdbb70a380d8c3b3438e11882a3/mypy-2.1.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c90345fc182dc363b891350457ec69c35140858538f38b4540845afcc32b1aef", size = 15020937, upload-time = "2026-05-11T18:34:59.618Z" }, + { url = "https://files.pythonhosted.org/packages/ff/d7/f08360c691d758acb02f45022c34d98b92892f4ea756644e1000d4b9f3d8/mypy-2.1.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:b84802e7b5a6daf1f5e15bc9fcd7ddae77be13981ffab037f1c67bb84d67d135", size = 15253371, upload-time = "2026-05-11T18:36:41.081Z" }, + { url = "https://files.pythonhosted.org/packages/67/1b/09460a13719530a19bce27bd3bc8449e83569dd2ba7faf51c9c3c30c0b61/mypy-2.1.0-cp314-cp314-win_amd64.whl", hash = "sha256:022c771234936ceac541ebaf836fe9e2abeb3f5e09aff21588fe543ff006fe21", size = 11326429, upload-time = "2026-05-11T18:34:13.526Z" }, + { url = "https://files.pythonhosted.org/packages/40/62/75dbf0f82f7b6680340efc614af29dd0b3c17b8a4f1cd09b8bd2fd6bc814/mypy-2.1.0-cp314-cp314-win_arm64.whl", hash = "sha256:498207db725cec88829a6a5c2fc771205fd043719ef98bc49aba8fb9fc4e6d57", size = 10218799, upload-time = "2026-05-11T18:32:23.491Z" }, + { url = "https://files.pythonhosted.org/packages/b2/66/caca04ed7d972fb6eb6dd1ccd6df1de5c38fae8c5b3dc1c4e8e0d85ee6b9/mypy-2.1.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:7d5e5cad0efeba72b93cd17490cc0d69c5ac9ca132994fe3fb0314808aeeb83e", size = 15923458, upload-time = "2026-05-11T18:35:28.64Z" }, + { url = "https://files.pythonhosted.org/packages/ed/52/2d90cbe49d014b13ed7ff337930c30bad35893fe38a1e4641e756bb62191/mypy-2.1.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ff715050c127d724fd260a2e666e7747fdd83511c0c47d449d98238970aef780", size = 14757697, upload-time = "2026-05-11T18:36:14.208Z" }, + { url = "https://files.pythonhosted.org/packages/ac/37/d98f4a14e081b238992d0ed96b6d39c7cc0148c9699eb71eaa68629665ea/mypy-2.1.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:82208da9e09414d520e912d3e462d454854bed0810b71540bb016dcbca7308fd", size = 15405638, upload-time = "2026-05-11T18:33:48.249Z" }, + { url = "https://files.pythonhosted.org/packages/a3/c2/15c46613b24a84fad2aea1248bf9619b99c2767ae9071fe224c179a0b7d4/mypy-2.1.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e79ebc1b904b84f0310dff7469655a9c36c7a68bddb37bdd42b67a332df61d08", size = 16215852, upload-time = "2026-05-11T18:32:50.296Z" }, + { url = "https://files.pythonhosted.org/packages/5c/90/9c16a57f482c76d25f6379762b56bbf65c711d8158cf271fb2802cfb0640/mypy-2.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:e583edc957cfb0deb142079162ae826f58449b116c1d442f2d91c69d9fced081", size = 16452695, upload-time = "2026-05-11T18:33:38.182Z" }, + { url = "https://files.pythonhosted.org/packages/0f/4c/215a4eeb63cacc5f17f516691ea7285d11e249802b942476bff15922a314/mypy-2.1.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b33b6cd332695bba180d55e717a79d3038e479a2c49cc5eb3d53603409b9a5d7", size = 12866622, upload-time = "2026-05-11T18:34:39.945Z" }, + { url = "https://files.pythonhosted.org/packages/4b/50/1043e1db5f455ffe4c9ab22747cd8ca2bc492b1e4f4e21b130a44ee2b217/mypy-2.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:4f910fe825376a7b66ef7ca8c98e5a149e8cd64c19ae71d84047a74ee060d4e6", size = 10610798, upload-time = "2026-05-11T18:36:31.444Z" }, + { url = "https://files.pythonhosted.org/packages/0d/2a/13ca1f292f6db1b98ff495ef3467736b331621c5917cad984b7043e7348d/mypy-2.1.0-py3-none-any.whl", hash = "sha256:a663814603a5c563fb87a4f96fb473eeb30d1f5a4885afcf44f9db000a366289", size = 2693302, upload-time = "2026-05-11T18:31:29.246Z" }, +] + +[[package]] +name = "mypy-extensions" +version = "1.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a2/6e/371856a3fb9d31ca8dac321cda606860fa4548858c0cc45d9d1d4ca2628b/mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558", size = 6343, upload-time = "2025-04-22T14:54:24.164Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" }, +] + [[package]] name = "nltk" version = "3.9.4" @@ -536,11 +609,20 @@ wheels = [ [[package]] name = "packaging" -version = "26.1" +version = "26.2" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/df/de/0d2b39fb4af88a0258f3bac87dfcbb48e73fbdea4a2ed0e2213f9a4c2f9a/packaging-26.1.tar.gz", hash = "sha256:f042152b681c4bfac5cae2742a55e103d27ab2ec0f3d88037136b6bfe7c9c5de", size = 215519, upload-time = "2026-04-14T21:12:49.362Z" } +sdist = { url = "https://files.pythonhosted.org/packages/d7/f1/e7a6dd94a8d4a5626c03e4e99c87f241ba9e350cd9e6d75123f992427270/packaging-26.2.tar.gz", hash = "sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661", size = 228134, upload-time = "2026-04-24T20:15:23.917Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/7a/c2/920ef838e2f0028c8262f16101ec09ebd5969864e5a64c4c05fad0617c56/packaging-26.1-py3-none-any.whl", hash = "sha256:5d9c0669c6285e491e0ced2eee587eaf67b670d94a19e94e3984a481aba6802f", size = 95831, upload-time = "2026-04-14T21:12:47.56Z" }, + { url = "https://files.pythonhosted.org/packages/df/b2/87e62e8c3e2f4b32e5fe99e0b86d576da1312593b39f47d8ceef365e95ed/packaging-26.2-py3-none-any.whl", hash = "sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e", size = 100195, upload-time = "2026-04-24T20:15:22.081Z" }, +] + +[[package]] +name = "pathspec" +version = "1.1.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz", hash = "sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a", size = 135180, upload-time = "2026-04-27T01:46:08.907Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" }, ] [[package]] @@ -593,7 +675,7 @@ wheels = [ [[package]] name = "pydantic" -version = "2.13.2" +version = "2.13.4" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "annotated-types" }, @@ -601,50 +683,50 @@ dependencies = [ { name = "typing-extensions" }, { name = "typing-inspection" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/09/e5/06d23afac9973109d1e3c8ad38e1547a12e860610e327c05ee686827dc37/pydantic-2.13.2.tar.gz", hash = "sha256:b418196607e61081c3226dcd4f0672f2a194828abb9109e9cfb84026564df2d1", size = 843836, upload-time = "2026-04-17T09:31:59.636Z" } +sdist = { url = "https://files.pythonhosted.org/packages/18/a5/b60d21ac674192f8ab0ba4e9fd860690f9b4a6e51ca5df118733b487d8d6/pydantic-2.13.4.tar.gz", hash = "sha256:c40756b57adaa8b1efeeced5c196f3f3b7c435f90e84ea7f443901bec8099ef6", size = 844775, upload-time = "2026-05-06T13:43:05.343Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/77/ca/b45c378e6e8d0b90577288b533e04e95b7afd61bb1d51b6c263176435489/pydantic-2.13.2-py3-none-any.whl", hash = "sha256:a525087f4c03d7e7456a3de89b64cd693d2229933bb1068b9af6befd5563694e", size = 471947, upload-time = "2026-04-17T09:31:57.541Z" }, + { url = "https://files.pythonhosted.org/packages/fd/7b/122376b1fd3c62c1ed9dc80c931ace4844b3c55407b6fb2d199377c9736f/pydantic-2.13.4-py3-none-any.whl", hash = "sha256:45a282cde31d808236fd7ea9d919b128653c8b38b393d1c4ab335c62924d9aba", size = 472262, upload-time = "2026-05-06T13:43:02.641Z" }, ] [[package]] name = "pydantic-core" -version = "2.46.2" +version = "2.46.4" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/43/bb/4742f05b739b2478459bb16fa8470549518c802e06ddcf3f106c5081315e/pydantic_core-2.46.2.tar.gz", hash = "sha256:37bb079f9ee3f1a519392b73fda2a96379b31f2013c6b467fe693e7f2987f596", size = 471269, upload-time = "2026-04-17T09:10:07.017Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d0/96/a50ccb6b539ae780f73cea74905468777680e30c6c3bdf714b9d4c116ea0/pydantic_core-2.46.2-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:4f59b45f3ef8650c0c736a57f59031d47ed9df4c0a64e83796849d7d14863a2d", size = 2097111, upload-time = "2026-04-17T09:10:49.617Z" }, - { url = "https://files.pythonhosted.org/packages/34/5f/fdead7b3afa822ab6e5a18ee0ecffd54937de1877c01ed13a342e0fb3f07/pydantic_core-2.46.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:3a075a29ebef752784a91532a1a85be6b234ccffec0a9d7978a92696387c3da6", size = 1951904, upload-time = "2026-04-17T09:12:32.062Z" }, - { url = "https://files.pythonhosted.org/packages/95/e0/1c5d547e550cdab1bec737492aa08865337af6fe7fc9b96f7f45f17d9519/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0d12d786e30c04a9d307c5d7080bf720d9bac7f1668191d8e37633a9562749e2", size = 1978667, upload-time = "2026-04-17T09:11:35.589Z" }, - { url = "https://files.pythonhosted.org/packages/0e/cb/665ce629e218c8228302cb94beff4f6531082a2c87d3ecc3d5e63a26f392/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0d5e6d6343b0b5dcacb3503b5de90022968da8ed0ab9ab39d3eda71c20cbf84e", size = 2046721, upload-time = "2026-04-17T09:11:47.725Z" }, - { url = "https://files.pythonhosted.org/packages/77/e9/6cb2cf60f54c1472bbdfce19d957553b43dbba79d1d7b2930a195c594785/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:233eebac0999b6b9ba76eb56f3ec8fce13164aa16b6d2225a36a79e0f95b5973", size = 2228483, upload-time = "2026-04-17T09:12:08.837Z" }, - { url = "https://files.pythonhosted.org/packages/0d/2a/93e018dd5571f781ebaeda8c0cf65398489d5bee9b1f484df0b6149b43b9/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9cc0eee720dd2f14f3b7c349469402b99ad81a174ab49d3533974529e9d93992", size = 2294663, upload-time = "2026-04-17T09:12:52.053Z" }, - { url = "https://files.pythonhosted.org/packages/5e/4f/49e57ca55c770c93d9bb046666a54949b42e3c9099a0c5fe94557873fe30/pydantic_core-2.46.2-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83ee76bf2c9910513dbc19e7d82367131fa7508dedd6186a462393071cc11059", size = 2098742, upload-time = "2026-04-17T09:13:45.472Z" }, - { url = "https://files.pythonhosted.org/packages/c6/b0/6e46b5cd3332af665f794b8cdeea206618a8630bd9e7bcc36864518fce81/pydantic_core-2.46.2-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:d61db38eb4ee5192f0c261b7f2d38e420b554df8912245e3546aee5c45e2fd78", size = 2125922, upload-time = "2026-04-17T09:12:54.304Z" }, - { url = "https://files.pythonhosted.org/packages/06/d1/40850c81585be443a2abfdf7f795f8fae831baf8e2f9b2133c8246ac671c/pydantic_core-2.46.2-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8f09a713d17bcd55da8ab02ebd9110c5246a49c44182af213b5212800af8bc83", size = 2183000, upload-time = "2026-04-17T09:10:59.027Z" }, - { url = "https://files.pythonhosted.org/packages/04/af/8493d7dfa03ebb7866909e577c6aa65ea0de7377b86023cc51d0c8e11db3/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:30cacc5fb696e64b8ef6fd31d9549d394dd7d52760db072eecb98e37e3af1677", size = 2180335, upload-time = "2026-04-17T09:12:57.01Z" }, - { url = "https://files.pythonhosted.org/packages/72/5b/1f6a344c4ffdf284da41c6067b82d5ebcbd11ce1b515ae4b662d4adb6f61/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:7ccfb105fcfe91a22bbb5563ad3dc124bc1aa75bfd2e53a780ab05f78cdf6108", size = 2330002, upload-time = "2026-04-17T09:12:02.958Z" }, - { url = "https://files.pythonhosted.org/packages/25/ff/9a694126c12d6d2f48a0cafa6f8eef88ef0d8825600e18d03ff2e896c3b2/pydantic_core-2.46.2-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:13ffef637dc8370c249e5b26bd18e9a80a4fca3d809618c44e18ec834a7ca7a8", size = 2359920, upload-time = "2026-04-17T09:10:27.764Z" }, - { url = "https://files.pythonhosted.org/packages/51/c8/3a35c763d68a9cb2675eb10ef242cf66c5d4701b28ae12e688d67d2c180e/pydantic_core-2.46.2-cp314-cp314-win32.whl", hash = "sha256:1b0ab6d756ca2704a938e6c31b53f290c2f9c10d3914235410302a149de1a83e", size = 1953701, upload-time = "2026-04-17T09:13:30.021Z" }, - { url = "https://files.pythonhosted.org/packages/1a/6a/f2726a780365f7dfd89d62036f984f7acb99978c60c5e1fa7c0cb898ed11/pydantic_core-2.46.2-cp314-cp314-win_amd64.whl", hash = "sha256:99ebade8c9ada4df975372d8dd25883daa0e379a05f1cd0c99aa0c04368d01a6", size = 2071867, upload-time = "2026-04-17T09:10:39.205Z" }, - { url = "https://files.pythonhosted.org/packages/e1/79/76baacb9feba3d7c399b245ca1a29c74ea0db04ea693811374827eec2290/pydantic_core-2.46.2-cp314-cp314-win_arm64.whl", hash = "sha256:de87422197cf7f83db91d89c86a21660d749b3cd76cd8a45d115b8e675670f02", size = 2017252, upload-time = "2026-04-17T09:10:26.175Z" }, - { url = "https://files.pythonhosted.org/packages/f1/3b/77c26938f817668d9ad9bab1a905cb23f11d9a3d4bf724d429b3e55a8eaf/pydantic_core-2.46.2-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:236f22b4a206b5b61db955396b7cf9e2e1ff77f372efe9570128ccfcd6a525eb", size = 2094545, upload-time = "2026-04-17T09:12:19.339Z" }, - { url = "https://files.pythonhosted.org/packages/fe/de/42c13f590e3c260966aa49bcdb1674774f975467c49abd51191e502bea28/pydantic_core-2.46.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c2012f64d2cd7cca50f49f22445aa5a88691ac2b4498ee0a9a977f8ca4f7289f", size = 1933953, upload-time = "2026-04-17T09:09:55.889Z" }, - { url = "https://files.pythonhosted.org/packages/4e/84/ebe3ebb3e2d8db656937cfa6f97f544cb7132f2307a4a7dfdcd0ea102a12/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d07d6c63106d3a9c9a333e2636f9c82c703b1a9e3b079299e58747964e4fdb72", size = 1974435, upload-time = "2026-04-17T09:10:12.371Z" }, - { url = "https://files.pythonhosted.org/packages/b9/15/0bf51ca6709477cd4ef86148b6d7844f3308f029eac361dd0383f1e17b1a/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c326a2b4b85e959d9a1fc3a11f32f84611b6ec07c053e1828a860edf8d068208", size = 2031113, upload-time = "2026-04-17T09:10:00.752Z" }, - { url = "https://files.pythonhosted.org/packages/02/ae/b7b5af9b79db036d9e61a44c481c17a213dc8fc4b8b71fe6875a72fc778b/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ac8a65e798f2462552c00d2e013d532c94d646729dda98458beaf51f9ec7b120", size = 2236325, upload-time = "2026-04-17T09:10:33.227Z" }, - { url = "https://files.pythonhosted.org/packages/a6/ae/ecef7477b5a03d4a499708f7e75d2836452ebb70b776c2d64612b334f57a/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5a3c2bc1cc8164bedbc160b7bb1e8cc1e8b9c27f69ae4f9ae2b976cdae02b2dd", size = 2278135, upload-time = "2026-04-17T09:10:23.287Z" }, - { url = "https://files.pythonhosted.org/packages/db/e4/2f9d82faa47af6c39fc3f120145fd915971e1e0cb6b55b494fad9fdf8275/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e69aa5e10b7e8b1bb4a6888650fd12fcbf11d396ca11d4a44de1450875702830", size = 2109071, upload-time = "2026-04-17T09:11:06.149Z" }, - { url = "https://files.pythonhosted.org/packages/f1/9c/677cf10873fbd0b116575ab7b97c90482b21564f8a8040beb18edef7a577/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:4e6df5c3301e65fb42bc5338bf9a1027a02b0a31dc7f54c33775229af474daf0", size = 2106028, upload-time = "2026-04-17T09:10:51.525Z" }, - { url = "https://files.pythonhosted.org/packages/d6/53/6a06183544daba51c059123a2064a99039df25f115a06bdb26f2ea177038/pydantic_core-2.46.2-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2c2f6e32548ac8d559b47944effcf8ae4d81c161f6b6c885edc53bc08b8f192d", size = 2164816, upload-time = "2026-04-17T09:11:56.187Z" }, - { url = "https://files.pythonhosted.org/packages/57/6f/10fcdd9e3eca66fc828eef0f6f5850f2dd3bca2c59e6e041fb8bc3da39be/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:b089a81c58e6ea0485562bbbbbca4f65c0549521606d5ef27fba217aac9b665a", size = 2166130, upload-time = "2026-04-17T09:10:03.804Z" }, - { url = "https://files.pythonhosted.org/packages/29/83/92d3fd0e0156cad2e3cb5c26de73794af78ac9fa0c22ab666e566dd67061/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:7f700a6d6f64112ae9193709b84303bbab84424ad4b47d0253301aabce9dfc70", size = 2316605, upload-time = "2026-04-17T09:12:45.249Z" }, - { url = "https://files.pythonhosted.org/packages/97/f1/facffdb970981068219582e499b8d0871ed163ffcc6b347de5c412669e4c/pydantic_core-2.46.2-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:67db6814beaa5fefe91101ec7eb9efda613795767be96f7cf58b1ca8c9ca9972", size = 2358385, upload-time = "2026-04-17T09:09:54.657Z" }, - { url = "https://files.pythonhosted.org/packages/8b/a1/b8160b2f22b2199467bc68581a4ed380643c16b348a27d6165c6c242d694/pydantic_core-2.46.2-cp314-cp314t-win32.whl", hash = "sha256:32fbc7447be8e3be99bf7869f7066308f16be55b61f9882c2cefc7931f5c7664", size = 1942373, upload-time = "2026-04-17T09:12:59.594Z" }, - { url = "https://files.pythonhosted.org/packages/0d/90/db89acabe5b150e11d1b59fe3d947dda2ef6abbfef5c82f056ff63802f5d/pydantic_core-2.46.2-cp314-cp314t-win_amd64.whl", hash = "sha256:b317a2b97019c0b95ce99f4f901ae383f40132da6706cdf1731066a73394c25c", size = 2052078, upload-time = "2026-04-17T09:10:19.96Z" }, - { url = "https://files.pythonhosted.org/packages/97/32/e19b83ceb07a3f1bb21798407790bbc9a31740158fd132b94139cb84e16c/pydantic_core-2.46.2-cp314-cp314t-win_arm64.whl", hash = "sha256:7dcb9d40930dfad7ab6b20bcc6ca9d2b030b0f347a0cd9909b54bd53ead521b1", size = 2016941, upload-time = "2026-04-17T09:12:34.447Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/9d/56/921726b776ace8d8f5db44c4ef961006580d91dc52b803c489fafd1aa249/pydantic_core-2.46.4.tar.gz", hash = "sha256:62f875393d7f270851f20523dd2e29f082bcc82292d66db2b64ea71f64b6e1c1", size = 471464, upload-time = "2026-05-06T13:37:06.98Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/74/228a26ddad29c6672b805d9fd78e8d251cd04004fa7eed0e622096cd0250/pydantic_core-2.46.4-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:428e04521a40150c85216fc8b85e8d39fece235a9cf5e383761238c7fa9b96fb", size = 2102079, upload-time = "2026-05-06T13:38:41.019Z" }, + { url = "https://files.pythonhosted.org/packages/ad/1f/8970b150a4b4365623ae00fc88603491f763c627311ae8031e3111356d6e/pydantic_core-2.46.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:23ace664830ee0bfe014a0c7bc248b1f7f25ed7ad103852c317624a1083af462", size = 1952179, upload-time = "2026-05-06T13:36:59.812Z" }, + { url = "https://files.pythonhosted.org/packages/95/30/5211a831ae054928054b2f79731661087a2bc5c01e825c672b3a4a8f1b3e/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce5c1d2a8b27468f433ca974829c44060b8097eedc39933e3c206a90ee49c4a9", size = 1978926, upload-time = "2026-05-06T13:37:39.933Z" }, + { url = "https://files.pythonhosted.org/packages/57/e9/689668733b1eb67adeef047db3c2e8788fcf65a7fd9c9e2b46b7744fe245/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7283d57845ecf5a163403eb0702dfc220cc4fbdd18919cb5ccea4f95ee1cdab4", size = 2046785, upload-time = "2026-05-06T13:38:01.995Z" }, + { url = "https://files.pythonhosted.org/packages/60/d9/6715260422ff50a2109878fd24d948a6c3446bb2664f34ee78cd972b3acd/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8daafc69c93ee8a0204506a3b6b30f586ef54028f52aeeeb5c4cfc5184fd5914", size = 2228733, upload-time = "2026-05-06T13:40:50.371Z" }, + { url = "https://files.pythonhosted.org/packages/18/ae/fdb2f64316afca925640f8e70bb1a564b0ec2721c1389e25b8eb4bf9a299/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cd2213145bcc2ba85884d0ac63d222fece9209678f77b9b4d76f054c561adb28", size = 2307534, upload-time = "2026-05-06T13:37:21.531Z" }, + { url = "https://files.pythonhosted.org/packages/89/1d/8eff589b45bb8190a9d12c49cfad0f176a5cbd1534908a6b5125e2886239/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7a5f930472650a82629163023e630d160863fce524c616f4e5186e5de9d9a49b", size = 2099732, upload-time = "2026-05-06T13:39:31.942Z" }, + { url = "https://files.pythonhosted.org/packages/06/d5/ee5a3366637fee41dee51a1fc91562dcf12ddbc68fda34e6b253da2324bb/pydantic_core-2.46.4-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:c1b3f518abeca3aa13c712fd202306e145abf59a18b094a6bafb2d2bbf59192c", size = 2129627, upload-time = "2026-05-06T13:37:25.033Z" }, + { url = "https://files.pythonhosted.org/packages/94/33/2414be571d2c6a6c4d08be21f9292b6d3fdb08949a97b6dfe985017821db/pydantic_core-2.46.4-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1a7dd0b3ee80d90150e3495a3a13ac34dbcbfd4f012996a6a1d8900e91b5c0fb", size = 2179141, upload-time = "2026-05-06T13:37:14.046Z" }, + { url = "https://files.pythonhosted.org/packages/7b/79/7daa95be995be0eecc4cf75064cb33f9bbbfe3fe0158caf2f0d4a996a5c7/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:3fb702cd90b0446a3a1c5e470bfa0dd23c0233b676a9099ddcc964fa6ca13898", size = 2184325, upload-time = "2026-05-06T13:36:53.615Z" }, + { url = "https://files.pythonhosted.org/packages/9f/cb/d0a382f5c0de8a222dc61c65348e0ce831b1f68e0a018450d31c2cace3a5/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:b8458003118a712e66286df6a707db01c52c0f52f7db8e4a38f0da1d3b94fc4e", size = 2323990, upload-time = "2026-05-06T13:40:29.971Z" }, + { url = "https://files.pythonhosted.org/packages/05/db/d9ba624cc4a5aced1598e88c04fdbd8310c8a69b9d38b9a3d39ce3a61ed7/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:372429a130e469c9cd698925ce5fc50940b7a1336b0d82038e63d5bbc4edc519", size = 2369978, upload-time = "2026-05-06T13:37:23.027Z" }, + { url = "https://files.pythonhosted.org/packages/f2/20/d15df15ba918c423461905802bfd2981c3af0bfa0e40d05e13edbfa48bc3/pydantic_core-2.46.4-cp314-cp314-win32.whl", hash = "sha256:85bb3611ff1802f3ee7fdd7dbff26b56f343fb432d57a4728fdd49b6ef35e2f4", size = 1966354, upload-time = "2026-05-06T13:38:03.499Z" }, + { url = "https://files.pythonhosted.org/packages/fc/b6/6b8de4c0a7d7ab3004c439c80c5c1e0a3e8d78bbae19379b01960383d9e5/pydantic_core-2.46.4-cp314-cp314-win_amd64.whl", hash = "sha256:811ff8e9c313ab425368bcbb36e5c4ebd7108c2bbf4e4089cfbb0b01eff63fac", size = 2072238, upload-time = "2026-05-06T13:39:40.807Z" }, + { url = "https://files.pythonhosted.org/packages/32/36/51eb763beec1f4cf59b1db243a7dcc39cbb41230f050a09b9d69faaf0a48/pydantic_core-2.46.4-cp314-cp314-win_arm64.whl", hash = "sha256:bfec22eab3c8cc2ceec0248aec886624116dc079afa027ecc8ad4a7e62010f8a", size = 2018251, upload-time = "2026-05-06T13:37:26.72Z" }, + { url = "https://files.pythonhosted.org/packages/e8/91/855af51d625b23aa987116a19e231d2aaef9c4a415273ddc189b79a45fee/pydantic_core-2.46.4-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:af8244b2bef6aaad6d92cda81372de7f8c8d36c9f0c3ea36e827c60e7d9467a0", size = 2099593, upload-time = "2026-05-06T13:39:47.682Z" }, + { url = "https://files.pythonhosted.org/packages/fb/1b/8784a54c65edb5f49f0a14d6977cf1b209bba85a4c77445b255c2de58ab3/pydantic_core-2.46.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5a4330cdbc57162e4b3aa303f588ba752257694c9c9be3e7ebb11b4aca659b5d", size = 1935226, upload-time = "2026-05-06T13:40:40.428Z" }, + { url = "https://files.pythonhosted.org/packages/e8/e7/1955d28d1afc56dd4b3ad7cc0cf39df1b9852964cf16e5d13912756d6d6b/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:29c61fc04a3d840155ff08e475a04809278972fe6aef51e2720554e96367e34b", size = 1974605, upload-time = "2026-05-06T13:37:32.029Z" }, + { url = "https://files.pythonhosted.org/packages/93/e2/3fedbf0ba7a22850e6e9fd78117f1c0f10f950182344d8a6c535d468fdd8/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c50f2528cf200c5eed56faf3f4e22fcd5f38c157a8b78576e6ba3168ec35f000", size = 2030777, upload-time = "2026-05-06T13:38:55.239Z" }, + { url = "https://files.pythonhosted.org/packages/f8/61/46be275fcaaba0b4f5b9669dd852267ce1ff616592dccf7a7845588df091/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:0cbe8b01f948de4286c74cdd6c667aceb38f5c1e26f0693b3983d9d74887c65e", size = 2236641, upload-time = "2026-05-06T13:37:08.096Z" }, + { url = "https://files.pythonhosted.org/packages/60/db/12e93e46a8bac9988be3c016860f83293daea8c716c029c9ace279036f2f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:617d7e2ca7dcb8c5cf6bcb8c59b8832c94b36196bbf1cbd1bfb56ed341905edd", size = 2286404, upload-time = "2026-05-06T13:40:20.221Z" }, + { url = "https://files.pythonhosted.org/packages/e2/4a/4d8b19008f38d31c53b8219cfedc2e3d5de5fe99d90076b7e767de29274f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7027560ee92211647d0d34e3f7cd6f50da56399d26a9c8ad0da286d3869a53f3", size = 2109219, upload-time = "2026-05-06T13:38:12.153Z" }, + { url = "https://files.pythonhosted.org/packages/88/70/3cbc40978fefb7bb09c6708d40d4ad1a5d70fd7213c3d17f971de868ec1f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:f99626688942fb746e545232e7726926f3be91b5975f8b55327665fafda991c7", size = 2110594, upload-time = "2026-05-06T13:40:02.971Z" }, + { url = "https://files.pythonhosted.org/packages/9d/20/b8d36736216e29491125531685b2f9e61aa5b4b2599893f8268551da3338/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fc3e9034a63de20e15e8ade85358bc6efc614008cab72898b4b4952bea0509ff", size = 2159542, upload-time = "2026-05-06T13:39:27.506Z" }, + { url = "https://files.pythonhosted.org/packages/1d/a2/367df868eb584dacf6bf82a389272406d7178e301c4ac82545ab98bc2dd9/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:97e7cf2be5c77b7d1a9713a05605d49460d02c6078d38d8bef3cbe323c548424", size = 2168146, upload-time = "2026-05-06T13:38:31.93Z" }, + { url = "https://files.pythonhosted.org/packages/c1/b8/4460f77f7e201893f649a29ab355dddd3beee8a97bcb1a320db414f9a06e/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:3bf92c5d0e00fefaab325a4d27828fe6b6e2a21848686b5b60d2d9eeb09d76c6", size = 2306309, upload-time = "2026-05-06T13:37:44.717Z" }, + { url = "https://files.pythonhosted.org/packages/64/c4/be2639293acd87dc8ddbcec41a73cee9b2ebf996fe6d892a1a74e88ad3f7/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:3ecbc122d18468d06ca279dc26a8c2e2d5acb10943bb35e36ae92096dc3b5565", size = 2369736, upload-time = "2026-05-06T13:37:05.645Z" }, + { url = "https://files.pythonhosted.org/packages/30/a6/9f9f380dbb301f67023bf8f707aaa75daadf84f7152d95c410fd7e81d994/pydantic_core-2.46.4-cp314-cp314t-win32.whl", hash = "sha256:e846ae7835bf0703ae43f534ab79a867146dadd59dc9ca5c8b53d5c8f7c9ef02", size = 1955575, upload-time = "2026-05-06T13:38:51.116Z" }, + { url = "https://files.pythonhosted.org/packages/40/1f/f1eb9eb350e795d1af8586289746f5c5677d16043040d63710e22abc43c9/pydantic_core-2.46.4-cp314-cp314t-win_amd64.whl", hash = "sha256:2108ba5c1c1eca18030634489dc544844144ee36357f2f9f780b93e7ddbb44b5", size = 2051624, upload-time = "2026-05-06T13:38:21.672Z" }, + { url = "https://files.pythonhosted.org/packages/f6/d2/42dd53d0a85c27606f316d3aa5d2869c4e8470a5ed6dec30e4a1abe19192/pydantic_core-2.46.4-cp314-cp314t-win_arm64.whl", hash = "sha256:4fcbe087dbc2068af7eda3aa87634eba216dbda64d1ae73c8684b621d33f6596", size = 2017325, upload-time = "2026-05-06T13:40:52.723Z" }, ] [[package]] @@ -658,20 +740,20 @@ wheels = [ [[package]] name = "pyright" -version = "1.1.408" +version = "1.1.411" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "nodeenv" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/74/b2/5db700e52554b8f025faa9c3c624c59f1f6c8841ba81ab97641b54322f16/pyright-1.1.408.tar.gz", hash = "sha256:f28f2321f96852fa50b5829ea492f6adb0e6954568d1caa3f3af3a5f555eb684", size = 4400578, upload-time = "2026-01-08T08:07:38.795Z" } +sdist = { url = "https://files.pythonhosted.org/packages/7e/ab/265f7dc69d28113ebba19092e57b075f41543b2ed048429c5f56e2b88eac/pyright-1.1.411.tar.gz", hash = "sha256:d885a0551f2e763b089a02702174e7f4ba77548cddabc972ab86d1f7f1b0f998", size = 4112861, upload-time = "2026-06-25T02:14:06.37Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/0c/82/a2c93e32800940d9573fb28c346772a14778b84ba7524e691b324620ab89/pyright-1.1.408-py3-none-any.whl", hash = "sha256:090b32865f4fdb1e0e6cd82bf5618480d48eecd2eb2e70f960982a3d9a4c17c1", size = 6399144, upload-time = "2026-01-08T08:07:37.082Z" }, + { url = "https://files.pythonhosted.org/packages/0a/49/385be530a6a5b78d1cbcd5c2e38debc8959a2fc6bdb716f4e581002979fc/pyright-1.1.411-py3-none-any.whl", hash = "sha256:dc7c72a8e2700c55baa127554040e067041ea53ccfd50bf96308cc4291c7d5d9", size = 6181526, upload-time = "2026-06-25T02:14:04.691Z" }, ] [[package]] name = "pytest" -version = "9.0.3" +version = "9.1.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, @@ -680,9 +762,9 @@ dependencies = [ { name = "pluggy" }, { name = "pygments" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" }, + { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" }, ] [[package]] @@ -754,6 +836,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5a/cc/06253936f4a7fa2e0f48dfe6d851d9c56df896a9ab09ac019d70b760619c/pytest_mock-3.15.1-py3-none-any.whl", hash = "sha256:0a25e2eb88fe5168d535041d09a4529a188176ae608a6d249ee65abc0949630d", size = 10095, upload-time = "2025-09-16T16:37:25.734Z" }, ] +[[package]] +name = "pytest-vcr" +version = "1.0.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pytest" }, + { name = "vcrpy" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/1a/60/104c619483c1a42775d3f8b27293f1ecfc0728014874d065e68cb9702d49/pytest-vcr-1.0.2.tar.gz", hash = "sha256:23ee51b75abbcc43d926272773aae4f39f93aceb75ed56852d0bf618f92e1896", size = 3810, upload-time = "2019-04-26T19:04:00.806Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9d/d3/ff520d11e6ee400602711d1ece8168dcfc5b6d8146fb7db4244a6ad6a9c3/pytest_vcr-1.0.2-py2.py3-none-any.whl", hash = "sha256:2f316e0539399bea0296e8b8401145c62b6f85e9066af7e57b6151481b0d6d9c", size = 4137, upload-time = "2019-04-26T19:03:57.034Z" }, +] + [[package]] name = "python-dateutil" version = "2.9.0.post0" @@ -794,57 +889,42 @@ wheels = [ [[package]] name = "regex" -version = "2026.4.4" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/cb/0e/3a246dbf05666918bd3664d9d787f84a9108f6f43cc953a077e4a7dfdb7e/regex-2026.4.4.tar.gz", hash = "sha256:e08270659717f6973523ce3afbafa53515c4dc5dcad637dc215b6fd50f689423", size = 416000, upload-time = "2026-04-03T20:56:28.155Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/f0/f5/ed97c2dc47b5fbd4b73c0d7d75f9ebc8eca139f2bbef476bba35f28c0a77/regex-2026.4.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:2da82d643fa698e5e5210e54af90181603d5853cf469f5eedf9bfc8f59b4b8c7", size = 490343, upload-time = "2026-04-03T20:55:15.241Z" }, - { url = "https://files.pythonhosted.org/packages/80/e9/de4828a7385ec166d673a5790ad06ac48cdaa98bc0960108dd4b9cc1aef7/regex-2026.4.4-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:54a1189ad9d9357760557c91103d5e421f0a2dabe68a5cdf9103d0dcf4e00752", size = 291909, upload-time = "2026-04-03T20:55:17.558Z" }, - { url = "https://files.pythonhosted.org/packages/b4/d6/5cfbfc97f3201a4d24b596a77957e092030dcc4205894bc035cedcfce62f/regex-2026.4.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:76d67d5afb1fe402d10a6403bae668d000441e2ab115191a804287d53b772951", size = 289692, upload-time = "2026-04-03T20:55:20.561Z" }, - { url = "https://files.pythonhosted.org/packages/8e/ac/f2212d9fd56fe897e36d0110ba30ba2d247bd6410c5bd98499c7e5a1e1f2/regex-2026.4.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e7cd3e4ee8d80447a83bbc9ab0c8459781fa77087f856c3e740d7763be0df27f", size = 796979, upload-time = "2026-04-03T20:55:22.56Z" }, - { url = "https://files.pythonhosted.org/packages/c9/e3/a016c12675fbac988a60c7e1c16e67823ff0bc016beb27bd7a001dbdabc6/regex-2026.4.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2e19e18c568d2866d8b6a6dfad823db86193503f90823a8f66689315ba28fbe8", size = 866744, upload-time = "2026-04-03T20:55:24.646Z" }, - { url = "https://files.pythonhosted.org/packages/af/a4/0b90ca4cf17adc3cb43de80ec71018c37c88ad64987e8d0d481a95ca60b5/regex-2026.4.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7698a6f38730fd1385d390d1ed07bb13dce39aa616aca6a6d89bea178464b9a4", size = 911613, upload-time = "2026-04-03T20:55:27.033Z" }, - { url = "https://files.pythonhosted.org/packages/8e/3b/2b3dac0b82d41ab43aa87c6ecde63d71189d03fe8854b8ca455a315edac3/regex-2026.4.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:173a66f3651cdb761018078e2d9487f4cf971232c990035ec0eb1cdc6bf929a9", size = 800551, upload-time = "2026-04-03T20:55:29.532Z" }, - { url = "https://files.pythonhosted.org/packages/25/fe/5365eb7aa0e753c4b5957815c321519ecab033c279c60e1b1ae2367fa810/regex-2026.4.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fa7922bbb2cc84fa062d37723f199d4c0cd200245ce269c05db82d904db66b83", size = 776911, upload-time = "2026-04-03T20:55:31.526Z" }, - { url = "https://files.pythonhosted.org/packages/aa/b3/7fb0072156bba065e3b778a7bc7b0a6328212be5dd6a86fd207e0c4f2dab/regex-2026.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:59f67cd0a0acaf0e564c20bbd7f767286f23e91e2572c5703bf3e56ea7557edb", size = 785751, upload-time = "2026-04-03T20:55:33.797Z" }, - { url = "https://files.pythonhosted.org/packages/02/1a/9f83677eb699273e56e858f7bd95acdbee376d42f59e8bfca2fd80d79df3/regex-2026.4.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:475e50f3f73f73614f7cba5524d6de49dee269df00272a1b85e3d19f6d498465", size = 860484, upload-time = "2026-04-03T20:55:35.745Z" }, - { url = "https://files.pythonhosted.org/packages/3b/7a/93937507b61cfcff8b4c5857f1b452852b09f741daa9acae15c971d8554e/regex-2026.4.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:a1c0c7d67b64d85ac2e1879923bad2f08a08f3004055f2f406ef73c850114bd4", size = 765939, upload-time = "2026-04-03T20:55:37.972Z" }, - { url = "https://files.pythonhosted.org/packages/86/ea/81a7f968a351c6552b1670ead861e2a385be730ee28402233020c67f9e0f/regex-2026.4.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:1371c2ccbb744d66ee63631cc9ca12aa233d5749972626b68fe1a649dd98e566", size = 851417, upload-time = "2026-04-03T20:55:39.92Z" }, - { url = "https://files.pythonhosted.org/packages/4c/7e/323c18ce4b5b8f44517a36342961a0306e931e499febbd876bb149d900f0/regex-2026.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:59968142787042db793348a3f5b918cf24ced1f23247328530e063f89c128a95", size = 789056, upload-time = "2026-04-03T20:55:42.303Z" }, - { url = "https://files.pythonhosted.org/packages/c0/af/e7510f9b11b1913b0cd44eddb784b2d650b2af6515bfce4cffcc5bfd1d38/regex-2026.4.4-cp314-cp314-win32.whl", hash = "sha256:59efe72d37fd5a91e373e5146f187f921f365f4abc1249a5ab446a60f30dd5f8", size = 272130, upload-time = "2026-04-03T20:55:44.995Z" }, - { url = "https://files.pythonhosted.org/packages/9a/51/57dae534c915e2d3a21490e88836fa2ae79dde3b66255ecc0c0a155d2c10/regex-2026.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:e0aab3ff447845049d676827d2ff714aab4f73f340e155b7de7458cf53baa5a4", size = 280992, upload-time = "2026-04-03T20:55:47.316Z" }, - { url = "https://files.pythonhosted.org/packages/0a/5e/abaf9f4c3792e34edb1434f06717fae2b07888d85cb5cec29f9204931bf8/regex-2026.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:a7a5bb6aa0cf62208bb4fa079b0c756734f8ad0e333b425732e8609bd51ee22f", size = 273563, upload-time = "2026-04-03T20:55:49.273Z" }, - { url = "https://files.pythonhosted.org/packages/ff/06/35da85f9f217b9538b99cbb170738993bcc3b23784322decb77619f11502/regex-2026.4.4-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:97850d0638391bdc7d35dc1c1039974dcb921eaafa8cc935ae4d7f272b1d60b3", size = 494191, upload-time = "2026-04-03T20:55:51.258Z" }, - { url = "https://files.pythonhosted.org/packages/54/5b/1bc35f479eef8285c4baf88d8c002023efdeebb7b44a8735b36195486ae7/regex-2026.4.4-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:ee7337f88f2a580679f7bbfe69dc86c043954f9f9c541012f49abc554a962f2e", size = 293877, upload-time = "2026-04-03T20:55:53.214Z" }, - { url = "https://files.pythonhosted.org/packages/39/5b/f53b9ad17480b3ddd14c90da04bfb55ac6894b129e5dea87bcaf7d00e336/regex-2026.4.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7429f4e6192c11d659900c0648ba8776243bf396ab95558b8c51a345afeddde6", size = 292410, upload-time = "2026-04-03T20:55:55.736Z" }, - { url = "https://files.pythonhosted.org/packages/bb/56/52377f59f60a7c51aa4161eecf0b6032c20b461805aca051250da435ffc9/regex-2026.4.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc4f10fbd5dd13dcf4265b4cc07d69ca70280742870c97ae10093e3d66000359", size = 811831, upload-time = "2026-04-03T20:55:57.802Z" }, - { url = "https://files.pythonhosted.org/packages/dd/63/8026310bf066f702a9c361f83a8c9658f3fe4edb349f9c1e5d5273b7c40c/regex-2026.4.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a152560af4f9742b96f3827090f866eeec5becd4765c8e0d3473d9d280e76a5a", size = 871199, upload-time = "2026-04-03T20:56:00.333Z" }, - { url = "https://files.pythonhosted.org/packages/20/9f/a514bbb00a466dbb506d43f187a04047f7be1505f10a9a15615ead5080ee/regex-2026.4.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:54170b3e95339f415d54651f97df3bff7434a663912f9358237941bbf9143f55", size = 917649, upload-time = "2026-04-03T20:56:02.445Z" }, - { url = "https://files.pythonhosted.org/packages/cb/6b/8399f68dd41a2030218839b9b18360d79b86d22b9fab5ef477c7f23ca67c/regex-2026.4.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:07f190d65f5a72dcb9cf7106bfc3d21e7a49dd2879eda2207b683f32165e4d99", size = 816388, upload-time = "2026-04-03T20:56:04.595Z" }, - { url = "https://files.pythonhosted.org/packages/1e/9c/103963f47c24339a483b05edd568594c2be486188f688c0170fd504b2948/regex-2026.4.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9a2741ce5a29d3c84b0b94261ba630ab459a1b847a0d6beca7d62d188175c790", size = 785746, upload-time = "2026-04-03T20:56:07.13Z" }, - { url = "https://files.pythonhosted.org/packages/fa/ee/7f6054c0dec0cee3463c304405e4ff42e27cff05bf36fcb34be549ab17bd/regex-2026.4.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:b26c30df3a28fd9793113dac7385a4deb7294a06c0f760dd2b008bd49a9139bc", size = 801483, upload-time = "2026-04-03T20:56:09.365Z" }, - { url = "https://files.pythonhosted.org/packages/30/c2/51d3d941cf6070dc00c3338ecf138615fc3cce0421c3df6abe97a08af61a/regex-2026.4.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:421439d1bee44b19f4583ccf42670ca464ffb90e9fdc38d37f39d1ddd1e44f1f", size = 866331, upload-time = "2026-04-03T20:56:12.039Z" }, - { url = "https://files.pythonhosted.org/packages/16/e8/76d50dcc122ac33927d939f350eebcfe3dbcbda96913e03433fc36de5e63/regex-2026.4.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:b40379b53ecbc747fd9bdf4a0ea14eb8188ca1bd0f54f78893a39024b28f4863", size = 772673, upload-time = "2026-04-03T20:56:14.558Z" }, - { url = "https://files.pythonhosted.org/packages/a5/6e/5f6bf75e20ea6873d05ba4ec78378c375cbe08cdec571c83fbb01606e563/regex-2026.4.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:08c55c13d2eef54f73eeadc33146fb0baaa49e7335eb1aff6ae1324bf0ddbe4a", size = 857146, upload-time = "2026-04-03T20:56:16.663Z" }, - { url = "https://files.pythonhosted.org/packages/0b/33/3c76d9962949e487ebba353a18e89399f292287204ac8f2f4cfc3a51c233/regex-2026.4.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9776b85f510062f5a75ef112afe5f494ef1635607bf1cc220c1391e9ac2f5e81", size = 803463, upload-time = "2026-04-03T20:56:18.923Z" }, - { url = "https://files.pythonhosted.org/packages/19/eb/ef32dcd2cb69b69bc0c3e55205bce94a7def48d495358946bc42186dcccc/regex-2026.4.4-cp314-cp314t-win32.whl", hash = "sha256:385edaebde5db5be103577afc8699fea73a0e36a734ba24870be7ffa61119d74", size = 275709, upload-time = "2026-04-03T20:56:20.996Z" }, - { url = "https://files.pythonhosted.org/packages/a0/86/c291bf740945acbf35ed7dbebf8e2eea2f3f78041f6bd7cdab80cb274dc0/regex-2026.4.4-cp314-cp314t-win_amd64.whl", hash = "sha256:5d354b18839328927832e2fa5f7c95b7a3ccc39e7a681529e1685898e6436d45", size = 285622, upload-time = "2026-04-03T20:56:23.641Z" }, - { url = "https://files.pythonhosted.org/packages/d5/e7/ec846d560ae6a597115153c02ca6138a7877a1748b2072d9521c10a93e58/regex-2026.4.4-cp314-cp314t-win_arm64.whl", hash = "sha256:af0384cb01a33600c49505c27c6c57ab0b27bf84a74e28524c92ca897ebdac9d", size = 275773, upload-time = "2026-04-03T20:56:26.07Z" }, -] - -[[package]] -name = "requests" -version = "2.33.1" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "certifi" }, - { name = "charset-normalizer" }, - { name = "idna" }, - { name = "urllib3" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz", hash = "sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517", size = 134120, upload-time = "2026-03-30T16:09:15.531Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a", size = 64947, upload-time = "2026-03-30T16:09:13.83Z" }, +version = "2026.6.28" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f1/05/e4f219230e11e774a6c9987d2ab0d0c6b8573e13a17e143d0015bee710ef/regex-2026.6.28.tar.gz", hash = "sha256:3cb4b6c5cb3060cc31efdc1fbb27c25fb9b29044afd87e40601a1c4d9db54342", size = 416101, upload-time = "2026-06-28T19:56:55.302Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3b/fb/fad3b810a5bb1e09b9e5d6913fc6ba88cab738fdf283196827a3c59a4c10/regex-2026.6.28-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:f7c032b0c8a73739ff8ff1aaf30c281fa19c17bf7f1543256c8507390db7807c", size = 490407, upload-time = "2026-06-28T19:55:42.724Z" }, + { url = "https://files.pythonhosted.org/packages/d6/52/b8c79d12276d93e90e707e939b396034c04980caf1235312ef790f8e11fc/regex-2026.6.28-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:f6710f512c57b84f127a23d0f59560a03b64136eff419ae1be5ab557577fe5e3", size = 291988, upload-time = "2026-06-28T19:55:44.549Z" }, + { url = "https://files.pythonhosted.org/packages/23/d2/6a911f18279daa8d7bb8b20d771ddb6ef31fabd35f5921f9d3ba21640e80/regex-2026.6.28-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c0013958f427bd82509a186b9ff206d66cb8d60a81fc797a4c717afd18c5b0ba", size = 289704, upload-time = "2026-06-28T19:55:46.365Z" }, + { url = "https://files.pythonhosted.org/packages/fd/22/ad1955c47c669291a05804d53d7071cc0732dfdf166857be38003cedc2d1/regex-2026.6.28-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:94f06cdcd6421f8e194ad312ea608020381250df9b8a57661c1b57e9e5273878", size = 797017, upload-time = "2026-06-28T19:55:48.166Z" }, + { url = "https://files.pythonhosted.org/packages/e5/67/a83159ff8703ab4d0c2cf99e76ebf289b7b4a501623241d09f88f3614f80/regex-2026.6.28-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ec9689392f7494ff4e3f8e7e8522f9158f11023f337eaaf04a64542fc45bbf26", size = 866112, upload-time = "2026-06-28T19:55:51.047Z" }, + { url = "https://files.pythonhosted.org/packages/b9/09/7bff2d6dbbd77421b3274aa51db1c887381cbc5b6eda93598c3e882ea345/regex-2026.6.28-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:aa084684e6d2078bf6139e374d1fc2af5ddc1ac7122759a2db716d68169f6fd0", size = 911554, upload-time = "2026-06-28T19:55:53.707Z" }, + { url = "https://files.pythonhosted.org/packages/29/44/ae59c3826e7ba492e56795cdf74ea2a7b5b7c5ea116afb79ee4956a5dff1/regex-2026.6.28-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:40455e6840dc4e96a6fe50f4cedc957de2752c954d91e789812be55d49be199a", size = 800665, upload-time = "2026-06-28T19:55:55.875Z" }, + { url = "https://files.pythonhosted.org/packages/d6/19/6fd033d2ab00f35d445aaeaf3307c1e721424dcbfd48f6f65c857cb939cf/regex-2026.6.28-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:530b5c223b9ca5dd8370ac502e080aee0e4ded32be987c6564b425fb5523d581", size = 777243, upload-time = "2026-06-28T19:55:57.909Z" }, + { url = "https://files.pythonhosted.org/packages/4e/9d/99730f26df4938049ab1e652ca75e967b4c6739444e18d9707bfdb8af20c/regex-2026.6.28-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8e0ed273ecd1a89be84466c1749bfe58609cc2a32b5d5e05006c4625ba96411b", size = 785784, upload-time = "2026-06-28T19:56:00.072Z" }, + { url = "https://files.pythonhosted.org/packages/48/49/105cd57162f5fc5c04cc917a1388a060cf8427e5c14353cd9044660fbf4d/regex-2026.6.28-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:0ab0d5344311fc8e8667078942056c3b9c9b4a4b1cc99f2eb8a5af54554f4acc", size = 860914, upload-time = "2026-06-28T19:56:02.017Z" }, + { url = "https://files.pythonhosted.org/packages/a2/a5/788245a95b69018f58bff2f4fd27d007cacaea088cdb390979743f1b2571/regex-2026.6.28-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:eacb79625323d9f7e7925366b917f492b8356fad58f5dc4fa12ff8c21d8f4ca9", size = 765915, upload-time = "2026-06-28T19:56:05.021Z" }, + { url = "https://files.pythonhosted.org/packages/ca/01/292065a39a004b05e67a337b18213670a7cb919d6856ac2d7df7f1a10dbb/regex-2026.6.28-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:20f4d87702702aa1d572721e146f301660c50eef6fd6cb596e48a22b0ace17db", size = 851404, upload-time = "2026-06-28T19:56:07.251Z" }, + { url = "https://files.pythonhosted.org/packages/98/9e/a93d865db0e13483ae1a01d81e2ce16d4a7fe2f9b9fe4aac4cc08590b136/regex-2026.6.28-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:1e693940a3b9e6d6e4dc2a54ecaa74b74934f77af1ef95f518a74261ef7cc1bc", size = 789373, upload-time = "2026-06-28T19:56:09.894Z" }, + { url = "https://files.pythonhosted.org/packages/82/0c/38b1685ad4017d78efbc8fa7dbbf96d8113b53750c8aa2d3609defd46605/regex-2026.6.28-cp314-cp314-win32.whl", hash = "sha256:234a51e20ebc18ab83b2c0600cf28f2e884560a0e00f743878f0b7d8e7c4cf03", size = 272496, upload-time = "2026-06-28T19:56:11.83Z" }, + { url = "https://files.pythonhosted.org/packages/55/50/e19f261ff9ba9b50722a529e09b1743ecf65eb348be99d0fd2cd7fcede1c/regex-2026.6.28-cp314-cp314-win_amd64.whl", hash = "sha256:7b15c437bc4604f03ceb3f8d37eae2f8930e320e1bc556b259848c639d9eec1a", size = 280754, upload-time = "2026-06-28T19:56:13.758Z" }, + { url = "https://files.pythonhosted.org/packages/36/b8/c9e68f3a9e33be73f20990b2c065b144ff2d0aa242608a950d8c4f3b56e8/regex-2026.6.28-cp314-cp314-win_arm64.whl", hash = "sha256:c6e6f790d01380a74ad564f216c533b86504afb61bf66f2b2e11e7f1a3e287a7", size = 280979, upload-time = "2026-06-28T19:56:15.928Z" }, + { url = "https://files.pythonhosted.org/packages/03/e6/21c425a37880c650d007c4171c6a80325446d830d85f5fbf335e7205b1e7/regex-2026.6.28-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:3527a72adcbe9e3600f1553b497d397c1a371d227580d41d96c3c5964109b65c", size = 494282, upload-time = "2026-06-28T19:56:18.049Z" }, + { url = "https://files.pythonhosted.org/packages/07/50/6647a7ccf5ffff995ba955a0b7d766440f4e58ce1666549c8ee998f2b972/regex-2026.6.28-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:a644f6408692812f5ead82519eed680e08d5d546fddbd9f7d9514e3c73899aa5", size = 293977, upload-time = "2026-06-28T19:56:20.145Z" }, + { url = "https://files.pythonhosted.org/packages/8c/dc/a3e141a4eaf125e50f63105570c01fa477c06ac5259dcfa95e9b90760e84/regex-2026.6.28-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:8e2fae6bb883648346f84db270dc9aafc29d8e895f62b88a75ccc83b09519820", size = 292432, upload-time = "2026-06-28T19:56:22.345Z" }, + { url = "https://files.pythonhosted.org/packages/35/ee/2ac1a6b9f167f8ff69f5a789938cc103b60cff41b24a6990daced8b88e34/regex-2026.6.28-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:debe623e09cee97ef9404575e936c610aac9bb08358c5099aaef14644a6871f2", size = 811877, upload-time = "2026-06-28T19:56:25.056Z" }, + { url = "https://files.pythonhosted.org/packages/df/7b/9a5505ee92180bcae300b1018b9ff3d3c19962436e66f2505f255e9fde35/regex-2026.6.28-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:cc579c91fb4605773483a8d940b136bcc5b854fff44fa14a1572a038f46563f1", size = 871212, upload-time = "2026-06-28T19:56:27.352Z" }, + { url = "https://files.pythonhosted.org/packages/24/4d/d61a702a9f9d1bd29b22cbef1aed6d477baa961232a7eb4d91b7775b0b3e/regex-2026.6.28-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e7c42be203d84ecf7d487ff23f8a61ef0eb0534fa0fc317a2fce8c065d20618f", size = 917507, upload-time = "2026-06-28T19:56:29.762Z" }, + { url = "https://files.pythonhosted.org/packages/d4/60/1308066f5966b65fbb6905b99ba37e9f1cd753dd0ac08485f8257334ee92/regex-2026.6.28-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e8184b4e2fdaf9cdfe77e38f15a4d9dc149168c9c29eb0ea17c5481d3bb80546", size = 816389, upload-time = "2026-06-28T19:56:32.043Z" }, + { url = "https://files.pythonhosted.org/packages/bd/5c/57ce2cb8d714ee0b7f11c7ee4cfe2af66df2b90f147feadcb538609a3a02/regex-2026.6.28-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:697f103104f5872d64078d8eeac59979960be8ee76115a2d3f31096312e2a400", size = 785890, upload-time = "2026-06-28T19:56:34.492Z" }, + { url = "https://files.pythonhosted.org/packages/ff/fd/1d5350d3a8a327bff0fccacb911732baf7b5b6f5529c0e3fa602a23e7dad/regex-2026.6.28-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:714d2b1aa29beef0ddfcdc72ad0771c05326551a8bb0680b0ddf74bfaad87387", size = 801451, upload-time = "2026-06-28T19:56:36.749Z" }, + { url = "https://files.pythonhosted.org/packages/f3/79/3c9e4f8a0306e030ad5a43bbbc01625fb28d58a813bc52d42fd1cc63fb2e/regex-2026.6.28-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0f09f62e450cc2f113018cc8412aeea3a120a04e1ca7e801a0d441583f9a3b06", size = 866504, upload-time = "2026-06-28T19:56:38.994Z" }, + { url = "https://files.pythonhosted.org/packages/65/12/f747de475b54f4709efb24dd0fbc8467c64cec91f5db0d047b079646ee78/regex-2026.6.28-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:731ea12d5aeb2577eaef2393d6428b995f76eb35f68a89e03e15a97719d1de19", size = 773047, upload-time = "2026-06-28T19:56:41.061Z" }, + { url = "https://files.pythonhosted.org/packages/58/3c/f02f860e0500c1b2d61a79dec7e214b37fb9656281dcddc92397edf96678/regex-2026.6.28-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:51e952c8783eabd4706d0f63922f219bcfc1bef9b8cb35941c0d1a0396578858", size = 856665, upload-time = "2026-06-28T19:56:43.466Z" }, + { url = "https://files.pythonhosted.org/packages/4d/6c/28b3fa222513484be9dee26b7222bda109056c43ea28aa2314262ca48816/regex-2026.6.28-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:43248fe4c0ab8fbb223588a0795b11268940072c97bba30ea8f9b49d8cdfde34", size = 803573, upload-time = "2026-06-28T19:56:45.791Z" }, + { url = "https://files.pythonhosted.org/packages/fa/f0/8f86cf1a1fd85c5ab0c503c9fe4607ad4ad48978b2d8b435d94465e134c7/regex-2026.6.28-cp314-cp314t-win32.whl", hash = "sha256:fc1eddc25ad23c0f1344ab280d961ac595ead48292d7c779497975942373f493", size = 274515, upload-time = "2026-06-28T19:56:47.948Z" }, + { url = "https://files.pythonhosted.org/packages/0f/de/f8613c03b36786ddef2c930d28f9bcae861fcd541cc9203a870956cf1e83/regex-2026.6.28-cp314-cp314t-win_amd64.whl", hash = "sha256:ede8d8e53b6dde0a50f7eca902f0af76d87ab02a55aba7542da68ae3e5dfe83d", size = 283650, upload-time = "2026-06-28T19:56:50.614Z" }, + { url = "https://files.pythonhosted.org/packages/4d/f3/f5ec86839bbabe33b6dee649b62ff9a445d43de6b0ad780cf6b83c56f61e/regex-2026.6.28-cp314-cp314t-win_arm64.whl", hash = "sha256:4da6f6a72f8700b97a1a765e837fb7d5750bfd9f13acea7bae498f573e3a70a8", size = 283338, upload-time = "2026-06-28T19:56:52.879Z" }, ] [[package]] @@ -871,35 +951,36 @@ wheels = [ [[package]] name = "ruff" -version = "0.15.11" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/e4/8d/192f3d7103816158dfd5ea50d098ef2aec19194e6cbccd4b3485bdb2eb2d/ruff-0.15.11.tar.gz", hash = "sha256:f092b21708bf0e7437ce9ada249dfe688ff9a0954fc94abab05dcea7dcd29c33", size = 4637264, upload-time = "2026-04-16T18:46:26.58Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/02/1e/6aca3427f751295ab011828e15e9bf452200ac74484f1db4be0197b8170b/ruff-0.15.11-py3-none-linux_armv6l.whl", hash = "sha256:e927cfff503135c558eb581a0c9792264aae9507904eb27809cdcff2f2c847b7", size = 10607943, upload-time = "2026-04-16T18:46:05.967Z" }, - { url = "https://files.pythonhosted.org/packages/e7/26/1341c262e74f36d4e84f3d6f4df0ac68cd53331a66bfc5080daa17c84c0b/ruff-0.15.11-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7a1b5b2938d8f890b76084d4fa843604d787a912541eae85fd7e233398bbb73e", size = 10988592, upload-time = "2026-04-16T18:46:00.742Z" }, - { url = "https://files.pythonhosted.org/packages/03/71/850b1d6ffa9564fbb6740429bad53df1094082fe515c8c1e74b6d8d05f18/ruff-0.15.11-py3-none-macosx_11_0_arm64.whl", hash = "sha256:d4176f3d194afbdaee6e41b9ccb1a2c287dba8700047df474abfbe773825d1cb", size = 10338501, upload-time = "2026-04-16T18:46:03.723Z" }, - { url = "https://files.pythonhosted.org/packages/f2/11/cc1284d3e298c45a817a6aadb6c3e1d70b45c9b36d8d9cce3387b495a03a/ruff-0.15.11-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3b17c886fb88203ced3afe7f14e8d5ae96e9d2f4ccc0ee66aa19f2c2675a27e4", size = 10670693, upload-time = "2026-04-16T18:46:41.941Z" }, - { url = "https://files.pythonhosted.org/packages/ce/9e/f8288b034ab72b371513c13f9a41d9ba3effac54e24bfb467b007daee2ca/ruff-0.15.11-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:49fafa220220afe7758a487b048de4c8f9f767f37dfefad46b9dd06759d003eb", size = 10416177, upload-time = "2026-04-16T18:46:21.717Z" }, - { url = "https://files.pythonhosted.org/packages/85/71/504d79abfd3d92532ba6bbe3d1c19fada03e494332a59e37c7c2dabae427/ruff-0.15.11-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f2ab8427e74a00d93b8bda1307b1e60970d40f304af38bccb218e056c220120d", size = 11221886, upload-time = "2026-04-16T18:46:15.086Z" }, - { url = "https://files.pythonhosted.org/packages/43/5a/947e6ab7a5ad603d65b474be15a4cbc6d29832db5d762cd142e4e3a74164/ruff-0.15.11-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:195072c0c8e1fc8f940652073df082e37a5d9cb43b4ab1e4d0566ab8977a13b7", size = 12075183, upload-time = "2026-04-16T18:46:07.944Z" }, - { url = "https://files.pythonhosted.org/packages/9f/a1/0b7bb6268775fdd3a0818aee8efd8f5b4e231d24dd4d528ced2534023182/ruff-0.15.11-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a3a0996d486af3920dec930a2e7daed4847dfc12649b537a9335585ada163e9e", size = 11516575, upload-time = "2026-04-16T18:46:31.687Z" }, - { url = "https://files.pythonhosted.org/packages/30/c3/bb5168fc4d233cc06e95f482770d0f3c87945a0cd9f614b90ea8dc2f2833/ruff-0.15.11-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1bef2cb556d509259f1fe440bb9cd33c756222cf0a7afe90d15edf0866702431", size = 11306537, upload-time = "2026-04-16T18:46:36.988Z" }, - { url = "https://files.pythonhosted.org/packages/e4/92/4cfae6441f3967317946f3b788136eecf093729b94d6561f963ed810c82e/ruff-0.15.11-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:030d921a836d7d4a12cf6e8d984a88b66094ccb0e0f17ddd55067c331191bf19", size = 11296813, upload-time = "2026-04-16T18:46:24.182Z" }, - { url = "https://files.pythonhosted.org/packages/43/26/972784c5dde8313acde8ac71ba8ac65475b85db4a2352a76c9934361f9bc/ruff-0.15.11-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0e783b599b4577788dbbb66b9addcef87e9a8832f4ce0c19e34bf55543a2f890", size = 10633136, upload-time = "2026-04-16T18:46:39.802Z" }, - { url = "https://files.pythonhosted.org/packages/5b/53/3985a4f185020c2f367f2e08a103032e12564829742a1b417980ce1514a0/ruff-0.15.11-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:ae90592246625ba4a34349d68ec28d4400d75182b71baa196ddb9f82db025ef5", size = 10424701, upload-time = "2026-04-16T18:46:10.381Z" }, - { url = "https://files.pythonhosted.org/packages/d3/57/bf0dfb32241b56c83bb663a826133da4bf17f682ba8c096973065f6e6a68/ruff-0.15.11-py3-none-musllinux_1_2_i686.whl", hash = "sha256:1f111d62e3c983ed20e0ca2e800f8d77433a5b1161947df99a5c2a3fb60514f0", size = 10873887, upload-time = "2026-04-16T18:46:29.157Z" }, - { url = "https://files.pythonhosted.org/packages/02/05/e48076b2a57dc33ee8c7a957296f97c744ca891a8ffb4ffb1aaa3b3f517d/ruff-0.15.11-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:06f483d6646f59eaffba9ae30956370d3a886625f511a3108994000480621d1c", size = 11404316, upload-time = "2026-04-16T18:46:19.462Z" }, - { url = "https://files.pythonhosted.org/packages/88/27/0195d15fe7a897cbcba0904792c4b7c9fdd958456c3a17d2ea6093716a9a/ruff-0.15.11-py3-none-win32.whl", hash = "sha256:476a2aa56b7da0b73a3ee80b6b2f0e19cce544245479adde7baa65466664d5f3", size = 10655535, upload-time = "2026-04-16T18:46:12.47Z" }, - { url = "https://files.pythonhosted.org/packages/3a/5e/c927b325bd4c1d3620211a4b96f47864633199feed60fa936025ab27e090/ruff-0.15.11-py3-none-win_amd64.whl", hash = "sha256:8b6756d88d7e234fb0c98c91511aae3cd519d5e3ed271cae31b20f39cb2a12a3", size = 11779692, upload-time = "2026-04-16T18:46:17.268Z" }, - { url = "https://files.pythonhosted.org/packages/63/b6/aeadee5443e49baa2facd51131159fd6301cc4ccfc1541e4df7b021c37dd/ruff-0.15.11-py3-none-win_arm64.whl", hash = "sha256:063fed18cc1bbe0ee7393957284a6fe8b588c6a406a285af3ee3f46da2391ee4", size = 11032614, upload-time = "2026-04-16T18:46:34.487Z" }, +version = "0.15.20" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/43/dc/35b341fc554ba02f217fc10da57d1a75168cfbcf75b0ef2202176d4c4f2d/ruff-0.15.20.tar.gz", hash = "sha256:1416eb04349192646b54de98f146c4f59afe37d0decfc02c3cbbf396f3a28566", size = 4755489, upload-time = "2026-06-25T17:20:37.578Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/94/d9/2d5014f0253ba541d2061d9fa7193f48e941c8b21bb88a7ff9bbe0bd0596/ruff-0.15.20-py3-none-linux_armv6l.whl", hash = "sha256:00e188c53e499c3c1637f73c91dcf2fb56d576cab76ce1be50a27c4e80e37078", size = 10839665, upload-time = "2026-06-25T17:19:44.702Z" }, + { url = "https://files.pythonhosted.org/packages/c6/d3/ac1798ba64f670698867fcfc591d50e7e421bef137db564858f619a30fcf/ruff-0.15.20-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:9ebd1fd9b9c95fc0bd7b2761aebec1f030013d2e193a2901b224af68fe47251b", size = 11208649, upload-time = "2026-06-25T17:19:48.787Z" }, + { url = "https://files.pythonhosted.org/packages/47/47/d3ac899991202095dfcf3d5176be4272642be3cf981a2f1a30f72a2afb95/ruff-0.15.20-py3-none-macosx_11_0_arm64.whl", hash = "sha256:c5b16cdd67ca108185cd36dce98c576350c03b1660a751de725fb049193a0632", size = 10622638, upload-time = "2026-06-25T17:19:51.354Z" }, + { url = "https://files.pythonhosted.org/packages/33/13/4e043fe30aa94d4ff5213a9881fc296d12960f5971b234a5263fdc225312/ruff-0.15.20-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3413bb3c3d2ca6a8208f1f4809cd2dca3c6de6d0b491c0e70847672bde6e6efd", size = 10984227, upload-time = "2026-06-25T17:19:54.044Z" }, + { url = "https://files.pythonhosted.org/packages/76/e6/92e7bf40388bc5800073b96564f56264f7e48bfd1a498f5ced6ae6d5a769/ruff-0.15.20-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bd7ec42b3bb3da066488db093308a69c4ac5ee6d2af333a86ba6e2eb2e7dd44b", size = 10622882, upload-time = "2026-06-25T17:19:57.037Z" }, + { url = "https://files.pythonhosted.org/packages/13/7a/43460be3f24495a3aa46d4b16873e2c4941b3b5f0b00cf88c03b7b94b339/ruff-0.15.20-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e1a36ad0eb77fba9aabfb69ede54de6f376d04ac18ebea022847046d340a8267", size = 11474808, upload-time = "2026-06-25T17:20:00.357Z" }, + { url = "https://files.pythonhosted.org/packages/27/a0/f37077884873221c6b33b4ab49eb18f9f88e54a16a25a5bca59bef46dd66/ruff-0.15.20-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b6df3b1e4610432f0386dba04d853b5f08cbbc903410c6fcc02f620f05aff53c", size = 12293094, upload-time = "2026-06-25T17:20:03.446Z" }, + { url = "https://files.pythonhosted.org/packages/a6/74/165545b60256a9704c21ac0ec4a0d07933b320812f9584836c9f4aca4292/ruff-0.15.20-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e89f198a1ea6ef0d727c1cf16088bc91a6cb0ab947dedc966715691647186eae", size = 11526176, upload-time = "2026-06-25T17:20:06.301Z" }, + { url = "https://files.pythonhosted.org/packages/86/b1/a976a136d40ade83ce743578399865f57001003a409acadc0ecbb3051082/ruff-0.15.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:309809086c2acb67624950a3c8133e80f32d0d3e27106c0cd60ff26657c9f24b", size = 11520767, upload-time = "2026-06-25T17:20:09.191Z" }, + { url = "https://files.pythonhosted.org/packages/19/0f/f032696cb01c9b54c0263fa393474d7758f1cdc021a01b04e3cbc2500999/ruff-0.15.20-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2d2374caa2f2c2f9e2b7da0a50802cfb8b79f55a9b5e49379f564544fbf56487", size = 11500132, upload-time = "2026-06-25T17:20:13.602Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f4/51b1a14bc69e8c224b15dab9cce8e99b425e0455d462caa2b3c9be2b6a8e/ruff-0.15.20-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a1ed17b65293e0c2f22fc387bc13198a5de94bf4429589b0ff6946b0feaf21a3", size = 10943828, upload-time = "2026-06-25T17:20:16.635Z" }, + { url = "https://files.pythonhosted.org/packages/71/4b/fe267640783cd02bf6c5cc290b1df1051be2ec294c678b5c15fe19e52343/ruff-0.15.20-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:f701305e66b38ea6c91882490eb73459796808e4c6362a1b765255e0cdcd4053", size = 10645418, upload-time = "2026-06-25T17:20:19.4Z" }, + { url = "https://files.pythonhosted.org/packages/b0/c0/a65aa4ec2f5e87a1df32dc3ec1fede434fe3dfd5cbcf3b503cafc676ab54/ruff-0.15.20-py3-none-musllinux_1_2_i686.whl", hash = "sha256:5b9c0c367ad8e5d0d5b5b8537864c469a0a0e55417aadfbeca41fa61333be9f4", size = 11211770, upload-time = "2026-06-25T17:20:22.033Z" }, + { url = "https://files.pythonhosted.org/packages/5a/a4/0caa331d954ae2723d729d351c989cb4ca8b6077d5c6c2cb6de75e98c041/ruff-0.15.20-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:01cc00dd58f0df339d0e902219dd53990ea99996a0344e5d9cc8d45d5307e460", size = 11618698, upload-time = "2026-06-25T17:20:25.259Z" }, + { url = "https://files.pythonhosted.org/packages/10/9b/5f14927848d2fd4aa891fd88d883788c5a7baba561c7874732364045708c/ruff-0.15.20-py3-none-win32.whl", hash = "sha256:ed65ef510e43a137207e0f01cfcf998aeddb1aeeda5c9d35023e910284d7cf21", size = 10857322, upload-time = "2026-06-25T17:20:28.612Z" }, + { url = "https://files.pythonhosted.org/packages/fa/f0/fe47c501f9dea92a26d788ff98bb5d92ed4cb4c88792c5c88af6b697dc8e/ruff-0.15.20-py3-none-win_amd64.whl", hash = "sha256:a525c81c70fb0380344dd1d8745d8cc1c890b7fc94a58d5a07bd8eb9557b8415", size = 11993274, upload-time = "2026-06-25T17:20:31.871Z" }, + { url = "https://files.pythonhosted.org/packages/d7/2b/9555445e1201d92b3195f45cdb153a0b68f24e0a4273f6e3d5ab46e212bb/ruff-0.15.20-py3-none-win_arm64.whl", hash = "sha256:2f5b2a6d614e8700388806a14996c40fab2c47b819ef57d790a34878858ed9ca", size = 11343498, upload-time = "2026-06-25T17:20:35.03Z" }, ] [[package]] name = "safety" -version = "3.7.0" +version = "3.8.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "authlib" }, + { name = "certifi" }, { name = "click" }, { name = "dparse" }, { name = "filelock" }, @@ -909,17 +990,17 @@ dependencies = [ { name = "nltk" }, { name = "packaging" }, { name = "pydantic" }, - { name = "requests" }, { name = "ruamel-yaml" }, { name = "safety-schemas" }, { name = "tenacity" }, { name = "tomlkit" }, + { name = "truststore" }, { name = "typer" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/6f/e8/1cfffa0d8836de8aa31f4fa7fdeb892c7cfa97cd555039ad5df71ce0e968/safety-3.7.0.tar.gz", hash = "sha256:daec15a393cafc32b846b7ef93f9c952a1708863e242341ab5bde2e4beabb54e", size = 330538, upload-time = "2025-11-06T20:10:15.067Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c2/7b/8e1d580c5178f0736b806b7199827e61e2a2569eec5b49ec75da6273bbdf/safety-3.8.1.tar.gz", hash = "sha256:e646123b976bbb6707cfaacae8c926e2f886b744a60e0f410e8610a3a4eaf7be", size = 412947, upload-time = "2026-05-29T15:09:33.355Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/89/55/c4b2058ca346e58124ba082a3596e30dc1f5793710f8173156c7c2d77048/safety-3.7.0-py3-none-any.whl", hash = "sha256:65e71db45eb832e8840e3456333d44c23927423753d5610596a09e909a66d2bf", size = 312436, upload-time = "2025-11-06T20:10:13.576Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f5/498db84333a644835e572c0d96cfa705bf9871f863289a7845082d54755e/safety-3.8.1-py3-none-any.whl", hash = "sha256:953c1c3c60c873f53a6cc250b2a9c4b38bb6ef45f0625990e43f20bff916c965", size = 340521, upload-time = "2026-05-29T15:09:31.622Z" }, ] [[package]] @@ -967,14 +1048,14 @@ wheels = [ [[package]] name = "starlette" -version = "1.0.1" +version = "1.3.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/08/a3/84e821cc54b4ab50ae6dbc6ac3800a651b65ec35f045cc73785380654057/starlette-1.0.1.tar.gz", hash = "sha256:512399c5f1de7fac99c88572212ded9ddeddef2fb32afa82d724000e88b38f4f", size = 2659596, upload-time = "2026-05-21T21:58:58.433Z" } +sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ec/e1/b2df4bc09a1e51ff664c1e17018a4274b42e5e9352e4a478ea540512dc88/starlette-1.0.1-py3-none-any.whl", hash = "sha256:7c0e69b2ee1c848bd54669d908500117a3ee13de603a21427e5c6fc1adf98dcd", size = 72802, upload-time = "2026-05-21T21:58:56.551Z" }, + { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" }, ] [[package]] @@ -996,13 +1077,15 @@ wheels = [ name = "temple8" version = "9.4.0" source = { virtual = "." } +dependencies = [ + { name = "flowr" }, +] [package.optional-dependencies] dev = [ - { name = "beehave" }, - { name = "flowr" }, { name = "ghp-import" }, { name = "hypothesis" }, + { name = "mypy" }, { name = "pdoc" }, { name = "pyright" }, { name = "pytest" }, @@ -1010,9 +1093,11 @@ dev = [ { name = "pytest-cov" }, { name = "pytest-html" }, { name = "pytest-mock" }, + { name = "pytest-vcr" }, { name = "ruff" }, { name = "safety" }, { name = "taskipy" }, + { name = "vcrpy" }, ] [package.dev-dependencies] @@ -1023,10 +1108,10 @@ dev = [ [package.metadata] requires-dist = [ - { name = "beehave", marker = "extra == 'dev'", specifier = ">=1.0.0" }, - { name = "flowr", marker = "extra == 'dev'", specifier = ">=1.2.0" }, + { name = "flowr", specifier = ">=1.2.1" }, { name = "ghp-import", marker = "extra == 'dev'", specifier = ">=2.1.0" }, { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.148.4" }, + { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" }, { name = "pdoc", marker = "extra == 'dev'", specifier = ">=14.0" }, { name = "pyright", marker = "extra == 'dev'", specifier = ">=1.1.407" }, { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" }, @@ -1034,9 +1119,11 @@ requires-dist = [ { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=6.1.1" }, { name = "pytest-html", marker = "extra == 'dev'", specifier = ">=4.0.0" }, { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.14.0" }, + { name = "pytest-vcr", marker = "extra == 'dev'", specifier = ">=1.0.2" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.11.5" }, { name = "safety", marker = "extra == 'dev'", specifier = ">=3.7.0" }, { name = "taskipy", marker = "extra == 'dev'", specifier = ">=1.14.1" }, + { name = "vcrpy", marker = "extra == 'dev'", specifier = ">=6.0.1" }, ] provides-extras = ["dev"] @@ -1084,28 +1171,37 @@ wheels = [ [[package]] name = "tomlkit" -version = "0.14.0" +version = "0.15.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/c3/af/14b24e41977adb296d6bd1fb59402cf7d60ce364f90c890bd2ec65c43b5a/tomlkit-0.14.0.tar.gz", hash = "sha256:cf00efca415dbd57575befb1f6634c4f42d2d87dbba376128adb42c121b87064", size = 187167, upload-time = "2026-01-13T01:14:53.304Z" } +sdist = { url = "https://files.pythonhosted.org/packages/51/db/03eaf4331631ef6b27d6e3c9b68c54dc6f0d63d87201fed600cc409307fd/tomlkit-0.15.0.tar.gz", hash = "sha256:7d1a9ecba3086638211b13814ea79c90dd54dd11993564376f3aa92271f5c7a3", size = 161875, upload-time = "2026-05-10T07:38:22.245Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b5/11/87d6d29fb5d237229d67973a6c9e06e048f01cf4994dee194ab0ea841814/tomlkit-0.14.0-py3-none-any.whl", hash = "sha256:592064ed85b40fa213469f81ac584f67a4f2992509a7c3ea2d632208623a3680", size = 39310, upload-time = "2026-01-13T01:14:51.965Z" }, + { url = "https://files.pythonhosted.org/packages/6a/43/8bd850ee71a191bf072e31302c73a66be413fecdd98fdcd111ecbcce13ca/tomlkit-0.15.0-py3-none-any.whl", hash = "sha256:4dbc8f0fc024412b57ced8757ac7461305126a648ff8c2c807fcb8e133a78738", size = 41328, upload-time = "2026-05-10T07:38:23.517Z" }, ] [[package]] name = "tqdm" -version = "4.67.3" +version = "4.68.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/09/a9/6ba95a270c6f1fbcd8dac228323f2777d886cb206987444e4bce66338dd4/tqdm-4.67.3.tar.gz", hash = "sha256:7d825f03f89244ef73f1d4ce193cb1774a8179fd96f31d7e1dcde62092b960bb", size = 169598, upload-time = "2026-02-03T17:35:53.048Z" } +sdist = { url = "https://files.pythonhosted.org/packages/87/d7/0535a28b1f5f24f6612fb3ff1e89fb1a8d160fee0f976e0aa6803862134b/tqdm-4.68.3.tar.gz", hash = "sha256:00dfa48452b6b6cfae3dd9885636c23d3422d1ec97c66d96818cbd5e0821d482", size = 170596, upload-time = "2026-06-17T07:36:52.105Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/16/e1/3079a9ff9b8e11b846c6ac5c8b5bfb7ff225eee721825310c91b3b50304f/tqdm-4.67.3-py3-none-any.whl", hash = "sha256:ee1e4c0e59148062281c49d80b25b67771a127c85fc9676d3be5f243206826bf", size = 78374, upload-time = "2026-02-03T17:35:50.982Z" }, + { url = "https://files.pythonhosted.org/packages/d8/8e/bb97bb0c71802080bfc8952937d174e49cfc50de5c951dd47b2496f0dcdb/tqdm-4.68.3-py3-none-any.whl", hash = "sha256:39832cc2def2789a6f29df83f172db7416cea70052c0907a57801c5f2fdccb03", size = 78337, upload-time = "2026-06-17T07:36:50.132Z" }, +] + +[[package]] +name = "truststore" +version = "0.10.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/53/a3/1585216310e344e8102c22482f6060c7a6ea0322b63e026372e6dcefcfd6/truststore-0.10.4.tar.gz", hash = "sha256:9d91bd436463ad5e4ee4aba766628dd6cd7010cf3e2461756b3303710eebc301", size = 26169, upload-time = "2025-08-12T18:49:02.73Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/19/97/56608b2249fe206a67cd573bc93cd9896e1efb9e98bce9c163bcdc704b88/truststore-0.10.4-py3-none-any.whl", hash = "sha256:adaeaecf1cbb5f4de3b1959b42d41f6fab57b2b1666adb59e89cb0b53361d981", size = 18660, upload-time = "2025-08-12T18:49:01.46Z" }, ] [[package]] name = "typer" -version = "0.24.1" +version = "0.25.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "annotated-doc" }, @@ -1113,9 +1209,9 @@ dependencies = [ { name = "rich" }, { name = "shellingham" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e4/51/9aed62104cea109b820bbd6c14245af756112017d309da813ef107d42e7e/typer-0.25.1.tar.gz", hash = "sha256:9616eb8853a09ffeabab1698952f33c6f29ffdbceb4eaeecf571880e8d7664cc", size = 122276, upload-time = "2026-04-30T19:32:16.964Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" }, + { url = "https://files.pythonhosted.org/packages/3f/f9/2b3ff4e56e5fa7debfaf9eb135d0da96f3e9a1d5b27222223c7296336e5f/typer-0.25.1-py3-none-any.whl", hash = "sha256:75caa44ed46a03fb2dab8808753ffacdbfea88495e74c85a28c5eefcf5f39c89", size = 58409, upload-time = "2026-04-30T19:32:18.271Z" }, ] [[package]] @@ -1139,24 +1235,59 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" }, ] -[[package]] -name = "urllib3" -version = "2.7.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" }, -] - [[package]] name = "uvicorn" -version = "0.47.0" +version = "0.49.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click" }, { name = "h11" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f6/b1/8e7077a8641086aea449e1b5752a570f1b5906c64e0a33cd6d93b63a066b/uvicorn-0.47.0.tar.gz", hash = "sha256:7c9a0ea1a9414106bbab7324609c162d8fa0cdcdcb703060987269d77c7bb533", size = 90582, upload-time = "2026-05-14T18:16:54.455Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c4/1f/fa18009dea8469069cca78a4e877a008ab78f08b064bfc9ab891579077ff/uvicorn-0.49.0.tar.gz", hash = "sha256:ebf4271aa580d9de97f93192d4595176df6e91f9aae919ca73e4fc07df1e66a3", size = 91284, upload-time = "2026-06-03T22:01:30.448Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/15/41/ac2dfdbc1f60c7af4f994c7a335cfa7040c01642b605d65f611cecc2a1e4/uvicorn-0.47.0-py3-none-any.whl", hash = "sha256:2c5715bc12d1892d84752049f400cd1c3cb018514967fdfeb97640443a6a9432", size = 71301, upload-time = "2026-05-14T18:16:51.762Z" }, + { url = "https://files.pythonhosted.org/packages/88/fa/e1388bbcf24ef3274f45c0c1c7b501fd14971037c1b6ee23610553307497/uvicorn-0.49.0-py3-none-any.whl", hash = "sha256:ba3d14c3ee7e41c6c654c46c9eb489d33213cdd30aa1696eab1374337c13f68f", size = 71376, upload-time = "2026-06-03T22:01:29.037Z" }, +] + +[[package]] +name = "vcrpy" +version = "8.2.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pyyaml" }, + { name = "wrapt" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/08/db/08183b845b0040bb877dad2bd7e4e0976fc232bb3476d7ee369c6c4f8b5a/vcrpy-8.2.1.tar.gz", hash = "sha256:d73a6e4eb6dae8148e659764b7a00e68cc51ba29ba9e6a85e1f0790ad96b97df", size = 90511, upload-time = "2026-06-16T13:20:52.906Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f8/7c/0e812ab83f5289404c674f3461ba783250b967d34b5ab034d361236ec042/vcrpy-8.2.1-py3-none-any.whl", hash = "sha256:7ce58c9e2792b246f79d6f4b3e9660676cc6f853be17e1547305b4437ab1ff85", size = 44925, upload-time = "2026-06-16T13:20:51.734Z" }, +] + +[[package]] +name = "wrapt" +version = "2.2.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fe/a4/282c8e64300a59fc834518a54bf0afabb4ff9218b5fa76958b450459a844/wrapt-2.2.2.tar.gz", hash = "sha256:0788e321027c999bf221b667bd4a54aaefd1a36283749a860ac3eb77daed0302", size = 129068, upload-time = "2026-06-20T23:49:44.49Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/24/05/7fd9c3f83b2c74cbfc572a0b88aa37431e04bd8aed70d2c0efd3464206de/wrapt-2.2.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0e64826f920c42d9d9f87e8cc09ffae66c51ede12d59061a5a426deb9aa71745", size = 81341, upload-time = "2026-06-20T23:48:49.39Z" }, + { url = "https://files.pythonhosted.org/packages/4b/68/1bfa43100dd90d4ef74a05897b86275cf57e1313ca14aae2545bc9f872c9/wrapt-2.2.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:dcaa5e1451bd8751d7bd1568dfa3321c78092a52a7ecb5d1a0f18a5791e1fd00", size = 81921, upload-time = "2026-06-20T23:48:50.986Z" }, + { url = "https://files.pythonhosted.org/packages/74/eb/df7b7f0b631dbbc750f39be27d8b55f65777d8ac86da80e12be41a644c4b/wrapt-2.2.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0abfd648dac9ac9c5b3aa9b523d27f1789046640b58dcd5652a720ddb325e1fc", size = 167713, upload-time = "2026-06-20T23:48:52.598Z" }, + { url = "https://files.pythonhosted.org/packages/4d/9a/d1bd36f6d088c8e652a9383cabbd49af30b8c576302a7eccddbab6963e3f/wrapt-2.2.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f4bfd8d1eb438153eff8b8cfe87f032ba65731e1ce06138b5090f745a33f6f95", size = 166779, upload-time = "2026-06-20T23:48:54.33Z" }, + { url = "https://files.pythonhosted.org/packages/4c/ae/24ffacd4187fac2740a1972093929e836dea092d42c87d728cd98fee11a6/wrapt-2.2.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c427c9d06d859848a69f0d928fe28b5c33a941b2265d10a0e1f15cd244f1ee33", size = 158407, upload-time = "2026-06-20T23:48:55.944Z" }, + { url = "https://files.pythonhosted.org/packages/a3/ed/974427668249a356051e8d67d47fa54ef6c777f0fcf3bae9d292c047d4b6/wrapt-2.2.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:4250b43d1a129d947e083c4dc6baf333c9bb34edd26f912d5b0457841fc858ab", size = 166594, upload-time = "2026-06-20T23:48:57.617Z" }, + { url = "https://files.pythonhosted.org/packages/fb/5f/e1d7c6e4523f78db2fbd7826babd0348da1d5e0834c4f918b9ab5757dfae/wrapt-2.2.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:173e5bb5ca350a6e0abab60b7ec7cdd7992a814cb14b4de670a28f067f105663", size = 157068, upload-time = "2026-06-20T23:48:59.171Z" }, + { url = "https://files.pythonhosted.org/packages/1e/c1/7ebd1027f00700c0b0233b20aceef2b4784294ed64971424c4a78e069e34/wrapt-2.2.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:aa14b01804bce36c6d63d7b6a4f55df390f29f8648cc13a1f40b166f4d54680d", size = 166470, upload-time = "2026-06-20T23:49:00.737Z" }, + { url = "https://files.pythonhosted.org/packages/99/eb/974e471a6a978b8180186b8a9dc5ae3361ce269a967190b709b8ce17abfb/wrapt-2.2.2-cp314-cp314-win32.whl", hash = "sha256:58f9f8d637c9a6e245c6ef5b109b67ec187d2faed23d1405656b51d96e0a5b56", size = 78062, upload-time = "2026-06-20T23:49:02.327Z" }, + { url = "https://files.pythonhosted.org/packages/49/ec/e1281156cdc7a66693838ad7a0865ad641c74abd337a957d668b575aaffb/wrapt-2.2.2-cp314-cp314-win_amd64.whl", hash = "sha256:385cb1866f20479e83299af585375bfa0a4b0c6c9907a981483ea782ea8ae406", size = 80832, upload-time = "2026-06-20T23:49:03.837Z" }, + { url = "https://files.pythonhosted.org/packages/45/7d/1b6b5ddd94005a2dac97a4490c9838f3154977850d633abcb65b30089437/wrapt-2.2.2-cp314-cp314-win_arm64.whl", hash = "sha256:8ffbeaea6771a6eba6e6eeb09767864995726bc8240bb54baf88a9bb1db34d5c", size = 80029, upload-time = "2026-06-20T23:49:05.237Z" }, + { url = "https://files.pythonhosted.org/packages/b0/33/9ebcf8aafe91c601127cbd93708c16aa8f688f34a10bf004046803ecdc4f/wrapt-2.2.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:09f811d43f6f33ec7515f0be76b159569f4057ab54d3e079c3204dddb90afa2a", size = 83357, upload-time = "2026-06-20T23:49:06.632Z" }, + { url = "https://files.pythonhosted.org/packages/39/38/ec45b635153327b52e52732a0ea980e5f00b7efba65f9e018828f1e69daa/wrapt-2.2.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a795d3c06e5fbf9ea2f13196180b77aeab1b4685917256ee0d014cc163d90063", size = 83794, upload-time = "2026-06-20T23:49:08.098Z" }, + { url = "https://files.pythonhosted.org/packages/4e/ea/1a89e6d3b7a83c3affe5c09cde77792c947e63e4bc85ad84cd5bb9abb0d8/wrapt-2.2.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:45c2f2768e790c9f8db90f239ef23a2af8e7570f25a35619ef902df4a738447f", size = 203362, upload-time = "2026-06-20T23:49:09.811Z" }, + { url = "https://files.pythonhosted.org/packages/19/d8/3b58763d9863b5a73771c0d97110f9595d248db454009e07e1535ee905a4/wrapt-2.2.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bbf00ee0cb55ec24e2b0995a71942b85b21a066db8f3f46e1dbfdb9433ffba81", size = 210449, upload-time = "2026-06-20T23:49:11.521Z" }, + { url = "https://files.pythonhosted.org/packages/2d/6f/17fd9e053103d8be148d20d5d7505facc72d5fe1f9127973904ceaed79cf/wrapt-2.2.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:2252f77663651b89255895f58cc6ac08fcb206d4371813e5af61bb62d4f7689c", size = 195349, upload-time = "2026-06-20T23:49:13.346Z" }, + { url = "https://files.pythonhosted.org/packages/ef/04/d0d1ccaaa12cb7dccf28a23f0279a608ba498f71e81d949d5ed54bcfd5c1/wrapt-2.2.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2cd7181ab1c31192ff5219269830744b5a62020b3a6d433588c4f1c95b8f8bff", size = 206099, upload-time = "2026-06-20T23:49:15.051Z" }, + { url = "https://files.pythonhosted.org/packages/44/b3/e8aa07b619890a2aa6cde1931b1887abb08820721b564a5f80b7ca3f3aa0/wrapt-2.2.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:6fe35fd51b74867d8b80174c277bd6bbf6a73e443f908129dc531c4b688a20d5", size = 192728, upload-time = "2026-06-20T23:49:16.854Z" }, + { url = "https://files.pythonhosted.org/packages/b7/f0/1819fb50f0d3c9bd758d8a83b56f1b470dee8b5b8eac8702b7c137cea9d4/wrapt-2.2.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:11d95fc2fbad3163596c39d440e6f21ca9fccece74b56e30a37ac2fca786a07c", size = 198842, upload-time = "2026-06-20T23:49:18.504Z" }, + { url = "https://files.pythonhosted.org/packages/67/7c/e88313f16a99930b899ef970d91c281544a470749a359decad994483bbda/wrapt-2.2.2-cp314-cp314t-win32.whl", hash = "sha256:d8a15813215f33fa83667bfc978b300e35669ea8bb424e970a1426bcb7bc6cca", size = 79059, upload-time = "2026-06-20T23:49:20.107Z" }, + { url = "https://files.pythonhosted.org/packages/a0/4f/ac12fda57a55068a094ec42851fb0a40e8489d8941863d517452de62e507/wrapt-2.2.2-cp314-cp314t-win_amd64.whl", hash = "sha256:d09db0f7e8357060d3c38fc22a018aba683a796bf184360fd1a58f6fc180dc77", size = 82462, upload-time = "2026-06-20T23:49:21.631Z" }, + { url = "https://files.pythonhosted.org/packages/48/a7/df732dac86d9b2027c56bd163dbc883e037b16c3469614752e148d219c61/wrapt-2.2.2-cp314-cp314t-win_arm64.whl", hash = "sha256:f32fe639c39561ccc187bcae17e9271be0eb45f1c2952510d2f29b33ab577347", size = 81182, upload-time = "2026-06-20T23:49:23.199Z" }, + { url = "https://files.pythonhosted.org/packages/6e/d2/6317eb6d4554855bbf12d61857774af34747bf88a42c19bf306de67e2fa3/wrapt-2.2.2-py3-none-any.whl", hash = "sha256:5bad217350f19ce99ca5b5e71d406765ea86fe541628426772b657375ee1c048", size = 61460, upload-time = "2026-06-20T23:49:42.966Z" }, ] From a7d5065876b0507dcdbfa8be72c5a92b3b1b9c40 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 12:13:26 -0400 Subject: [PATCH 02/28] fix(discovery): scope interview skills to the techniques they apply MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop interview-techniques from interview-features and consolidate-interview load lists — those levels do structural decomposition and synthesis, not CIT/Laddering elicitation, so loading the shared technique bled undirected elicitation into them. interview-techniques is now cited only by the two elicitation levels (interview-general, interview-cross-cutting), which direct every technique they load. Update TODO with the missing tracks: flow design debt (plan-flow rework gaps), pyproject+tooling cleanup, docs (deleted-but-referenced README), and the knowledge-to-author list. --- .../skills/consolidate-interview/SKILL.md | 2 +- .opencode/skills/interview-features/SKILL.md | 2 +- TODO.md | 74 +++++++++++-------- 3 files changed, 45 insertions(+), 33 deletions(-) diff --git a/.opencode/skills/consolidate-interview/SKILL.md b/.opencode/skills/consolidate-interview/SKILL.md index 6c22e943..a95dad82 100644 --- a/.opencode/skills/consolidate-interview/SKILL.md +++ b/.opencode/skills/consolidate-interview/SKILL.md @@ -5,7 +5,7 @@ description: "End of session — replace running notes with the full synthesis a # Consolidate Interview -1. Load [[requirements/interview-techniques]], [[requirements/ubiquitous-language]] — the active-listening protocol and term extraction. +1. Load [[requirements/ubiquitous-language]] — term extraction for the glossary. This level synthesises (Active Listening L3, applied in step 3); it does not probe. 2. Read the running interview-notes across all three levels. 3. Apply Active Listening L3: replace the running notes with the full synthesis across all three funnel levels and present it to the stakeholder for approval. The summary reflects what the stakeholder said — no new framing or topic labels. 4. Author and refine the glossary of ubiquitous language from the stakeholder's own terms so it leads all subsequent naming per [[requirements/ubiquitous-language]]. diff --git a/.opencode/skills/interview-features/SKILL.md b/.opencode/skills/interview-features/SKILL.md index 655fecc7..74024bd9 100644 --- a/.opencode/skills/interview-features/SKILL.md +++ b/.opencode/skills/interview-features/SKILL.md @@ -5,7 +5,7 @@ description: "Funnel level 3 — identify feature names and rough boundaries onl # Interview (Features) -1. Load [[requirements/interview-techniques]], [[requirements/feature-discovery]], [[requirements/feature-boundaries]] — elicitation technique, gap analysis, and boundary sizing. +1. Load [[requirements/feature-discovery]], [[requirements/feature-boundaries]] — gap analysis and boundary sizing. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). 2. Read the running interview-notes; append the feature names and boundaries to it. 3. Capture feature NAMES and rough boundaries ONLY — no detailed spec (rules, examples, criteria come later in planning). The purpose is to know WHAT features exist, not to specify each. 4. Run gap analysis: IF a bounded context from cross-cutting maps to no feature THEN flag the gap; IF a quality attribute maps to no feature THEN flag the gap. Do not silently fill gaps per [[requirements/feature-discovery]], [[requirements/feature-boundaries]]. diff --git a/TODO.md b/TODO.md index e8b38fd6..4e272636 100644 --- a/TODO.md +++ b/TODO.md @@ -216,43 +216,51 @@ Known constraints (revisit if they bite): - Committed vcrpy cassettes can leak secrets unless `filter_headers` / `before_record` scrub them at record time; review cassettes before commit. -Markers: `[ ]` pending · `[~]` in progress. +Markers: `[x]` done · `[ ]` pending · `[~]` in progress. -## Knowledge to author (Stage 3 — cited by the skills via `[[...]]`) -Raw material lives in `.backup/.opencode/knowledge/`; restore selectively and rewrite (the backup is beehave-stale — do NOT bulk-copy). Track as debt until authored; skills' forward-ref wikilinks resolve once these exist. +## Flow design debt (rework path — happy path verified in simulation, rework path untested) +- [ ] `needs-contracts` carries no persisted handoff — build/red `output artifacts: []`, so the gap relies on undocumented orchestrator prompt-stuffing. Add a `.cache//contract-gap.md` that `author-test-stubs` reads on re-entry, or document the prompt-stuffing convention explicitly. +- [ ] Plan authoring states (`author-test-stubs`, `write-test-py`, `derive-source-stubs`) list their OUTPUT globs but not the EXISTING instances — a fresh pass is explicit, a rework pass is implicit ("read what's on disk"). Add the existing-output globs as inputs. +- [ ] Escalations re-enter subflows at the FIRST state (flowr has no position memory); rework re-runs the whole chain and full gates. Document the cost or accept it. -`requirements/`: -- [x] `interview-techniques.md` — CIT, Laddering, CI Perspective, Funnel, Active Listening L1/L2/L3 (cited by interview-general, interview-cross-cutting, interview-features, consolidate-interview). AUTHORED. -- [ ] `ubiquitous-language.md` — genus-differentia definitions, term extraction (consolidate-interview). -- [ ] `feature-discovery.md` — bounded-context → feature, gap analysis (interview-features, review-test-stubs). -- [ ] `feature-boundaries.md` — naming + boundary sizing (interview-features). -- [ ] `spec-simulation.md` — "would-passing-yield-a-working-system" method (simulate-contracts). +## Knowledge to author (Stage 3 — derived from the skills' `[[...]]` citations) +18 distinct knowledge files cited across the 21 skills. Re-derived from `.opencode/skills/`; priority = citation count (most-cited first = highest leverage to author). Raw material lives in `.backup/.opencode/knowledge/` — restore selectively and rewrite (the backup is beehave-stale; do NOT bulk-copy). Skills' forward-ref wikilinks resolve once these exist; track as debt until authored. -`software-craft/`: -- [ ] `external-fixtures.md` — probe patterns, vcrpy cassette hygiene, kind-dispatch table (research-provider, write-probe, record-cassette). -- [ ] `test-stubs.md` — test `.pyi` conventions, stubtest on test pairs (author-test-stubs, simulate-contracts). -- [ ] `test-design.md` — what to test, body patterns (author-test-stubs, write-test-py). -- [ ] `code-review.md` — review method (review-test-stubs, review-implementation). -- [ ] `solid.md` — SOLID criteria (write-test-py, refactor-green, review-implementation). -- [ ] `object-calisthenics.md` — Object Calisthenics rules (write-test-py, refactor-green). -- [ ] `smell-catalogue.md` — smell taxonomy (write-test-py, refactor-green, review-implementation). -- [ ] `source-stubs.md` — source `.pyi` conventions, stubtest scope, canonical data-shape (derive-source-stubs, implement-from-stub). -- [ ] `tdd.md` — red/green/refactor discipline, pending-mark cycle (select-build-target, confirm-red-failure, implement-from-stub). -- [ ] `design-patterns.md` — implementation patterns (implement-from-stub). -- [ ] `refactoring-techniques.md` — refactoring moves (refactor-green). -- [ ] `git-conventions.md` — imperative messages, squash-merge (ship-unit, merge-to-dev, publish-release). -- [ ] `versioning.md` — release/tag policy (publish-release). +**Cited by 4 skills:** +- [x] `requirements/interview-techniques.md` — CIT, Laddering, CI Perspective, Funnel, Active Listening L1/L2/L3. *(interview-general, interview-cross-cutting, interview-features, consolidate-interview)*. AUTHORED. + +**Cited by 3 skills:** +- [ ] `software-craft/solid.md` — SOLID criteria. *(write-test-py, refactor-green, review-implementation)* +- [ ] `software-craft/smell-catalogue.md` — smell taxonomy. *(write-test-py, refactor-green, review-implementation)* +- [ ] `software-craft/tdd.md` — red/green/refactor discipline, pending-mark cycle. *(select-build-target, confirm-red-failure, implement-from-stub)* +- [ ] `software-craft/external-fixtures.md` — probe patterns, vcrpy cassette hygiene, kind-dispatch table. *(research-provider, write-probe, record-cassette)* +- [ ] `software-craft/git-conventions.md` — imperative messages, squash-merge. *(ship-unit, merge-to-dev, publish-release)* + +**Cited by 2 skills:** +- [ ] `software-craft/test-stubs.md` — test `.pyi` conventions, stubtest on test pairs. *(author-test-stubs, simulate-contracts)* +- [ ] `software-craft/test-design.md` — what to test, body patterns. *(author-test-stubs, write-test-py)* +- [ ] `software-craft/code-review.md` — review method. *(review-test-stubs, review-implementation)* +- [ ] `software-craft/object-calisthenics.md` — Object Calisthenics rules. *(write-test-py, refactor-green)* +- [ ] `software-craft/source-stubs.md` — source `.pyi` conventions, stubtest scope, canonical data-shape. *(derive-source-stubs, implement-from-stub)* +- [ ] `requirements/feature-discovery.md` — bounded-context → feature, gap analysis. *(interview-features, review-test-stubs)* + +**Cited by 1 skill:** +- [ ] `requirements/ubiquitous-language.md` — genus-differentia definitions, term extraction. *(consolidate-interview)* +- [ ] `requirements/feature-boundaries.md` — naming + boundary sizing. *(interview-features)* +- [ ] `requirements/spec-simulation.md` — "would-passing-yield-a-working-system" method. *(simulate-contracts)* +- [ ] `software-craft/design-patterns.md` — implementation patterns. *(implement-from-stub)* +- [ ] `software-craft/refactoring-techniques.md` — refactoring moves. *(refactor-green)* +- [ ] `software-craft/versioning.md` — release/tag policy. *(publish-release)* ## pyproject + tooling -- [ ] Wire `stubtest` task targets once the package name is finalized (currently - uses the stale `app` placeholder, consistent with `[tool.setuptools]` / - `--cov=app` / `static-check = "pyright app tests"`). -- [ ] Drop `beehave` / `pytest-beehave` deps + `[tool.beehave]` (feature-file - stubbing no longer used); keep `flowr`, `pytest`. -- [ ] Strip stale `[tool.setuptools] packages = ["app"]`, `--cov=app`, - `requires-python>=3.14`, taskipy/pdoc/hypothesis/pyright/safety until - decided. +- [ ] `[project].readme = "README.md"` and `[project.urls]` reference files deleted in the clean-slate commit (README.md, `docs/api/`) — pyproject points at ghosts. Author a fresh README + drop stale URLs, or remove the fields. +- [ ] Reset `version` and `description` (still "9.4.0" / "Spec-driven ... BDD traceability" — pre-clean-slate). +- [ ] Two dev-dependency sections overlap and diverge: `[project.optional-dependencies].dev` vs `[dependency-groups].dev` (the latter carries `flowr[viz]` + `pytest-beehave[html]`). Consolidate to one; decide `uv run --extra dev` vs `uv sync --group dev`. +- [ ] `conventions` task selects `ANN` (flake8-annotations) which flags the un-annotated `conftest.py` hook and diverges from `ruff check .` (main select has no ANN). Reconcile — drop `ANN` from `conventions`, or drop the `conventions` task in favour of `ruff check .`. +- [ ] Wire `stubtest` / `static-check` / coverage (`--cov`) / `doc-serve` / `doc-build` / `run` tasks to the real package once named (all target the stale `app` placeholder, matching `[tool.setuptools] packages = ["app"]`). +- [ ] Drop `beehave` / `pytest-beehave` deps + `[tool.beehave]` (feature-file stubbing is gone); keep `flowr`, `pytest`. +- [ ] Decide `requires-python` (currently `>=3.14`). - [ ] Decide task runner: `taskipy` vs plain `uv run`. ## Package + tests skeleton @@ -271,6 +279,10 @@ Raw material lives in `.backup/.opencode/knowledge/`; restore selectively and re - [ ] External-adapter cassettes — recorded in explore; replayed in tests. - [ ] `docs/glossary.md` — ubiquitous language; drives naming (from template). +## Docs +- [ ] `README.md` — author a fresh one for the rebuild (deleted in clean-slate; pyproject references it). +- [ ] `CHANGELOG.md` — decide whether to maintain (deleted; `publish-release` implies one may be wanted). + ## Docs-as-derived - [ ] Decide the derivation mechanism (tool? extraction script? manual?) that regenerates docs/specs from the green suite. From 2cfbb912febc55c9e6ebcefa19b59c981abba5f8 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 15:49:51 -0400 Subject: [PATCH 03/28] feat(knowledge): DDD building-blocks model + feature->building-block rename Author the DDD decomposition knowledges and retitle the funnel's third level off the product term "feature" onto the DDD term "building block". - Add requirements/domain-decomposition.md (aggregate-first decomposition, gap analysis as coverage matrix) and requirements/aggregate-boundaries.md (sizing/splitting aggregates); repoint citations in interview-techniques and the interview/review skills - Rename interview-features -> interview-building-blocks: state, skill, trigger (building-blocks-done, aligned with general/cross-cutting-done), description ("Tactical decomposition"); drop the contradictory L2 step - Reframe agent identities off "feature" -> "building block" across domain-expert, product-owner, reviewer, release-engineer - discovery-flow 2.1.0 -> 2.2.0 - derive-source-stubs input: test .pyi -> test .py (bodies hold the domain types the stubs are derived from) - Rationalize working-state paths: probe scripts explore/ -> .cache/explore/ (consolidates gitignored working state); rewrite .gitignore lean and project-only; add a Project layout section to AGENTS.md --- .flowr/flows/discovery-flow.yaml | 15 +- .flowr/flows/explore-flow.yaml | 6 +- .flowr/flows/pipeline-flow.yaml | 2 +- .flowr/flows/plan-flow.yaml | 6 +- .gitignore | 190 ++---------------- .opencode/agents/domain-expert.md | 2 +- .opencode/agents/product-owner.md | 6 +- .opencode/agents/release-engineer.md | 2 +- .opencode/agents/reviewer.md | 2 +- .../requirements/aggregate-boundaries.md | 149 ++++++++++++++ .../requirements/domain-decomposition.md | 164 +++++++++++++++ .../requirements/interview-techniques.md | 6 +- .opencode/skills/derive-source-stubs/SKILL.md | 2 +- .../skills/interview-building-blocks/SKILL.md | 11 + .opencode/skills/interview-features/SKILL.md | 12 -- .opencode/skills/review-test-stubs/SKILL.md | 4 +- AGENTS.md | 25 +++ TODO.md | 60 +++--- 18 files changed, 427 insertions(+), 237 deletions(-) create mode 100644 .opencode/knowledge/requirements/aggregate-boundaries.md create mode 100644 .opencode/knowledge/requirements/domain-decomposition.md create mode 100644 .opencode/skills/interview-building-blocks/SKILL.md delete mode 100644 .opencode/skills/interview-features/SKILL.md diff --git a/.flowr/flows/discovery-flow.yaml b/.flowr/flows/discovery-flow.yaml index 01fb64cd..c0778661 100644 --- a/.flowr/flows/discovery-flow.yaml +++ b/.flowr/flows/discovery-flow.yaml @@ -1,5 +1,5 @@ flow: discovery-flow -version: 2.1.0 +version: 2.2.0 exits: - interview-ready states: @@ -32,23 +32,24 @@ states: output artifacts: - ".cache//interview-notes.md" next: - cross-cutting-done: interview-features + cross-cutting-done: interview-building-blocks - - id: interview-features + - id: interview-building-blocks attrs: description: > - Funnel level 3 - Feature identification. Capture feature NAMES and rough - boundaries only; run gap analysis; append to the interview-notes. + Funnel level 3 - Tactical decomposition. Capture building-block NAMES + and rough boundaries only; run gap analysis; append to the + interview-notes. dispatch_to: product-owner specialists: [domain-expert] git branch: dev - skills: [interview-features] + skills: [interview-building-blocks] input artifacts: - ".cache//interview-notes.md" output artifacts: - ".cache//interview-notes.md" next: - features-identified: consolidate-interview + building-blocks-done: consolidate-interview - id: consolidate-interview attrs: diff --git a/.flowr/flows/explore-flow.yaml b/.flowr/flows/explore-flow.yaml index b6cba00e..51921717 100644 --- a/.flowr/flows/explore-flow.yaml +++ b/.flowr/flows/explore-flow.yaml @@ -1,5 +1,5 @@ flow: explore-flow -version: 1.4.0 +version: 1.5.0 exits: - explored-ready - needs-elicitation @@ -52,7 +52,7 @@ states: input artifacts: - ".cache//probe-research.md" output artifacts: - - "explore/**" + - ".cache/explore/**" next: probe-written: record-cassette @@ -67,7 +67,7 @@ states: skills: [record-cassette] input artifacts: - ".cache//probe-research.md" - - "explore/**" + - ".cache/explore/**" output artifacts: - "tests/cassettes/**" - ".cache//external-contracts.md" diff --git a/.flowr/flows/pipeline-flow.yaml b/.flowr/flows/pipeline-flow.yaml index 556efd35..5ef7bfcd 100644 --- a/.flowr/flows/pipeline-flow.yaml +++ b/.flowr/flows/pipeline-flow.yaml @@ -6,7 +6,7 @@ states: - id: discover attrs: description: > - Run the interview funnel (general -> cross-cutting -> features -> + Run the interview funnel (general -> cross-cutting -> building-blocks -> consolidate) to elicit requirements and author the glossary. Emits interview notes and glossary only - no tests, source, or external contracts. diff --git a/.flowr/flows/plan-flow.yaml b/.flowr/flows/plan-flow.yaml index 0eb300db..5d2590d8 100644 --- a/.flowr/flows/plan-flow.yaml +++ b/.flowr/flows/plan-flow.yaml @@ -1,5 +1,5 @@ flow: plan-flow -version: 1.4.0 +version: 1.5.0 exits: - contracts-ready - needs-elicitation @@ -82,8 +82,8 @@ states: git branch: dev skills: [derive-source-stubs] input artifacts: - - "tests/integration/**/*_test.pyi" - - "tests/e2e/**/*_test.pyi" + - "tests/integration/**/*_test.py" + - "tests/e2e/**/*_test.py" output artifacts: - "/**/*.pyi" next: diff --git a/.gitignore b/.gitignore index 185d4b37..763cee82 100644 --- a/.gitignore +++ b/.gitignore @@ -1,186 +1,36 @@ -.DS_Store -*.swp -.coverage -.vscode/ -.idea/ -# Byte-compiled / optimized / DLL files +# Python bytecode & packaging __pycache__/ *.py[cod] -*$py.class - -# Generated documentation (built by task doc-build) -docs/api/ -docs/coverage/ -docs/tests/ -mutants - -# C extensions -*.so - -# Distribution / packaging -.Python +*.egg-info/ build/ -develop-eggs/ dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec +# Virtual environment +.venv/ -# Installer logs -pip-log.txt -pip-delete-this-directory.txt +# Tool caches +.mypy_cache/ +.pytest_cache/ +.ruff_cache/ +.hypothesis/ -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ +# Coverage .coverage .coverage.* -.cache -nosetests.xml +htmlcov/ coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/#use-with-ide -.pdm.toml - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments +# 12-factor config (local secrets — never commit) .env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ -.mutmut-cache - -# Session files and simulation cache (local working state) +# Local working state (flowr sessions, interview/explore/build notes, throwaway probe scripts) .cache/ -# Explore-flow throwaway probe scripts (captured cassettes ARE committed under tests/cassettes/) -explore/ - -# Generated flow visualization data (regenerate with: task regenerate-flowviz) -.flowr/viz/data.js - -# Trigger CI run to verify linting fixes - -# Local-only backup of the previous system (clean-slate rebuild) +# Local backup of the previous system (clean-slate rebuild; recoverable from origin/main) .backup/ + +# Editor / OS +.vscode/ +.idea/ +.DS_Store +*.swp diff --git a/.opencode/agents/domain-expert.md b/.opencode/agents/domain-expert.md index cd14838e..69c501c8 100644 --- a/.opencode/agents/domain-expert.md +++ b/.opencode/agents/domain-expert.md @@ -13,7 +13,7 @@ You are the Domain Expert. Your lens is the real-world semantics the software mo - Words carry meaning that survives the code. A term used loosely in the model becomes a liability the day it misleads a decision, a user, or a regulator. - The interesting cases are the ones the happy path hides. The boundary, the exception, the rare-but-critical, the seasonally-recurring — these are where the generic model fails and domain knowledge earns its place. - Constraints in a domain are often legal, not technical. Where a rule exists because the law or the industry demands it, the system must honor it even when a cleaner abstraction beckons. -- The cost of a wrong term compounds. A model built on a misunderstood concept infects every feature that inherits it. +- The cost of a wrong term compounds. A model built on a misunderstood concept infects every building block that inherits it. ## What you decide diff --git a/.opencode/agents/product-owner.md b/.opencode/agents/product-owner.md index 0e7d229e..ee6ac8a2 100644 --- a/.opencode/agents/product-owner.md +++ b/.opencode/agents/product-owner.md @@ -11,9 +11,9 @@ You are the Product Owner. Your lens is the requirement itself — the stakehold ## What you hold - The requirement is what the stakeholder can articulate and verify, not what is convenient to build. You climb from concrete past incidents to writable constraints rather than accepting vague wishes. -- Scope is a budget. Every feature earns its place by mapping to an interviewed need; anything else is deferred, no matter how easy or impressive. +- Scope is a budget. Every building block earns its place by mapping to an interviewed need; anything else is deferred, no matter how easy or impressive. - The ubiquitous language belongs to the stakeholder. You record their terms, you do not impose the team's jargon, and you let those terms lead all later naming. -- Ordering is value- and risk-weighted, then constrained by dependency layer: you never let a flashy feature leapfrog a foundation it secretly depends on. +- Ordering is value- and risk-weighted, then constrained by dependency layer: you never let a flashy building block leapfrog a foundation it secretly depends on. ## What you decide @@ -21,6 +21,6 @@ You alone decide what is in scope and which source contract builds next. ## What you refuse -- You refuse to invent requirements the interview did not surface, or to let a feature survive without a trace back to a stated need. +- You refuse to invent requirements the interview did not surface, or to let a building block survive without a trace back to a stated need. - You refuse to broaden scope by stealth; a change in scope is an explicit, recorded decision. - You refuse to prioritize by technical interest alone — "interesting to build" is not a priority signal. diff --git a/.opencode/agents/release-engineer.md b/.opencode/agents/release-engineer.md index 025c750c..44396dc9 100644 --- a/.opencode/agents/release-engineer.md +++ b/.opencode/agents/release-engineer.md @@ -6,7 +6,7 @@ temperature: 0.3 # Release Engineer -You are the Release Engineer. Your lens is the path from a green build to a shipped product — reproducible, gated, and reversible. Where others think about making a feature work, you think about the cost of putting it in front of users and the cost of pulling it back. +You are the Release Engineer. Your lens is the path from a green build to a shipped product — reproducible, gated, and reversible. Where others think about making a building block work, you think about the cost of putting it in front of users and the cost of pulling it back. ## What you hold diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index f99aa607..fa520c89 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -13,7 +13,7 @@ You are the Reviewer. Your lens is the gap between a claim and its evidence. Whe - Verification is adversarial by design. You trust nothing the author asserts; you re-derive it from the artifacts and the criteria. - A gate is passed only when each criterion is met with evidence, not when nothing obviously broke. Silence is not acceptance; the absence of a found defect is not proof of correctness. - The right failure is as informative as a pass. A red that fails for the right reason, a stub that is honestly inconsistent — these are correct states; you do not paper over them. -- Scope is a criterion too. A state that does more or less than its contract — unit tests leaking into an integration-only gate, a feature unrooted in the interview — fails review even if the code is clean. +- Scope is a criterion too. A state that does more or less than its contract — unit tests leaking into an integration-only gate, a building block unrooted in the interview — fails review even if the code is clean. ## What you decide diff --git a/.opencode/knowledge/requirements/aggregate-boundaries.md b/.opencode/knowledge/requirements/aggregate-boundaries.md new file mode 100644 index 00000000..7c370e25 --- /dev/null +++ b/.opencode/knowledge/requirements/aggregate-boundaries.md @@ -0,0 +1,149 @@ +--- +domain: requirements +tags: [aggregate, consistency-boundary, sizing, splitting, ddd] +last-updated: 2026-07-01 +--- + +# Aggregate Boundaries + +## Key Takeaways + +- An aggregate is a **transactional-consistency boundary**: one root entity, its + internal objects, and the invariants the root enforces. One transaction + touches one aggregate (Evans, 2003). +- **Design smaller aggregates** (Vernon, 2013): favour single-entity + aggregates. Large aggregates breed contention, latency, and false coupling. +- **Reference other aggregates by identity**, never by object reference. It + keeps boundaries firm and lets consistency across aggregates be eventual. +- **Split when** a candidate holds two unrelated invariants, serves two + contexts, or changes in ways that never co-occur. The seam is where + transactional consistency *ends*. +- **Do not split when** invariants genuinely cross and always co-change (shared + kernel, tightly-coupled siblings). Size follows the invariant, not the noun. + +## Concepts + +An *aggregate* is the unit of transactional consistency. Evans (2003, ch 4) +defines it as a cluster of domain objects treated as one for data changes: a +single *root entity* is the only member referenced from outside, and the root is +responsible for enforcing the cluster's invariants. Everything that must be true +*together*, at the end of one transaction, lives inside one aggregate; +everything else is outside. + +*Smaller is better* is Vernon's (2013) first rule of aggregate design. The +temptation is to group everything that "belongs together" into one big +aggregate; the cost is contention (many transactions serialise on one root), +latency (locking a large object graph), and false coupling (two unrelated +reasons to change, fused). A single-entity aggregate — root alone, no internals +— is the safe default; internals are added only when an invariant demands them. + +*Reference by identity* is the boundary-firmness rule. Aggregates reference each +other by identity (a foreign key on the root), never by holding an object +reference to another aggregate's internals. This keeps the consistency boundary +honest — you cannot accidentally traverse into another transaction's state — +and it makes eventual consistency between aggregates natural. + +*Splitting* answers "is this one aggregate or two?" The test is the invariant: +if two parts have unrelated invariants, serve different contexts, or change in +ways that never co-occur, they are two aggregates. The seam is precisely where +transactional consistency stops being required. + +*Not splitting* answers the same question the other way. Some candidates look +like two aggregates but have invariants that genuinely cross and always +co-change — a shared kernel, or two small siblings whose state is meaningless +apart. There, one aggregate spanning both is correct. Size follows the +invariant, not the noun. + +## Content + +### What an aggregate is + +Evans (2003, ch 4): an aggregate is a cluster of associated objects treated as a +unit for data changes. It has: + +- a single **aggregate root** — an entity referenced from outside; +- **internal objects** — entities and value objects reachable only through the + root; +- **invariants** — consistency rules the root enforces across the cluster. + +Outside code holds references only to the root; the root controls all access to +internals. A transaction loads one aggregate through its root, mutates it, and +the root validates the invariants before commit. One transaction, one +aggregate — this is what makes the boundary a *consistency* boundary. + +### Size: smaller is better + +Vernon (2013, ch 10) makes aggregate sizing the central design decision and +argues, against intuition, for **small** aggregates. The forces: + +- **Contention**: every transaction that touches the aggregate locks its root. + A large aggregate is a serialisation point many transactions fight over. +- **Latency**: loading a large object graph, and validating invariants across + it, costs more than loading a small one. +- **False coupling**: two unrelated reasons to change, fused in one root, break + the single-responsibility property and make every change riskier. + +A **single-entity aggregate** (root alone, no internal objects) is Vernon's +preferred default. Internal objects are added only when an invariant genuinely +spans them — when two parts must be consistent *together* within one +transaction. The rates-sim *Conversion* is a single-entity aggregate: the root +holds the amount, source, target, and result, and no invariant requires a +larger cluster. + +### Referencing other aggregates + +Aggregates reference each other **by identity**, not by object reference. A root +holds the identity (a value-object id or a foreign key) of another aggregate, +never a pointer to its internals. Three reasons: + +- **Boundary integrity**: there is no way to traverse into another aggregate's + state mid-transaction; the consistency boundary cannot be accidentally + punctured. +- **Independence**: each aggregate can be loaded, locked, and committed without + loading the other. +- **Eventual consistency**: changes that span aggregates are propagated by + events, not by one transaction mutating two roots — so the system stays + available under partition. + +The rates sim keeps *History* (a repository) separate from the *Conversion* +aggregate: History references conversions by identity and persists them, it does +not enlarge the aggregate. + +### When to split + +A candidate is two aggregates when any of these holds: + +- **Two unrelated invariants** — the cluster enforces two rules that share no + state; each rule could hold independently. +- **Two contexts** — the candidate serves two bounded contexts, and the + ubiquitous language differs across them. +- **Non-co-occurring change** — the two parts are changed by different + operations and never in the same transaction. + +The seam is where transactional consistency *stops being required*. Everything +inside the seam must be consistent together in one transaction; everything +outside can be eventually consistent. Splitting along the seam keeps each +aggregate a true consistency boundary rather than an arbitrary grouping. + +### When not to split + +A candidate that *looks* like two aggregates may be one, when: + +- **A shared invariant genuinely crosses** both parts — one rule spans them and + must hold at every commit, so they cannot be separated without losing + consistency. +- **Tightly-coupled siblings** — two small objects whose state is meaningless + apart (a line item without its parent, an address without its owner). +- **A shared kernel** — a small, deliberately shared model that two contexts + agree to co-own. + +The rule is the same in both directions: **size follows the invariant, not the +noun**. If an invariant binds the parts, they are one aggregate; if it does not, +they are two. + +## Related + +- [[requirements/domain-decomposition]] — discovering the blocks whose sizes + this file governs. +- [[requirements/ubiquitous-language]] — the terms a context owns, which the + aggregate root expresses. diff --git a/.opencode/knowledge/requirements/domain-decomposition.md b/.opencode/knowledge/requirements/domain-decomposition.md new file mode 100644 index 00000000..577a8a58 --- /dev/null +++ b/.opencode/knowledge/requirements/domain-decomposition.md @@ -0,0 +1,164 @@ +--- +domain: requirements +tags: [domain-decomposition, bounded-context, aggregate, gap-analysis, coverage] +last-updated: 2026-07-01 +--- + +# Domain Decomposition + +## Key Takeaways + +- The build unit is a **DDD building block** — primarily an **aggregate** (the + transactional-consistency core), with domain services, application services, + repositories, anti-corruption layers, and value objects as supporting blocks. + It is coarser than an entity, an operation, or a test (those are downstream). +- Capture **names + rough boundaries only** — coarse-then-detailed. The spec + (signatures, invariants, types) is deferred to plan and build (Patton, 2014). +- Decompose along **bounded-context borders**: each block belongs to one + context; a candidate straddling two contexts is two blocks, or signals a + missing context. Sizing and splitting rules live in + [[requirements/aggregate-boundaries]] (Evans, 2003; Vernon, 2013). +- **Gap analysis is a coverage matrix**: every bounded context → ≥1 block; every + quality attribute → ≥1 block that carries it (Wiegers, *Software + Requirements*, 2nd ed). An empty row is a gap; a dense cell is a block doing + too much. +- **Flag gaps, do not fill them** — a gap is a detection signal, not an + authoring trigger. Escalate to elicitation; preserve trace-to-stakeholder. + +## Concepts + +A *building block* is the unit a context is built from. Evans (2003, Part II) +names the set: entities, value objects, domain services, repositories, +factories, and — binding them — aggregates. Of these, the **aggregate** is the +load-bearing one: it is the only block that owns transactional consistency, so +identifying aggregates is the centre of gravity of decomposition. Services, +repositories, and anti-corruption layers exist to support aggregates or bridge +contexts; value objects are leaves. A block is a *capability* ("rate +conversion"), never a *mechanism* ("RatesRepository"). + +*Coarse-then-detailed* governs the grain at which blocks are captured. Patton +(2014) makes the same point for stories — they are *discovered*, not authored +upfront. At this level a block is a name and a rough boundary; its operations, +invariants, and types arrive later, in the test stubs of plan and the +implementation of build. + +The *bounded context* is the decomposition boundary. Inside one context a +ubiquitous-language term has exactly one meaning (Evans, 2003); a block is owned +by exactly one context. A candidate that genuinely serves two contexts is two +blocks, or evidence that the context map is wrong. How big each block is — the +consistency boundary — is the separate question answered in +[[requirements/aggregate-boundaries]]. + +*Gap analysis* reframes completeness as coverage, following the requirements +traceability matrix (Wiegers, *Software Requirements*, 2nd ed; Gotel & +Cleland-Huang, 2012). Two kinds of row must each map to at least one block: +bounded contexts (does every context have something living in it?) and quality +attributes (is every non-functional concern — performance, security, +auditability — carried by some block?). Quality attributes are not themselves +blocks; they are concerns a block must satisfy. + +*Flag, don't fill* keeps decomposition honest. A gap means the interview did +not surface enough — the response is to elicit more, not to invent a block to +fill the cell. Filling silently destroys traceability: a fabricated block has no +stakeholder and no CIT anchor. + +## Content + +### What a block is — and aggregate-first + +Evans (2003) Part II lays out the building blocks of a model-driven design: +**entities** (identity-defined), **value objects** (immutable, compared by +value), **services** (stateless operations that belong to no one entity), +**repositories** (abstract the persistence of an aggregate), **factories** +(encapsulate construction), and **modules** (the code-level partition). Chapter +4 introduces the **aggregate**: a cluster treated as a single unit for data +changes, with one root entity that enforces the cluster's invariants. + +Aggregate-first means: when decomposing a context, look for the +transactional-consistency cores first. Ask "what must be true, together, at the +end of one transaction?" — that invariant cluster is an aggregate. Everything +else arranges itself around the aggregates: repositories persist them, +anti-corruption layers translate foreign concepts into them, application +services orchestrate them, value objects describe their leaves. The rates sim +illustrates the mix: a *Conversion* aggregate (root + invariant), a +*RatesAdapter* anti-corruption layer, a *Settings* value object, a *convert* +application service. Naming a block as a capability — "rate conversion" — keeps +the door open to its eventual tactical shape; naming it as a mechanism — +"RatesRepository" — prematurely fixes it. + +### Coarse-then-detailed: names before spec + +Patton (2014) describes a two-dimensional map: a *backbone* of user activities +above, with stories beneath as one-line titles, refined gradually and sliced +horizontally into releases. The same shape governs blocks: the bounded contexts +form the backbone, and the blocks are the titles beneath them. At this level a +block is captured as a **name and a rough boundary** — what context it lives in, +what it neighbours, roughly what it is responsible for. Its operations, +invariants, parameter types, and return types are *not* designed here; they are +expressed in the test stubs (plan) and fixed in the implementation (build). +"Stories are discovered, not written" (Patton, 2014) — blocks are elicited from +the interview, not architected at the whiteboard. + +### The bounded context as decomposition unit + +Evans (2003) defines a bounded context as the boundary within which a +ubiquitous-language term has exactly one meaning. Vernon (2013) sharpens the +alignment: a context maps to a business capability, a transactional boundary, +and — often — a team. A block is owned by exactly one context. When a candidate +spans two contexts, one of two things is true: it is two blocks (one per +context, possibly linked by identity or a context-map relationship), or the +contexts are mis-drawn and should merge or be re-mapped. The consistency +boundary *within* a context — how big each aggregate is, when to split — is the +subject of [[requirements/aggregate-boundaries]]. + +Brandolini (2012) offers an alternative lens on the same boundary: **Event +Storming**. Domain events are placed on a timeline first; clusters of events +surface bounded contexts and aggregates collaboratively, and the commands +attached to events reveal intent. The boundary is the same; the entry point +(events, not nouns) is different. Either lens is a valid way to find the blocks +of a context. + +### Gap analysis as a coverage matrix + +Wiegers (*Software Requirements*, 2nd ed) frames requirements traceability as a +matrix that links each requirement forward to the design and test elements that +realise it. Gotel & Cleland-Huang (2012) generalise: a traceability matrix +correlates two baselined artefacts many-to-many; cells are marked where a +relationship exists. + +Applied to decomposition, the matrix has two row kinds and one column kind: + +| | block A | block B | block C | +|---|---|---|---| +| **bounded context: pricing** | × | | | +| **bounded context: billing** | | × | | +| **quality attribute: auditability** | | × | × | +| **quality attribute: performance** | × | | | + +A **bounded context** row asks: does something live here? A **quality +attribute** row asks: is this non-functional concern (security, performance, +auditability, ...) carried by at least one block? Quality attributes are not +blocks themselves; they are concerns a block must satisfy. An **empty row** — a +context or quality with no block — is a gap. A **dense cell** — one block +carrying many concerns — is a signal the block is over-complex and may need +splitting (see [[requirements/aggregate-boundaries]]). Build the matrix as you +go, not reconstructed at the end (Gotel & Cleland-Huang, 2012). + +### Flag, do not fill + +A gap in the coverage matrix is a detection, not a work item. The honest +response is to return to elicitation — the funnel's earlier levels, or another +interview pass — and surface the missing block or quality from the stakeholder. +Inventing a block to fill the cell destroys the property that makes the matrix +trustworthy: every block traces back to a stakeholder need and a CIT-anchored +interview finding. A fabricated block has neither, and it will drift the moment +it is built. + +## Related + +- [[requirements/aggregate-boundaries]] — sizing and splitting the blocks + identified here. +- [[requirements/ubiquitous-language]] — the shared language a bounded context + bounds. +- [[requirements/interview-techniques]] — CIT, Laddering, and the Active + Listening protocol that surface blocks. diff --git a/.opencode/knowledge/requirements/interview-techniques.md b/.opencode/knowledge/requirements/interview-techniques.md index 410f9b11..8fbf8f6e 100644 --- a/.opencode/knowledge/requirements/interview-techniques.md +++ b/.opencode/knowledge/requirements/interview-techniques.md @@ -40,7 +40,7 @@ Ask about a specific past event, not a general description. ### Laddering / Means-End Chain (Reynolds & Gutman, 1988) -Climb from surface feature to underlying consequence to terminal value. +Climb from surface attribute to underlying consequence to terminal value. - "Why is that important to you?" - "What does that enable?" @@ -70,5 +70,5 @@ Do not introduce topic labels during active listening; the summary reflects what ## Related - [[requirements/ubiquitous-language]] — term extraction feeding the glossary authored at consolidation -- [[requirements/feature-discovery]] — gap analysis applied at feature identification -- [[requirements/feature-boundaries]] — sizing feature boundaries +- [[requirements/domain-decomposition]] — gap analysis applied at building-block identification +- [[requirements/aggregate-boundaries]] — sizing block boundaries diff --git a/.opencode/skills/derive-source-stubs/SKILL.md b/.opencode/skills/derive-source-stubs/SKILL.md index 41879ea2..9454198a 100644 --- a/.opencode/skills/derive-source-stubs/SKILL.md +++ b/.opencode/skills/derive-source-stubs/SKILL.md @@ -6,7 +6,7 @@ description: "Derive the source stub files (.pyi) from the reviewed tests — ev # Derive Source Stubs 1. Load [[software-craft/source-stubs]] — source stub conventions and the canonical data-shape rule. -2. Read the test .py imports, parameter types, and return types: they are the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. +2. Read the test .py imports and bodies — every type constructed, method called, and relationship asserted in a body is the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. 3. Do not prescribe layout — no hardcoded module structure. External connector and adapter stubs are not a separate category; they live under the package alongside everything else. 4. Handle config by 12-factor: environment variables are the default, with dotenv loading a gitignored `.env` for local secrets. A typed Settings model is optional and, if warranted, is a normal source stub. 5. IF a value's representation is ambiguous (e.g. a database URL passed as bare string) THEN pin one canonical form once (the `sqlite:///path` URL form) and state it in the stub so every consumer agrees per [[software-craft/source-stubs]]. diff --git a/.opencode/skills/interview-building-blocks/SKILL.md b/.opencode/skills/interview-building-blocks/SKILL.md new file mode 100644 index 00000000..c6aae997 --- /dev/null +++ b/.opencode/skills/interview-building-blocks/SKILL.md @@ -0,0 +1,11 @@ +--- +name: interview-building-blocks +description: "Funnel level 3 — identify building-block names and rough boundaries only, and run gap analysis." +--- + +# Interview (Building Blocks) + +1. Load [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]] — gap analysis and boundary sizing. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). +2. Read the running interview-notes; append the building-block names and boundaries to it. +3. Capture building-block NAMES and rough boundaries ONLY — no detailed spec (rules, examples, criteria come later in planning). The purpose is to know WHAT building blocks exist, not to specify each. +4. Run gap analysis: IF a bounded context from cross-cutting maps to no block THEN flag the gap; IF a quality attribute maps to no block THEN flag the gap. Do not silently fill gaps per [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]]. diff --git a/.opencode/skills/interview-features/SKILL.md b/.opencode/skills/interview-features/SKILL.md deleted file mode 100644 index 74024bd9..00000000 --- a/.opencode/skills/interview-features/SKILL.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: interview-features -description: "Funnel level 3 — identify feature names and rough boundaries only, and run gap analysis." ---- - -# Interview (Features) - -1. Load [[requirements/feature-discovery]], [[requirements/feature-boundaries]] — gap analysis and boundary sizing. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). -2. Read the running interview-notes; append the feature names and boundaries to it. -3. Capture feature NAMES and rough boundaries ONLY — no detailed spec (rules, examples, criteria come later in planning). The purpose is to know WHAT features exist, not to specify each. -4. Run gap analysis: IF a bounded context from cross-cutting maps to no feature THEN flag the gap; IF a quality attribute maps to no feature THEN flag the gap. Do not silently fill gaps per [[requirements/feature-discovery]], [[requirements/feature-boundaries]]. -5. Continue Active Listening L2 between features. diff --git a/.opencode/skills/review-test-stubs/SKILL.md b/.opencode/skills/review-test-stubs/SKILL.md index d78ea884..e44028d8 100644 --- a/.opencode/skills/review-test-stubs/SKILL.md +++ b/.opencode/skills/review-test-stubs/SKILL.md @@ -5,8 +5,8 @@ description: "Review the test stubs for coverage, scope, and happy-path complete # Review Test Stubs -1. Load [[software-craft/code-review]], [[requirements/feature-discovery]] — review method and gap analysis. +1. Load [[software-craft/code-review]], [[requirements/domain-decomposition]] — review method and gap analysis. 2. Treat this review as coverage and scope against requirements, not code quality — quality is gated later on the bodies. 3. Check consistency: every stub maps to an interview requirement and uses the glossary's ubiquitous language; external-layer stubs match the captured cassettes. 4. Check scope: integration and E2E only; IF a unit test leaked in THEN reject it. -5. Check happy-path completeness: the stub set, once implemented, would exercise the full happy paths of every identified feature. IF a feature or quality attribute maps to no stub THEN flag the gap per [[requirements/feature-discovery]]. +5. Check happy-path completeness: the stub set, once implemented, would exercise the full happy paths of every identified building block. IF a building block or quality attribute maps to no stub THEN flag the gap per [[requirements/domain-decomposition]]. diff --git a/AGENTS.md b/AGENTS.md index c27a6e61..7c8bffbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,31 @@ external services → vcrpy cassettes) → `plan` (author test `.pyi` → review `plan` on a contract gap; `plan` and `explore` escalate to `discover` when the interview itself is insufficient. See `TODO.md` for what's owed. +## Project layout + +Committed (the source of truth): + +| Path | Holds | +|------|-------| +| `/` | source — `.pyi` stubs + `.py` bodies | +| `tests/integration/`, `tests/e2e/` | integration + E2E tests only (no unit) | +| `tests/cassettes/` | recorded vcrpy cassettes — the external contract | +| `tests/fixtures/` | test fixtures | +| `migrations/` | Alembic migrations — the schema spec | +| `docs/glossary.md` | ubiquitous language | +| `.flowr/flows/` | flow definitions | +| `.opencode/`, `.templates/`, `.github/` | methodology, templates, CI | + +Gitignored (local working state, regenerated on demand): + +| Path | Holds | +|------|-------| +| `.cache//` | interview notes, external contracts, probe research, build target | +| `.cache/explore/` | throwaway probe scripts (run once to record cassettes; never imported) | +| `.cache/sessions/` | flowr session state | +| `.backup/` | previous system (recoverable from `origin/main`) | +| `.env` | local config (12-factor) | + ## Agents, skills & knowledge The methodology layer lives under `.opencode/` (not loaded every session — diff --git a/TODO.md b/TODO.md index 4e272636..17eb12bd 100644 --- a/TODO.md +++ b/TODO.md @@ -16,7 +16,7 @@ one commit. Flow: `pipeline-flow` orchestrates five subflows. - `discovery-flow`: `interview-general → interview-cross-cutting → - interview-features → consolidate-interview` (exit `interview-ready`). + interview-building-blocks → consolidate-interview` (exit `interview-ready`). - `explore-flow`: `select-external-target → research-provider → write-probe → record-cassette` (loop, one service per pass; exits `explored-ready`, `needs-elicitation`). @@ -49,9 +49,9 @@ Sequence (the authoritative development order): 2. **interview-cross-cutting** *(discover)* — Funnel L2: behaviour groups, bounded contexts, integration points, lifecycle events; active listening L2 (synthesis per group). Appends to interview-notes. -3. **interview-features** *(discover)* — Funnel L3: feature names + rough +3. **interview-building-blocks** *(discover)* — Funnel L3: building-block names + rough boundaries only (no detailed spec); gap analysis (every context / quality - attribute → ≥1 feature). Appends to interview-notes. + attribute → ≥1 building block). Appends to interview-notes. 4. **consolidate-interview** *(discover)* — active listening L3: full synthesis → stakeholder approval; author `docs/glossary.md`. Exit `interview-ready`. 5. **explore external services** *(explore)* — a four-state loop, one external @@ -64,7 +64,7 @@ Sequence (the authoritative development order): until docs are read), determines the access shape, and recommends the ≤1 advisory specialist (→ `.cache//probe-research.md`). `write-probe` authors the minimal probe script (success + ≥1 error) under - `explore//` (gitignored throwaway). `record-cassette` runs the + `.cache/explore//` (gitignored throwaway). `record-cassette` runs the probe, RECORDS the real exchange into `tests/cassettes//` with decode + secret/volatile scrubbing, and appends `.cache//external-contracts.md`; then `captured` back to @@ -84,7 +84,7 @@ Sequence (the authoritative development order): not BDD features. No `.py` yet. 7. **review-test-stubs** *(plan)* — gate: consistency vs interview + ubiquitous language (external stubs match the cassettes); scope is integration + E2E - only; happy-path completeness (every feature → ≥1 stub). Not a code-quality + only; happy-path completeness (every building block → ≥1 stub). Not a code-quality gate (that's next). 8. **write-test-py** *(plan)* — transform the reviewed stubs into `tests/**/*_test.py` bodies (no docstrings, no comments). Bodies define how @@ -141,7 +141,7 @@ Design decisions: loaded by each of the four `interview-*` skills (one skill per funnel state). - Explore produces two sharply separated artifacts: committed vcrpy cassettes (`tests/cassettes/**` — the authoritative external contract, replayed by - tests/CI offline) and gitignored throwaway probe scripts (`explore/` — + tests/CI offline) and gitignored throwaway probe scripts (`.cache/explore/` — reference for the green implementer, never imported by `` or tests). Capture needs real 12-factor credentials; CI never runs explore, it replays the cassettes. @@ -224,33 +224,35 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [ ] Escalations re-enter subflows at the FIRST state (flowr has no position memory); rework re-runs the whole chain and full gates. Document the cost or accept it. ## Knowledge to author (Stage 3 — derived from the skills' `[[...]]` citations) -18 distinct knowledge files cited across the 21 skills. Re-derived from `.opencode/skills/`; priority = citation count (most-cited first = highest leverage to author). Raw material lives in `.backup/.opencode/knowledge/` — restore selectively and rewrite (the backup is beehave-stale; do NOT bulk-copy). Skills' forward-ref wikilinks resolve once these exist; track as debt until authored. +18 distinct knowledge files cited across the 21 skills. Ordered by LIFECYCLE — the sequence in which an agent meets them as a session runs (discover → explore → plan → build → deliver); each appears once, at its first encounter. Raw material lives in `.backup/.opencode/knowledge/` — restore selectively and rewrite (the backup is beehave-stale; do NOT bulk-copy). Skills' forward-ref wikilinks resolve once these exist; track as debt until authored. -**Cited by 4 skills:** -- [x] `requirements/interview-techniques.md` — CIT, Laddering, CI Perspective, Funnel, Active Listening L1/L2/L3. *(interview-general, interview-cross-cutting, interview-features, consolidate-interview)*. AUTHORED. +**Discover (interview funnel):** +- [x] `requirements/interview-techniques.md` — Elicitation methods (CIT, Laddering/Means-End, CI Perspective Change, Funnel, Active Listening L1-L3) applied at each funnel depth. *(interview-general, interview-cross-cutting)*. AUTHORED. +- [x] `requirements/domain-decomposition.md` — Decomposing each bounded context into DDD building blocks (aggregate-first); gap analysis as a coverage matrix (every context → ≥1 block; every quality attribute → ≥1 block). *(interview-building-blocks, review-test-stubs)*. AUTHORED. +- [x] `requirements/aggregate-boundaries.md` — Sizing and splitting aggregates: single-entity default, reference-by-identity, split on invariant seams (Evans ch 4; Vernon ch 10). *(interview-building-blocks)*. AUTHORED. +- [ ] `requirements/ubiquitous-language.md` — Curating the glossary: term extraction, genus-differentia definitions, bounded-context grouping (Evans DDD). *(consolidate-interview)* -**Cited by 3 skills:** -- [ ] `software-craft/solid.md` — SOLID criteria. *(write-test-py, refactor-green, review-implementation)* -- [ ] `software-craft/smell-catalogue.md` — smell taxonomy. *(write-test-py, refactor-green, review-implementation)* -- [ ] `software-craft/tdd.md` — red/green/refactor discipline, pending-mark cycle. *(select-build-target, confirm-red-failure, implement-from-stub)* -- [ ] `software-craft/external-fixtures.md` — probe patterns, vcrpy cassette hygiene, kind-dispatch table. *(research-provider, write-probe, record-cassette)* -- [ ] `software-craft/git-conventions.md` — imperative messages, squash-merge. *(ship-unit, merge-to-dev, publish-release)* +**Explore (ground externals):** +- [ ] `software-craft/external-fixtures.md` — Capturing external reality: vcrpy record/replay, cassette hygiene (decode + scrub volatile headers/secrets), probe-script conventions, 12-factor creds, kind-dispatch table. *(research-provider, write-probe, record-cassette)* -**Cited by 2 skills:** -- [ ] `software-craft/test-stubs.md` — test `.pyi` conventions, stubtest on test pairs. *(author-test-stubs, simulate-contracts)* -- [ ] `software-craft/test-design.md` — what to test, body patterns. *(author-test-stubs, write-test-py)* -- [ ] `software-craft/code-review.md` — review method. *(review-test-stubs, review-implementation)* -- [ ] `software-craft/object-calisthenics.md` — Object Calisthenics rules. *(write-test-py, refactor-green)* -- [ ] `software-craft/source-stubs.md` — source `.pyi` conventions, stubtest scope, canonical data-shape. *(derive-source-stubs, implement-from-stub)* -- [ ] `requirements/feature-discovery.md` — bounded-context → feature, gap analysis. *(interview-features, review-test-stubs)* +**Plan (author contracts):** +- [ ] `software-craft/test-stubs.md` — Test `.pyi` conventions: declare every module-level name (constants/fixtures/class+methods), no third-party imports, kept in sync with `.py`; test-pair stubtest drift rules. *(author-test-stubs, simulate-contracts)* +- [ ] `software-craft/test-design.md` — Designing integration + E2E tests only (no unit): scenario selection, fixture/parametrize conventions, deferred-SUT-import, depend-on-contracts. *(author-test-stubs, write-test-py)* +- [ ] `software-craft/code-review.md` — Review criteria + checklist for impl-matches-contract and source-quality. *(review-test-stubs, review-implementation)* +- [ ] `software-craft/solid.md` — SOLID principles (SRP/OCP/LSP/ISP/DIP) applied to source + test structure. *(write-test-py, refactor-green, review-implementation)* +- [ ] `software-craft/object-calisthenics.md` — Object Calisthenics rules (1-level indent, no getters, etc.) for structural quality. *(write-test-py, refactor-green)* +- [ ] `software-craft/smell-catalogue.md` — Code-smell detection signals (long method, god class, duplication, …). *(write-test-py, refactor-green, review-implementation)* +- [ ] `software-craft/source-stubs.md` — Source `.pyi` conventions: signature-only, ellipsis body, no prescribed layout, canonical data-shape pinning; stubtest scope rules. *(derive-source-stubs, implement-from-stub)* +- [ ] `requirements/spec-simulation.md` — Mental-simulation technique: "if an impl passes these tests, is the result complete + correct?" *(simulate-contracts)* -**Cited by 1 skill:** -- [ ] `requirements/ubiquitous-language.md` — genus-differentia definitions, term extraction. *(consolidate-interview)* -- [ ] `requirements/feature-boundaries.md` — naming + boundary sizing. *(interview-features)* -- [ ] `requirements/spec-simulation.md` — "would-passing-yield-a-working-system" method. *(simulate-contracts)* -- [ ] `software-craft/design-patterns.md` — implementation patterns. *(implement-from-stub)* -- [ ] `software-craft/refactoring-techniques.md` — refactoring moves. *(refactor-green)* -- [ ] `software-craft/versioning.md` — release/tag policy. *(publish-release)* +**Build (implement):** +- [ ] `software-craft/tdd.md` — Red-green-refactor cycle; right-reason-for-failure rule; pending-mark/backlog discipline; scoped-vs-whole stubtest. *(select-build-target, confirm-red-failure, implement-from-stub)* +- [ ] `software-craft/design-patterns.md` — Design patterns (adapter, facade, …) for composing source from a stub. *(implement-from-stub)* +- [ ] `software-craft/refactoring-techniques.md` — Refactoring moves (extract method, etc.) applied under green tests with `.pyi` fixed. *(refactor-green)* + +**Deliver (ship):** +- [ ] `software-craft/git-conventions.md` — Commit + branch conventions (imperative messages, one logical change, feature/dev/release branches). *(ship-unit, merge-to-dev, publish-release)* +- [ ] `software-craft/versioning.md` — Semantic versioning + release tagging. *(publish-release)* ## pyproject + tooling From 1c812d8f817c7d61e78806cb5d7a397e41a6bf3d Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 16:18:12 -0400 Subject: [PATCH 04/28] feat(knowledge): ubiquitous-language + external-fixtures; depth/research bar Author two domain knowledges and encode the depth/research authoring bar into the methodology. - requirements/ubiquitous-language.md: shared rigorous vocabulary as a translation-killer (Evans 2003; Fowler 2006); discovered-then-conquered not transcribed (Avanscoperta; Protean); one meaning per bounded context; genus-differentia; language and code co-evolve (Shore); curated not exhaustive. Completes the discover phase (4/4) - software-craft/external-fixtures.md: record-once-replay-forever (vcrpy record_mode=once; CI VCR_RECORD_MODE=none); kind-dispatch table as the spine (vcrpy HTTP-only; DB/queue/storage capture strategies); two scrubs (safety + determinism); capture-is-truth. Completes the explore phase (1/1) - methodology/knowledge-files.md: add two concepts -- depth deepens across the four sections (Content never thinner than Concepts; Diataxis/arc42/ Divio/Williams) and grounding/research (research the topic, cite inline; inaccurate knowledge is worse than none) --- .../knowledge/methodology/knowledge-files.md | 40 +++++++-- .../requirements/ubiquitous-language.md | 84 +++++++++++++++++++ .../software-craft/external-fixtures.md | 66 +++++++++++++++ TODO.md | 2 +- 4 files changed, 186 insertions(+), 6 deletions(-) create mode 100644 .opencode/knowledge/requirements/ubiquitous-language.md create mode 100644 .opencode/knowledge/software-craft/external-fixtures.md diff --git a/.opencode/knowledge/methodology/knowledge-files.md b/.opencode/knowledge/methodology/knowledge-files.md index 092a09c6..7abb8b7d 100644 --- a/.opencode/knowledge/methodology/knowledge-files.md +++ b/.opencode/knowledge/methodology/knowledge-files.md @@ -1,6 +1,6 @@ --- domain: methodology -tags: [knowledge, wikilinks, diataxis, progressive-disclosure] +tags: [knowledge, wikilinks, diataxis, progressive-disclosure, depth, research] last-updated: 2026-07-01 --- @@ -10,23 +10,27 @@ last-updated: 2026-07-01 - Knowledge holds reference and explanation only — the what and why; procedure lives in skills, identity in agents, routing in the flow (see [[methodology/separation-of-concerns#concepts]]). - Every knowledge file uses four ordered sections — Key Takeaways, Concepts, Content, Related — with strict correspondence: bullet N maps to paragraph N maps to subsection N. +- Depth deepens across the sections: Key Takeaways state the principle, Concepts give the reasoning, Content teaches the topic to a competent reader — Content is never thinner than Concepts. - Cite knowledge with `[[domain/concept]]` or `[[domain/concept#section]]`; the fragment selects how much to extract, saving up to ~80% of the tokens. -- One concept per file, ~150 lines maximum; small focused files may omit Content. +- One concept per file, ~150 lines maximum; split rather than grow. +- Knowledge is grounded in real sources — research the topic (the canonical book or framework, academic work, Wikipedia) and cite it inline; inaccurate knowledge is worse than none. - The knowledge graph is just the wikilinks in each file's Related section — no separate edge store. ## Concepts **Reference and explanation only.** Knowledge answers what and why: definitions, criteria, the reasoning behind a rule. It never answers how (that is a skill) or who (that is an agent). Mixing procedure into knowledge splits the procedure across two load points and the model cannot tell which is authoritative. -**Progressive disclosure.** A reader rarely needs a whole file. The four sections are ordered by depth, so a wikilink fragment can stop early: Key Takeaways for a one-line reminder, through Concepts for understanding, to Content for the full reference. Each tier is self-sufficient at its depth. +**Correspondence.** The four sections are ordered by depth, and the depth is also structure: bullet N in Key Takeaways expands to paragraph N in Concepts and to subsection N in Content. A reader who jumps from a takeaway to its detail must land on the matching concept. Breaking correspondence strands the reader at the wrong depth. -**Correspondence.** Bullet N in Key Takeaways expands to paragraph N in Concepts and to subsection N in Content. A reader who jumps from a takeaway to its detail must land on the matching concept. Breaking correspondence strands the reader at the wrong depth. +**Depth deepens progressively.** Each tier does a different job. Key Takeaways is austere reference — the firm principle, scannable, consulted rather than read (Diátaxis, Procida). Concepts is explanation — the reasoning that turns a rule into understanding. Content is the learning tier — it teaches the topic, expanding each concept with the source's actual mechanism and using tables, criteria, and examples so a reader can recognise an instance and tell it from its neighbours. Content that merely restates Concepts in more words has failed: it must be deeper, never thinner. **Wikilink routing.** Skills are the authority on when to load knowledge; the wikilink is the address. A fragment selects the cut: `#key-takeaways` loads frontmatter and Key Takeaways; `#concepts` loads through Concepts; no fragment loads the whole file. Extraction is cumulative and cuts from the top. **Size and attention.** Files past ~150 lines lose attention to their middles. Split a long file into siblings under the same domain and cross-link them. A small file whose rule fits in bullets and concepts omits Content entirely. -**Domains organise concepts.** `.opencode/knowledge/` is grouped by domain (`methodology/`, and later `requirements/`, `software-craft/`, `workflow/`, …). A domain is a topic area that holds one or more concept files; one concept per file lets a wikilink load exactly that concept. Deep topic areas may nest subdirectories. +**Grounding and accuracy.** Agents load knowledge on demand and treat it as authoritative, so a plausible-sounding error misleads every downstream step — arc42 (Starke) states the stakes plainly: wrong documentation is often worse than none, because it misleads with confidence. Author knowledge by researching the topic first — the canonical book or framework, academic papers, Wikipedia — and cite sources inline. Prefer primary sources (the book, the paper, the framework's own site) over secondary restatements, and cross-check a load-bearing claim against a second source when the stakes are high. + +**The graph is emergent.** Each file's Related section lists its neighbours. The graph is the union of those links — no separate edge file. To validate, extract every `[[...]]` and confirm the target file exists and any fragment names a real section. ## Content @@ -71,6 +75,32 @@ this section entirely when bullets and concepts are enough.> 7. No procedure — how-to belongs in skills. 8. Frontmatter carries `domain`, `tags`, `last-updated` for search and filtering. +### Depth across the four sections + +Each tier serves a different reader need, and the depth must actually increase — a reader who descends from Key Takeaways to Content must receive more, not less. + +| Tier | Job | Reader state | Form | +|---|---|---|---| +| Key Takeaways | state the principle | recalls it in passing | austere bullets, one per concept, imperative | +| Concepts | explain the reasoning | understands without detail | one paragraph per bullet, the why | +| Content | teach the topic | applies it, spots violations | each concept expanded with the source's mechanism; tables, criteria, examples | + +Key Takeaways is austere reference, after Diátaxis (Procida): "one hardly reads reference material; one consults it." Keep it to the firm principle a reader can stand on — no padding, no hedging. Microsoft's style guide echoes the same: reference must be consistent and unambiguous because developers rely on it as a firm platform. Concepts turns the principle into understanding: the reasoning, the why, the edge that makes the rule non-obvious. Content is the learning tier — where a competent reader who does not yet know this topic comes to grasp it. Expand each concept with the source's actual mechanism (not a paraphrase of it), and reach for a table, a criterion, or a worked example wherever it helps the reader recognise an instance or separate look-alikes. Williams's guidance for reference holds here: include examples everywhere — terse and direct, illustrating the thing itself. + +The failure mode is Content thinner than Concepts. If the deepest tier restates the middle tier in more words, the reader descends and learns nothing — expand the Content, or the concept does not deserve its own file. The guardrail runs the other way too: set a manageable scope (Williams — prioritise breadth over depth, with in-depth treatment reserved for the topics that matter) and stop when the concept is grasped. Padding erodes the attention that austere reference earns; arc42's "leave out irrelevant facts" is an explicit decision, not a default. + +### Grounding and research + +Agents load knowledge on demand and treat it as authoritative — there is no human in the loop to catch a plausible error before it steers a build step. arc42 (Starke) states the stakes plainly: wrong documentation is often worse than none, because it misleads with confidence. Author knowledge by researching the topic first, not by writing what seems right. + +1. **Start at the canonical source** — the book or framework the topic sits inside (Evans 2003 for domain-driven design; Diátaxis for documentation structure; the paper that introduced the technique). The canonical source is where the terms, mechanisms, and boundaries were fixed; secondary restatements quietly drop precision. As Divio's reference guide puts it, the only job is to describe "as clearly and completely as possible", and completeness is measured against the machinery, not against intuition. +2. **Corroborate and broaden** — academic or practitioner papers, and Wikipedia for a neutral overview and its cross-references. Wikipedia is strongest for breadth and for surfacing adjacent concepts and the history of an idea; treat it as a map to primary sources, not the destination. +3. **Cite inline (author, year)** at the point of claim, so a reader can verify or go deeper. Prefer the primary citation over a chain of "as cited in". +4. **Cross-check** any load-bearing claim against a second source; if two sources disagree, name the disagreement rather than papering over it. +5. **Reuse the curated research** under `.backup/docs/research/` where it exists — each file records source type, method, verification status, and confidence. Add new research files there for topics not yet covered, so the grounding accumulates rather than evaporating. + +A knowledge file is a claim about the world, not a note to self. Grounding it in cited sources is what lets the austere "consult it, don't read it" contract hold. + ### Wikilink convention `[[domain/concept]]` resolves to `.opencode/knowledge/{domain}/{concept}.md`. A `#section` fragment (lowercase, hyphenated) selects cumulative extraction from the top: diff --git a/.opencode/knowledge/requirements/ubiquitous-language.md b/.opencode/knowledge/requirements/ubiquitous-language.md new file mode 100644 index 00000000..13660a4e --- /dev/null +++ b/.opencode/knowledge/requirements/ubiquitous-language.md @@ -0,0 +1,84 @@ +--- +domain: requirements +tags: [ubiquitous-language, glossary, ddd, bounded-context, genus-differentia] +last-updated: 2026-07-01 +--- + +# Ubiquitous Language + +## Key Takeaways + +- The ubiquitous language is the single, rigorous vocabulary shared by domain experts and developers and used in conversation, code, and documentation; it exists to kill the translation cost between "business speak" and "technical speak" (Evans, 2003; Fowler, 2006). +- Terms are discovered through conversation with domain experts and then refined collaboratively into precision — experts supply field knowledge, modellers supply formal rigour; the language is conquered, not merely transcribed (Avanscoperta). +- A term carries ONE meaning within a bounded context; the same word may legitimately differ across contexts, and that difference marks a context boundary. A single universal vocabulary for the whole organisation is an anti-pattern. +- Each definition uses genus-differentia — name the category, then the distinguishing characteristic — so a reader can place a term and tell it from its neighbours. +- The language and the code co-evolve: a term that changes drives a code rename, and the precision code demands exposes gaps in the language that flow back to the experts. It is a living language, not a one-off artifact (Evans; Shore). +- The glossary is curated for the IMPORTANT domain concepts, not every code symbol: tests are the source of truth for behaviour, the glossary for names; entries are revised — renamed, split, merged, or removed — as understanding shifts. + +## Concepts + +**A shared, rigorous, translation-free vocabulary.** Evans (2003) named the practice of building a common, rigorous language between developers and domain experts the "ubiquitous language", and Fowler (2006) echoed it as the backbone of domain-driven design. Its purpose is to remove the translation layer between what the business says and what the code does: when "Order" means the same thing in a requirements conversation, a diagram, a test, and an identifier, a sentence about the domain maps word-for-word onto the code. Evans frames the cost of not having one plainly — the overhead of translation plus the risk of misunderstanding is simply too high; a fractured language, where domain experts use their jargon and engineers use theirs, is the default failure the ubiquitous language dissolves. + +**Discovered, then conquered.** The language is neither invented by developers nor a verbatim transcript of what experts happen to say. Evans, and the DDD community after him (Avanscoperta), describe it as discovered through conversation and then refined into precision: domain experts supply the field knowledge and the raw terms, while modellers supply the formal rigour that turns a fuzzy conversational word into an unambiguous one. Business language is often a tangle of overlapping narratives; the ubiquitous language is "conquered" through the convergence of the two perspectives, not transcribed. A good term tends to stick precisely because it resolves an ambiguity everyone had been working around. + +**One meaning per bounded context.** The single-meaning guarantee holds inside a bounded context, not globally (Evans, 2003). A bounded context is the stretch of the system in which a term is used consistently; across contexts the same word may legitimately name different things — "Account" with payment terms in Billing, "Account" with credentials in Identity. The advice is explicit: do not try to build one universal vocabulary for the organisation (Protean); each context owns its own language, and translation happens at context boundaries through defined interfaces. The glossary is grouped by context precisely so each term can be unambiguous within its group, and a word that needs two entries is signalling a context boundary, not a defect to merge away. + +**Genus-differentia definitions.** A useful definition places the term in a known category (the genus) and states what sets it apart (the differentia). "A Rate is a conversion ratio that maps one currency into another at a point in time" — the genus is "conversion ratio", the differentia names the mapping that distinguishes a rate from any other ratio. A bare synonym leaves the reader unable to recognise an instance; the category-plus-difference form makes the term recognisable and separates it from its neighbours. Aliases — genuine synonyms — are recorded as a trailing note, never as a substitute for the definition. + +**The language and the code co-evolve.** Evans treats the language as integral to everything the team does, not a design artifact produced once. It is living and bidirectional (Shore): when a term is renamed or refined, the code is refactored to match — classes, methods, and modules renamed to conform to the revised model — and the uncompromising precision that code requires exposes gaps in the language that flow back to the experts for resolution. Both sides carry a duty: domain experts object to terms too awkward to convey the domain; developers flag ambiguity or inconsistency that will trip up the design. Stale names in code are not cosmetic debt; they are ongoing miscommunication that compounds (Protean). + +**Curated, not exhaustive.** The glossary holds the important domain concepts — the ones that drive naming and that a newcomer must grasp to read the system — not a mirror of every class and function. Behaviour is owned by the tests (the source of truth for what the system does); the glossary owns only what things are called, so a term means the same thing in every conversation, diagram, and module. Forcing a one-to-one map between glossary and code creates a second source of truth that drifts from the first; curating for importance keeps the glossary short enough to read and authoritative where it speaks. As understanding shifts, terms are revised directly — renamed, split, merged, or removed — and the code moves with them; the history a superseded term would preserve is already in version control. + +## Content + +### What it is — a translation-killer, not a thesaurus + +Evans (2003) argues that a domain model worth building is worth a vocabulary: the team commits to using the same terms in requirements discussions, in code identifiers, in diagrams, and in tests, so that a spoken sentence about the domain maps word-for-word onto the code. The discipline is rigorous use, not a translation step — when a term does not fit the code, either the term or the code is wrong, and the team resolves it rather than carrying both. Wikipedia records the idea's status plainly: the ubiquitous language is one of the pillars of DDD, used both in the domain model and to describe system requirements. + +The ubiquitous language is not a thesaurus or a translation table between two existing vocabularies. Maintaining "the business calls it X, the code calls it Y" keeps both vocabularies alive and pays the translation cost permanently; the ubiquitous language collapses the two into one. The default state without it is the fractured language Evans opens with — domain experts in their jargon, engineers in theirs, and the code in a third dialect that none of them quite owns. + +### Discovered, then conquered + +Terms come from the elicited domain, but the glossary's definitions are a refinement, not a transcript. The raw material is whatever the stakeholder emphasises or repeats when describing concrete incidents: + +| Source | What it yields | Example | +|---|---|---| +| Domain events | the nouns an outcome revolves around | "Conversion recorded" → Conversion | +| Commands / intents | the nouns and verbs of an action | "Convert amount" → Convert, Amount | +| Building blocks | every named block is a term | RatesAdapter, History | +| Interview nouns | domain-specific words a stakeholder repeats | "rate", "base currency", "history" | +| Qualifying adjectives | words that change a noun's meaning | "available", "locked", "latest" | +| Verbs and phrases | the actions and states the domain names | "place", "ship", "back-ordered" | + +Exclude generic verbs ("store", "compute", "send") and infrastructure nouns ("API", "HTTP", "database") unless the domain has given them a specific, stakeholder-acknowledged meaning. But the refinement matters as much as the extraction: the DDD community (Avanscoperta; Protean) stresses that business language is usually fuzzy, and the ubiquitous language is the convergence of the experts' field knowledge with the modellers' formal rigour. A concept that begins as "Shipment" may be distinguished into "Dispatch" and "Delivery" as the team learns the logistics domain — a split the experts will recognise as right because it resolves an ambiguity they had been working around. + +### One meaning per bounded context + +The guarantee of "one meaning" is scoped to a bounded context (Evans, 2003). The glossary is grouped by context precisely so each term can be unambiguous within its group; when a term genuinely needs different meanings in two contexts, record each under its own context rather than forcing one definition to stretch. The temptation to resist is the universal glossary: an organisation-wide vocabulary that tries to make every word mean one thing everywhere (Protean). That path either flattens real distinctions or fails outright, because the differences between contexts are usually load-bearing — they are where the business actually varies. Translation between contexts is handled at the boundary, through defined interfaces; the glossary records that the boundary exists by grouping entries under each context. + +### Genus-differentia definitions + +A definition that only restates the term in synonyms fails the reader who needs to recognise an instance. The genus-differentia form (the classical Aristotelian definition) fixes this by combining a familiar category with a specific distinction: + +| Part | Answers | Example (a Rate) | +|---|---|---| +| Genus | "What kind of thing is it?" | a conversion ratio | +| Differentia | "Which one, among that kind?" | that maps one currency into another at a point in time | + +Read together: "A Rate is a conversion ratio that maps one currency into another at a point in time." The genus gives the reader a foothold; the differentia separates this term from anything else that is also a ratio. The payoff appears the moment a reader meets a candidate instance: they can ask "is it a ratio?" then "does it map currencies at a point in time?" and know whether the term applies. Aliases are recorded as a trailing note, not as a substitute. + +### The language and the code co-evolve + +The ubiquitous language is living, not authored once (Evans, 2003; Shore). The co-evolution runs in both directions. From language to code: when a term is renamed, refined, or found to conflate two concepts, the code is refactored to match — Evans is explicit that resolving a confusion in conversation means renaming classes, methods, and modules to conform to the revised model. A domain expert saying "the order is placed" should find a `place()` method on an `Order` aggregate that raises an `OrderPlaced` event (Protean); if the code says `submit()` on an `OrderEntity`, the language and the code have drifted and one of them is wrong. From code to language: the precision code demands — every term must name exactly one thing, every operation must be unambiguous — surfaces gaps and inconsistencies that fuzzy conversation hid, and those gaps flow back to the experts for resolution. Both sides carry a duty: experts object to terms too awkward to convey the domain; developers flag ambiguity that will trip up the design. Stale names left in code are not cosmetic debt but compounding miscommunication (Protean). + +### Curated, not exhaustive + +The glossary is a curated reference for the concepts that matter to reading and naming the system, not an index of every class and function. Behaviour — what the system does — is owned by the tests; the glossary owns only what things are called, so that a term used in one conversation, diagram, or module means the same thing in all of them. Forcing a one-to-one correspondence between glossary entries and code symbols produces a second source of truth that inevitably drifts from the first; curating for importance keeps the glossary short enough to read and authoritative where it speaks. + +When understanding shifts — a term is renamed, split, merged, or found redundant — revise or remove the entry directly, and rename in the code to match. The glossary is not an append-only ledger of superseded terms; the history of what a term used to mean is recoverable from version control when anyone needs it. + +## Related + +- [[requirements/domain-decomposition]] — bounded contexts as the decomposition unit; the glossary is grouped by them +- [[requirements/aggregate-boundaries]] — aggregates as one grain of term within a context +- [[requirements/interview-techniques]] — the elicitation that surfaces the stakeholder's raw terms diff --git a/.opencode/knowledge/software-craft/external-fixtures.md b/.opencode/knowledge/software-craft/external-fixtures.md new file mode 100644 index 00000000..93b6dfd1 --- /dev/null +++ b/.opencode/knowledge/software-craft/external-fixtures.md @@ -0,0 +1,66 @@ +--- +domain: software-craft +tags: [external-fixtures, cassettes, vcrpy, record-replay, deterministic-tests] +last-updated: 2026-07-01 +--- + +# External Fixtures + +## Key Takeaways + +- Anchor external-layer tests to REAL captured behaviour, never imagined data — an imagined fixture bakes in the developer's guess and misses the surprises (extra fields, odd types, error shapes) that a real capture exposes before production does. +- Capture once, replay forever: record the real exchange into a committed, replayable artifact; tests and CI replay it offline (HTTP via vcrpy with `record_mode="once"`, CI under `VCR_RECORD_MODE=none`). The capture IS the authoritative external contract. +- The recorder varies by service kind — vcrpy records HTTP only; databases, queues, and object stores each need their own capture strategy. The kind-dispatch table is the one knob set that changes. +- Scrub every cassette twice — for SAFETY (strip credentials, keys, PII) and for DETERMINISM (strip volatile values that churn run-to-run, so replay is stable). vcrpy will not scrub for you (Moskvin, 2025). +- The capture is the truth: never hand-edit a cassette to make a test pass — fix the code, or re-record when reality has genuinely shifted. + +## Concepts + +**Why real captures beat imagined data.** Imagining what an external service returns introduces a systematic bias: tests verify against what the developer thinks the service does, not what it does. A real capture anchors the test to observable truth and catches the surprise — the undocumented field, the error that returns 200 not 4xx, the stringly-typed number — at capture time, before it ships. The rule "stub only dependencies that live outside the service: calls to other microservices, third-party APIs, outbound queues — anything that introduces latency, rate limits, or data you don't control" draws the boundary precisely (Turmyshev, 2026); in-project databases and UI are NOT external and are not captured here. + +**Capture once, replay forever.** The real exchange is recorded a single time into a committed, replayable artifact, and every later run replays it without touching the service. For HTTP that artifact is a vcrpy cassette: the first run records the request/response pairs, later runs intercept matching requests and return the recorded responses, and CI runs with `VCR_RECORD_MODE=none` so a missing or drifting cassette fails loudly instead of silently re-recording (vcrpy, 8.0). The cassette is the authoritative external contract — the thing tests assert against and the reference the build-time adapter implementation honours. The recording vehicle is a throwaway probe script under `.cache/explore/` (gitignored, never imported); the cassette it produces is committed at `tests/cassettes//`. + +**The recorder varies by kind.** vcrpy intercepts HTTP client libraries; it has nothing to say about a database cursor, a queue consumer, or an object store. Each kind needs its own capture strategy, and the strategy is the one knob set that genuinely changes per kind — the kind-dispatch table below is the artifact the explore skills load. The pattern is constant (capture the real exchange, replay it offline); only the recorder, the scrub-fields, and the docs-focus move. + +**Scrub for safety and determinism.** Two independent concerns apply to every cassette. Safety: credentials, API keys, and PII must never reach the committed file — for HTTP, `filter_headers=["authorization"]` strips the request auth header and `filter_post_data_parameters` / `filter_query_parameters` strip secrets from the body and query. Determinism: anything that changes run-to-run (a `date`, a `cf-ray`, a row timestamp, a queue offset, a storage `ETag`) must be stripped or normalised, or replay will churn and the cassette will not diff cleanly. MVP Factory (2026) is blunt: external state is the single largest source of replay non-determinism, and you want it gone. vcrpy does neither scrub for you (Moskvin, 2025) — `before_record_response` (and `before_record_request`) are the hooks where you do it. + +**The capture is the truth.** A cassette is a recording of reality, not a desired outcome. If an adapter test fails against a captured cassette, the code is wrong (or the contract drifted) — never edit the cassette to make the test pass. When reality itself has shifted — the service changed its response, the schema evolved — re-record (our flow signals this as a mismatch and re-enters discovery), and the old capture is replaced, not patched. Fixing the code instead of the fixture is what keeps the test honest. + +## Content + +### Why real captures beat imagined data + +The developer who writes a fixture from memory writes what they remember, and memory smooths over exactly the details that bite in production — the extra nested object, the field the API returns as a string when the docs say integer, the error the service represents with a 200 and a `result: "error"` body rather than a 4xx. A real capture surfaces those at capture time, when they are cheap. The boundary is "anything that introduces latency, rate limits, or data you don't control" (Turmyshev, 2026): third-party APIs and SaaS, external managed databases, message queues you don't own, object stores you call. In-project databases and the UI are not external — they are designed here, specified by tests and migrations, and have no cassette. + +### Capture once, replay forever + +The model is record-once-replay-forever. vcrpy's default `record_mode="once"` records when the cassette is absent and replays when it is present; CI overrides to `record_mode="none"` so the build fails on a missing or unmatched cassette rather than silently re-recording (vcrpy, 8.0). The cassette is committed at `tests/cassettes//` and is the authoritative external contract: the adapter test in build replays it, and the adapter implementation is what makes a real call matching the recorded request. The recording is done by a throwaway probe script under `.cache/explore//` (gitignored, never imported by the package or the tests) that runs once with real 12-factor credentials (an environment variable, sourced locally from a gitignored `.env`), and the cassette it leaves behind is what everyone after consumes. Credentials live in the environment and the probe, never in the cassette — the scrub step exists to guarantee that. + +### The recorder varies by kind + +vcrpy is HTTP-only. Each other kind has its own recorder; the pattern (capture the real exchange, replay offline) is constant. + +| Kind | docs-focus | recorder | scrub-fields | default specialist | +|---|---|---|---|---| +| HTTP API (REST/GraphQL) | OpenAPI spec / official docs; auth scheme; error catalog | vcrpy (`record_mode="once"`) over the real client (httpx/requests) | `filter_headers=["authorization"]`; `before_record_response` strips volatile headers (`date`, `age`, `server`, `last-modified`, `content-encoding`, `transfer-encoding`, `vary`, `cf-ray`, `report-to`, `nel`); `decode_compressed_response=True`; scrub PII from bodies | integration-engineer | +| External database | schema docs; SQL dialect; connection parameters | record real queries + result-sets as a fixture (VCR-style driver interception, e.g. `pytest-adbc-replay`) or a committed fixture dump seeded into a test DB | connection string + password; volatile row values (timestamps, sequences, generated IDs) | data-architect | +| Message queue / event stream | message schema (registry); broker protocol; partition/offset model | capture real messages (key, headers, payload) with the schema version pinned; replay via an embedded broker or a fake consumer (MVP Factory, 2026; Keploy) | broker credentials; offsets, timestamps, producer IDs that churn | data-architect | +| Object storage | storage API; object model; auth (access keys / assumed roles) | capture real object metadata + a representative blob; replay via a mock client | access keys / tokens; volatile metadata (`ETag`, `last-modified`, `version-id`) | integration-engineer | +| Other | research-determined | capture the real exchange in its wire format | research-determined (credentials + volatile fields) | research-determined | + +### Scrub for safety and determinism + +Two independent scrubs apply to every cassette, and vcrpy performs neither (Moskvin, 2025) — you wire them through its hooks. + +**Safety** — nothing that unlocks the real service or identifies a real person reaches the commit. For HTTP: `filter_headers=["authorization"]` drops the request auth header; `filter_post_data_parameters` and `filter_query_parameters` redact secrets embedded in the body or query; `before_record_response` is where body PII (emails, IDs, names) is redacted, either by explicit JSON path or via a detector (Moskvin's `vcrpy-secrets` demonstrates both manual-path and Presidio/detect-secrets approaches). For non-HTTP kinds the credentials move (connection strings, broker tokens, access keys) but the rule does not. + +**Determinism** — anything that changes between recordings is stripped or normalised, so a replayed test is stable and a cassette diff in a pull request means the service changed, not that time passed. For HTTP that is the volatile-header list above; `decode_compressed_response=True` decompresses gzip/deflate bodies before recording (so the cassette is readable text, not an opaque blob) and before any custom response filtering (vcrpy, 8.0) — with the caveat that you avoid it when decompression is itself the behaviour under test. For non-HTTP kinds the volatile values move (row timestamps and sequences, queue offsets and producer IDs, storage `ETag`s and `version-id`s) but the principle does not: external state is the largest source of replay non-determinism, and the scrub exists to eliminate it (MVP Factory, 2026). + +### The capture is the truth + +A cassette records what the service actually did. If the adapter test fails against it, the implementation is wrong or the contract drifted — never hand-edit the cassette to make the test pass, because the moment you do, the test is asserting against a wish, not reality. When the service itself changes — a new required field, a restructured error — the correct response is to re-record (our flow signals a mismatch and re-enters discovery), replacing the stale capture entirely. Version control holds the history of what the cassette used to be; the working tree holds only what the service does now. + +## Related + +- [[software-craft/test-design]] — the adapter test that replays a cassette and asserts against the captured shapes +- [[software-craft/source-stubs]] — the adapter implementation, authored from its stub to match the recorded request and honour the captured response diff --git a/TODO.md b/TODO.md index 17eb12bd..db609af3 100644 --- a/TODO.md +++ b/TODO.md @@ -233,7 +233,7 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [ ] `requirements/ubiquitous-language.md` — Curating the glossary: term extraction, genus-differentia definitions, bounded-context grouping (Evans DDD). *(consolidate-interview)* **Explore (ground externals):** -- [ ] `software-craft/external-fixtures.md` — Capturing external reality: vcrpy record/replay, cassette hygiene (decode + scrub volatile headers/secrets), probe-script conventions, 12-factor creds, kind-dispatch table. *(research-provider, write-probe, record-cassette)* +- [x] `software-craft/external-fixtures.md` — Capturing external reality: record-once-replay-forever (vcrpy HTTP cassettes; CI under `VCR_RECORD_MODE=none`), the kind-dispatch table (recorder/docs-focus/scrub-fields/specialist per kind — vcrpy is HTTP-only), two scrubs (safety + determinism), 12-factor creds, capture-is-truth. *(research-provider, write-probe, record-cassette)*. AUTHORED. **Plan (author contracts):** - [ ] `software-craft/test-stubs.md` — Test `.pyi` conventions: declare every module-level name (constants/fixtures/class+methods), no third-party imports, kept in sync with `.py`; test-pair stubtest drift rules. *(author-test-stubs, simulate-contracts)* From aa72b754804b46b9b4ea16bc63dc347f22b36f12 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 16:35:27 -0400 Subject: [PATCH 05/28] feat(knowledge): test-stubs + test-design + code-review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three software-craft knowledges for the plan-phase review and authoring skills, researched against canonical sources and rethought for this flow: - test-stubs.md (99ln): PEP 484 .pyi signature files for tests, disambiguated from the Meszaros "Test Stub" test double. Documents why the .pyi-preferred rule hides drift from pyright (PEP 484/mypy/PEP 561), why stubtest is the sole detector (runtime inspect diff, structure not return-accuracy), the complete-module-surface rule, and stdlib-typing-only with types under TYPE_CHECKING. - test-design.md (85ln): observable behaviour not implementation (Meszaros); sociable tests at two grains only — integration (narrow) and E2E (broad), no solitary unit (Fowler, Vocke); one behaviour per test; spec value fidelity; property tests (Hypothesis) prove invariants (MacIver). - code-review.md (85ln): adversarial review (Fagan 1976, Tetlock), fail-fast at the first defect, report-only (minor is not a pass), two review modes (review-test-stubs = coverage/scope/happy-path vs interview; review-implementation = correctness/quality/drift/green), PASS/FAIL record per criterion. Conventions (ruff/docstrings) are CI's job, not review's. Knowledge progress: 8/18 authored (Discover 4/4, Explore 1/1, Plan 3/8). --- .../knowledge/software-craft/code-review.md | 85 ++++++++++++++++ .../knowledge/software-craft/test-design.md | 85 ++++++++++++++++ .../knowledge/software-craft/test-stubs.md | 99 +++++++++++++++++++ TODO.md | 6 +- 4 files changed, 272 insertions(+), 3 deletions(-) create mode 100644 .opencode/knowledge/software-craft/code-review.md create mode 100644 .opencode/knowledge/software-craft/test-design.md create mode 100644 .opencode/knowledge/software-craft/test-stubs.md diff --git a/.opencode/knowledge/software-craft/code-review.md b/.opencode/knowledge/software-craft/code-review.md new file mode 100644 index 00000000..4306f579 --- /dev/null +++ b/.opencode/knowledge/software-craft/code-review.md @@ -0,0 +1,85 @@ +--- +domain: software-craft +tags: [code-review, adversarial-review, fail-fast, structured-report, inspection] +last-updated: 2026-07-01 +--- + +# Code Review + +## Key Takeaways + +- The reviewer's default hypothesis is **"this is probably broken — prove otherwise."** Adversarial review, actively hunting for defects, catches more than cooperative "looks good" review, because accountability shifts the search from confirming that it works to finding where it breaks (Fagan, 1976; Tetlock, 1985). +- **Fail fast**: stop at the first defect, write a minimal REJECTED report, and do not continue. The first defect may invalidate everything that follows, so accumulating findings on a doomed pass wastes effort (Fagan, 1976). +- The reviewer **never modifies files**; the output is APPROVED or REJECTED, never an edit. "Minor" is not a pass — an acknowledged smell is still a finding that must be listed. +- **Two review modes run in this workflow, each with its own criteria**: review-test-stubs checks coverage, scope, and happy-path completeness against the interview (NOT code quality — that is gated later on the bodies); review-implementation checks correctness, quality, drift, and green tests against the contract. +- Each criterion is recorded as **Criterion / Verdict / Evidence / Action**. The structure forces a specific judgment per check and refuses the vague "looks good" approval that self-declaration exists to prevent (Hattie & Timperley, 2007). + +## Concepts + +**Adversarial review.** Fagan's (1976) inspections detected the bulk of defects before testing by fixing the process: separate the objectives so the team focuses on one at a time, classify error types and rank their frequency, then describe how to spot each type and condition the team to seek the high-occurrence, high-cost ones. The mechanism that makes it work is stance: Tetlock (1985) showed that accountability to an unknown audience shifts a reviewer out of confirmation bias ("looking for reasons it works") into adversarial search ("looking for reasons it breaks"). The reviewer begins from the assumption that the change is faulty and demands evidence to the contrary; vague approval is the failure mode the stance exists to prevent. + +**Fail fast.** Fagan's inspection stops at the first defect found, because a defect early in the artefact may invalidate the assumptions on which the rest of the review depends. Translated to a contract review: the moment a real defect is found, the reviewer writes a minimal REJECTED report — the defect, its file:line evidence, the required action — and stops. Accumulating further findings on a pass whose foundation is already broken wastes the reviewer's effort and the author's attention; the author fixes the defect, resubmits, and the reviewer starts over on a sound base. + +**Report-only; "minor" is never a pass.** The reviewer produces a verdict, not a patch: APPROVED or REJECTED, with findings, never an in-place edit, because the moment the reviewer starts fixing things the author stops owning the work and the review stops being independent. Within a review, "minor" is not a passing grade — a code smell that is acknowledged is still a finding and is still recorded. Downgrading a real defect to silence it defeats the inspection; the severity may shape the ordering of fixes, not whether they are reported. + +**Two review modes, one method.** The workflow runs two reviews, each aligned to its phase. review-test-stubs reviews the `.pyi` set for coverage, scope, and happy-path completeness *against the interview* — it deliberately does not judge code quality, because the bodies do not exist yet; quality is gated later, on the `.py`. review-implementation reviews the built source *against its contract* for correctness, quality, drift, and green tests. The method — adversarial, fail-fast, structured — is the same in both; only the criteria change. + +**Structured self-declaration.** Hattie and Timperley (2007) show that feedback forces learning only when it demands a specific judgment; a checklist of AGREE/DISAGREE on named criteria prevents the "I skimmed it and nothing jumped out" approval. The PASS/FAIL record — Criterion, Verdict, Evidence, Action — is that device: each check must be articulated against a named criterion with file:line evidence, so approval is explicit about what was verified rather than gestured at. + +## Content + +### Adversarial review + +Fagan (1976) reported that structured inspection caught most defects before any test execution, and the SmartBear Cisco study (2006) — the largest published peer-review dataset — quantified the pace at which the inspection stays effective: + +| Practice | Finding | +|---|---| +| review < 200–400 LOC at a time | defect density drops sharply above this | +| review < 300–500 LOC/hour | faster review misses defects | +| author preparation | the author's own annotation before review saves reviewer time on obvious defects | + +The stance is the part that travels: the reviewer adopts "I will actively search for defects, not confirm correctness," and conditions the search toward the error types this codebase produces most. A review that begins from "probably fine" is, in Fagan's terms, an inspection with its objective inverted. + +### Fail fast + +The protocol is a loop, not a batch: + +1. review against the first criterion; +2. IF a real defect is found THEN write a minimal REJECTED report (defect, file:line evidence, required action) and STOP; +3. ELSE proceed to the next criterion; +4. repeat until every criterion is checked → APPROVED. + +The discipline is to stop, not to stockpile. A second finding written on top of a first that may have invalidated it is effort spent on a pass the author cannot act on without re-review anyway. + +### Report-only; "minor" is not a pass + +The reviewer's output is a verdict plus findings, never an edit. Conventions — formatting, naming, the no-docstring policy — are NOT a review concern in this workflow: ruff (with `PYI`) runs in CI as the enforcement backstop, and review is spent on contract, quality, drift, and behaviour. Within the review's own criteria, no defect is too small to report: a smell that is noticed is a finding, recorded at whatever severity; it is never downgraded out of the report to keep a change moving. + +### Two review modes, one method + +| Mode | Phase | Criteria | NOT judged here | +|---|---|---|---| +| review-test-stubs | after test `.pyi` authoring | coverage against the interview; scope (integration + E2E only); happy-path completeness | code quality (no bodies yet) | +| review-implementation | after green | impl-matches-contract; source-quality-clean (SOLID/DRY/KISS/YAGNI/Object Calisthenics, per [[software-craft/solid]] and [[software-craft/object-calisthenics]]); stubtest-clean; tests-green | — | + +Both modes apply the same adversarial, fail-fast, structured method; the difference is only what the criteria are. A happy-path gap at review-test-stubs and a SOLID violation at review-implementation are both REJECTED with the same kind of report. + +### The PASS/FAIL report + +For every criterion checked, the reviewer records a row, whether the verdict is PASS or FAIL: + +| Field | Holds | +|---|---| +| Criterion | the named quality attribute being checked | +| Verdict | PASS or FAIL | +| Evidence | file:line reference and the specific observation | +| Action | the required change (FAIL only) | + +A REJECTED report is the first FAIL row plus nothing more — the defect, the evidence, the action. APPROVED is the complete table with every row at PASS. There is no third verdict; "looks good" is not one of them. + +## Related + +- [[software-craft/test-design]] — the criteria a review checks tests against +- [[software-craft/test-stubs]] — the `.pyi` surface review-test-stubs inspects +- [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/smell-catalogue]] — the quality bar review-implementation enforces +- [[software-craft/source-stubs]] — the source `.pyi` a contract review reads first diff --git a/.opencode/knowledge/software-craft/test-design.md b/.opencode/knowledge/software-craft/test-design.md new file mode 100644 index 00000000..8615e9e4 --- /dev/null +++ b/.opencode/knowledge/software-craft/test-design.md @@ -0,0 +1,85 @@ +--- +domain: software-craft +tags: [test-design, observable-behaviour, sociable-tests, spec-value-fidelity, property-tests] +last-updated: 2026-07-01 +--- + +# Test Design + +## Key Takeaways + +- A test specifies **observable behaviour through the public interface**, not the implementation; a test that fails under a behaviour-preserving refactor is coupled to the wrong thing and erodes trust in the suite (Meszaros, 2007). +- This project writes **sociable tests at two grains only** — integration (narrow: a boundary or adapter with its real internal wiring and a replayed cassette or fixture) and E2E (broad: the whole system through its entry point). Internal collaborators run real; there are no solitary unit tests that mock them away (Fowler, 2014; Vocke). +- **One observable behaviour per test**: each test fails for exactly one reason and passes for exactly one reason, so a failure points unambiguously at the broken contract. +- **Spec value fidelity**: every literal in a test carries domain intent — an identifier, a boundary, an expected outcome; noise patterns that satisfy structure without meaning (assigning to `_`, padding assert messages) are forbidden. +- Invariants that must hold across *all* inputs are proven by **property tests** (Hypothesis), never by any finite set of examples; examples confirm a case, only a generated range can probe a rule (MacIver, 2016). + +## Concepts + +**Observable behaviour, not implementation.** Meszaros (2007) draws the line that organises everything else: a test ought to verify what the system *does* through its public interface, never *how* it does it through its privates. A test that reaches into internal state or private methods is coupled to the implementation, so it breaks when the implementation changes even though behaviour is preserved — a false negative that trains the team to ignore red tests. Testing through the public interface leaves the test agnostic to the internal structure: a different class layout or a rewritten algorithm keeps the suite green as long as the observable outcome holds. + +**Sociable, at two grains — never solitary.** Fowler (2014) separates *solitary* unit tests (every collaborator replaced by a double) from *sociable* ones (real collaborators run), and Vocke notes the term "unit" is too contested to carry the meaning alone. This project takes the sociable, classicist side and fixes the grains: a *narrow* integration test exercises one external boundary or adapter with its real internal wiring, replacing only the external collaborator with a replayed cassette or fixture; a *broad* E2E test exercises the full system through its entry point. Internal collaborators are never mocked away — that is the solitary style explicitly rejected here, because mocking the insides reimplements the implementation in the test and couples the two. + +**One behaviour per test.** A test that asserts several independent behaviours fails ambiguously: the red signal points at the test, not at the broken behaviour. The discipline is one observable behaviour per test — one reason to fail, one reason to pass — so the title of the failing test names the broken contract directly. Multiple assertions are permitted only when they verify the same behaviour from different angles. + +**Spec value fidelity.** Every value in a specification exists because it carries domain meaning — an entity identifier, a boundary value, a configuration, a concrete expected outcome. The test must use each value in a way that reflects that intent, not invent noise to satisfy a structural check. Assigning a literal to `_`, stuffing it into an assert message, or building a helper whose only purpose is to consume it, all satisfy traceability while signifying nothing; if a spec value does not fit naturally into the test, the mismatch signals a spec problem, not a test workaround. + +**Property tests prove invariants; examples only confirm cases.** MacIver (2016) makes the limit plain: no finite set of hand-picked examples can prove an invariant — a general rule that must hold for all inputs can only be probed by generating inputs across the space. When a rule is structural ("the total always equals the sum of parts", "output is always sorted", "balance never goes negative"), a Hypothesis property test asserts the property over a generated range and finds failure modes no hand-picked set could reach. Examples remain the right tool for specific behaviours and exact outcomes; properties are for the rules that claim universality. + +## Content + +### Observable behaviour, not implementation + +The coupling shows up the moment a behaviour-preserving refactor lands: + +| Test style | What it touches | Under a behaviour-preserving refactor | +|---|---|---| +| observable-behaviour | public interface, returned values, raised errors, observable state | stays green — the contract held | +| implementation-coupled | private methods, internal state, call sequences | goes red — the insides moved | + +The cost of coupling is trust: a suite that red-flags refactors gets ignored, and the real failures get lost in the noise. Testing through the public interface is what makes aggressive refactoring safe — the test guards the behaviour while the implementation underneath is restructured freely. + +### Sociable, at two grains + +| Grain | Scope | Replaced with a double | Runs real | +|---|---|---|---| +| integration (narrow) | one external boundary or adapter + its internal wiring | the external collaborator (via cassette/fixture, per [[software-craft/external-fixtures]]) | all internal collaborators | +| E2E (broad) | the whole system, entry point to edge | nothing inside the system (only the external world, via cassette) | everything | + +The line that is *never* crossed is mocking an internal collaborator. Replacing the outside of the system at a boundary is principled — it isolates the system from a service it does not own; replacing the inside rewrites the implementation inside the test, so a change to the implementation has to be made twice and the two copies drift. This is the classicist position Fowler describes, taken at the narrow and broad grains only; the solitary middle is deliberately empty. + +### One behaviour per test + +- one reason to fail, one reason to pass; +- multiple assertions allowed only when they verify the same behaviour from different angles; +- two independent behaviours become two tests, each named for what it asserts; +- the failing test's name is the diagnosis — if it reads "test_X" and points at nothing specific, it is testing too much. + +### Spec value fidelity + +| The spec supplies | Fidelity looks like | Noise looks like | +|---|---|---| +| `"USD"` as a base currency | pass it as the base; assert on the rate it yields | assign it to `_`; stuff it in an assert message | +| `10` as an amount | convert it; assert the converted amount | bury it in a helper that consumes it | +| `8.77` as the expected result | assert equality against it | derive it from the computation under test (tautology) | + +If a value the interview supplied does not fit the test naturally, that is a signal the spec is unclear about why the value matters — not licence to absorb it as noise. + +### Property tests prove invariants + +An example can only confirm a rule holds for the chosen case; it cannot prove the rule holds generally. Hypothesis (MacIver, 2016) generates inputs across the declared strategy and shrinks any failing case to the smallest counterexample, so a property test is the right tool when the requirement is universal: + +| Requirement shape | Right tool | +|---|---| +| "converts 10 USD to 8.77 EUR" (specific case) | an example test with literal values | +| "the converted amount rounds to cents" (universal rule) | a Hypothesis property over generated amounts | +| "history is always latest-first" (universal ordering) | a Hypothesis property over generated histories | + +Property tests live alongside the example tests in the same suite; they are not a separate layer, just the tool that matches a universal claim. + +## Related + +- [[software-craft/test-stubs]] — the `.pyi` signature file each test is authored against first +- [[software-craft/external-fixtures]] — the cassettes and fixtures that replace the external collaborator at the boundary +- [[software-craft/code-review]] — the review method that checks these criteria are met +- [[software-craft/solid]], [[software-craft/object-calisthenics]] — the design discipline the bodies are held to diff --git a/.opencode/knowledge/software-craft/test-stubs.md b/.opencode/knowledge/software-craft/test-stubs.md new file mode 100644 index 00000000..b8faa92c --- /dev/null +++ b/.opencode/knowledge/software-craft/test-stubs.md @@ -0,0 +1,99 @@ +--- +domain: software-craft +tags: [test-stubs, pyi, stubtest, contract-surface, pep-484] +last-updated: 2026-07-01 +--- + +# Test Stubs + +## Key Takeaways + +- A test stub here is a **PEP 484 `.pyi` signature file** for a test module — not a Meszaros *Test Stub* (a test double that feeds indirect inputs to the SUT). The two share a name and nothing else; disambiguate before reading further (PEP 484; Meszaros, 2007). +- When a `.pyi` and its `.py` both exist, the type checker reads **only the `.pyi`** and ignores the `.py` (PEP 484; mypy; PEP 561). Editing the `.py` never reaches the checker, so `.pyi`↔`.py` drift is **invisible to pyright**. +- `mypy.stubtest` is the **sole drift detector**: it imports the module at runtime via `inspect`, diffs the live object against the `.pyi`, and reports every mismatch. It verifies structure and signatures — **not** return-type accuracy (mypy docs). +- A test `.pyi` must mirror the test `.py`'s **complete module surface** — every module-level constant, fixture, helper, the test class, and every method signature — or stubtest flags the gap (typing.python.org). +- Author **stdlib-typing-only**; never import third-party libraries in the stub (they trip mypy `import-untyped`, and stubtest does not require them). Route any import-that-exists-only-for-types through `typing.TYPE_CHECKING`. + +## Concepts + +**Two meanings of "stub" — disambiguate first.** Meszaros (2007) named a *Test Stub* as a test double that replaces a depended-on component to feed controlled indirect inputs to the system under test. PEP 484 named a *stub file* (`.pyi`) as a signature-only description of a module for type checkers. The two are unrelated — one is a runtime object, the other a static type artifact — yet both are called "stub"; a reader arriving here for test-double patterns is in the wrong place. Test doubles belong to [[software-craft/test-design]]; this file is about `.pyi` signature files. + +**The `.pyi` wins, so pyright hides drift.** PEP 484 is explicit: "If a stub file is found the type checker should not read the corresponding 'real' module." mypy and PEP 561 concur — "the `.pyi` file takes precedence," and "type checkers MUST maintain the normal resolution order of checking `*.pyi` before `*.py`." The consequence is asymmetric and dangerous: while the `.py` is absent or stale, the checker trusts the `.pyi` blindly and reports nothing. A stale `.pyi` is a silent lie that pyright will never expose; only a tool that reads the runtime module can. + +**stubtest — the runtime diff.** mypy ships `stubtest` precisely because stubs diverge. It imports the module and introspects the live objects with `inspect`, then compares what it finds against the analysed `.pyi` (mypy docs). It catches missing definitions, renamed or re-typed arguments, and default-value mismatches, and it is the tool used to validate typeshed itself. Two limits matter: it checks structure and signatures, not whether a return type is *accurate*; and it executes the module on import, so it must run where the code and its dependencies are installed. + +**Mirror the complete module surface.** A `.pyi` carries the full public interface of its module — every class, function, and constant (typing.python.org). For tests this is especially load-bearing because stubtest compares the *whole* module: a module-level constant (`BASE`, `CASSETTE`), a fixture function, or a helper omitted from the `.pyi` is a drift hit even when the test logic is correct. The test-specific difficulty is that fixture parameters are resolved by name at runtime, and attributes assigned in `setup_method` are invisible to a reader of the stub — both must be hand-declared in the `.pyi` and hand-synced, a standing drift vector with no library-stub analogue. + +**Stdlib typing only; types under TYPE_CHECKING.** Importing a third-party library in a `.pyi` makes mypy report `import-untyped` for any library that ships no stubs of its own, and stubtest does not need the import — it consults the *runtime* module, which already has its dependencies. Keep the stub to stdlib typing; route any import that exists only for types through a guarded block so it is invisible at runtime. + +## Content + +### Two meanings of "stub" + +| Term | Origin | What it is | Lives in | +|---|---|---|---| +| Test Stub | Meszaros, 2007 (xUnit Patterns) | a test **double** replacing a depended-on component to feed indirect inputs to the SUT | runtime, inside a test body | +| stub file (`.pyi`) | PEP 484 | a **signature-only** description of a module for type checkers (`...` bodies, no runtime logic) | a `.pyi` file beside its `.py` | + +This knowledge is about the second. The typing.python.org guide notes that conventional `.pyi` authoring targets a *library's public interface for consumers* and explicitly lists *tests* among modules excluded from stubs — so authoring test `.pyi` deliberately is a conscious adaptation of the mechanism, justified here because the test `.pyi` is the contract surface the staged workflow authors before any body or source exists. + +### Why the checker hides drift + +PEP 484 fixes the resolution order: when both files are present, the `.pyi` is the single source the checker consults, and the `.py` becomes invisible — not "lower priority," ignored. This is a feature for libraries (consumers type-check against the published surface, not the implementation) but a hazard for a workflow that maintains both files by hand: + +| Situation | pyright sees | Drift detected? | +|---|---|---| +| `.pyi` present, `.py` absent | the `.pyi` only; `reportMissingModuleSource` (tolerated) | n/a — expected pre-build | +| both present, in sync | the `.pyi` only | no drift — but pyright cannot confirm the `.py` matches | +| both present, `.py` drifted | the `.pyi` only | **no** — pyright is silent | + +ruff, equally, lints each file independently and is not a type checker, so it detects no cross-file drift either. The one tool that does is stubtest. + +### stubtest — the runtime diff + +stubtest's method is dynamic, not static. From the mypy docs: it imports the package, introspects the live objects with `inspect`, then diffs the result against the analysed `.pyi`. What it catches and what it cannot: + +| Catches | Does not catch | +|---|---| +| missing / redundant definitions | whether a return type is *accurate* | +| argument name / arity / annotation mismatch | internal implementation correctness | +| default-value presence and shape | runtime behaviour | +| positional-only / kind mismatches | type-checker-level soundness | + +Operational notes that bear on the gate: stubtest must run in the project environment (it executes the module, so transitive deps must be installed); `--ignore-missing-stub` silences "runtime has it, stub doesn't"; `--allowlist FILE` (regex) suppresses known exceptions. The workflow scopes stubtest per cycle — `stubtest . tests.` at green/review — and runs the whole `stubtest tests` only at merge, once every `.py` exists. + +### Mirror the complete module surface + +stubtest compares the whole module, so a `.pyi` that omits any name the `.py` exposes is a drift hit regardless of test correctness. For a test module that means declaring every module-level constant, every fixture, every helper, the test class, and every method signature: + +``` +BASE: str # module constants the .py defines +CASSETTE: str + +def sample_rate() -> Rate: ... # helper functions + +class TestRatesAdapter: # the test class + rates: RatesAdapter # attr set in setup_method — hand-declared + def setup_method(self) -> None: ... + def test_fetches_rate(self, monkeypatch) -> None: ... +``` + +Two test-specific drift vectors have no library-stub analogue. First, fixture parameters (`monkeypatch`, `tmp_path`, `capsys`) are resolved by *name* through pytest's dependency injection; a type checker reading the `.pyi` cannot see that binding, so the parameter is declared for structural agreement and left unannotated (the typing.python.org guide permits unannotated arguments in partial stubs). Second, instance attributes assigned in `setup_method` do not exist in the class body the checker reads, so they must be hand-declared at class level in the `.pyi` and updated whenever `setup_method` changes. Both drift silently if forgotten — stubtest is what eventually catches them. + +### Stdlib typing only; types under TYPE_CHECKING + +Importing a third-party library in a `.pyi` trips mypy's `import-untyped` for any library that ships no stubs, polluting the simulate gate with noise the test does not need. stubtest does not require the import either, because it consults the runtime module — which already has its dependencies installed. Keep the stub to stdlib typing, and route any import that exists only for types through a guarded block so it stays invisible at runtime: + +``` +from typing import TYPE_CHECKING +if TYPE_CHECKING: + from converter.models import Rate # import-only-for-types +``` + +This keeps the deferred-import convention intact: a pending test module whose system-under-test is not yet built still collects and skips cleanly, because the SUT import lives inside each test body, not at module top. + +## Related + +- [[software-craft/source-stubs]] — the source-side `.pyi` craft; the same drift mechanics from the implementation's perspective +- [[software-craft/test-design]] — what to test, and the Meszaros test doubles (the *other* meaning of "stub") +- [[requirements/spec-simulation]] — the simulate gate runs stubtest over the test set diff --git a/TODO.md b/TODO.md index db609af3..ac384ffc 100644 --- a/TODO.md +++ b/TODO.md @@ -236,9 +236,9 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [x] `software-craft/external-fixtures.md` — Capturing external reality: record-once-replay-forever (vcrpy HTTP cassettes; CI under `VCR_RECORD_MODE=none`), the kind-dispatch table (recorder/docs-focus/scrub-fields/specialist per kind — vcrpy is HTTP-only), two scrubs (safety + determinism), 12-factor creds, capture-is-truth. *(research-provider, write-probe, record-cassette)*. AUTHORED. **Plan (author contracts):** -- [ ] `software-craft/test-stubs.md` — Test `.pyi` conventions: declare every module-level name (constants/fixtures/class+methods), no third-party imports, kept in sync with `.py`; test-pair stubtest drift rules. *(author-test-stubs, simulate-contracts)* -- [ ] `software-craft/test-design.md` — Designing integration + E2E tests only (no unit): scenario selection, fixture/parametrize conventions, deferred-SUT-import, depend-on-contracts. *(author-test-stubs, write-test-py)* -- [ ] `software-craft/code-review.md` — Review criteria + checklist for impl-matches-contract and source-quality. *(review-test-stubs, review-implementation)* +- [x] `software-craft/test-stubs.md` — PEP 484 `.pyi` signature files for tests (disambiguated from the Meszaros test double); `.pyi`-preferred hides drift from pyright, stubtest is the sole detector; mirror the complete module surface; stdlib-typing-only with types under `TYPE_CHECKING`. *(author-test-stubs, simulate-contracts)*. AUTHORED. +- [x] `software-craft/test-design.md` — Observable behaviour not implementation; sociable tests at two grains only (integration narrow + E2E broad, no solitary unit); one behaviour per test; spec value fidelity; property tests (Hypothesis) prove invariants. *(author-test-stubs, write-test-py)*. AUTHORED. +- [x] `software-craft/code-review.md` — Adversarial review (Fagan 1976; Tetlock); fail-fast at the first defect; reviewer reports APPROVED/REJECTED only, never edits, "minor" is not a pass; two modes (review-test-stubs = coverage/scope/happy-path vs interview; review-implementation = correctness/quality/drift/green); PASS/FAIL record per criterion. *(review-test-stubs, review-implementation)*. AUTHORED. - [ ] `software-craft/solid.md` — SOLID principles (SRP/OCP/LSP/ISP/DIP) applied to source + test structure. *(write-test-py, refactor-green, review-implementation)* - [ ] `software-craft/object-calisthenics.md` — Object Calisthenics rules (1-level indent, no getters, etc.) for structural quality. *(write-test-py, refactor-green)* - [ ] `software-craft/smell-catalogue.md` — Code-smell detection signals (long method, god class, duplication, …). *(write-test-py, refactor-green, review-implementation)* From 1fc0fb14640653d21235efc19c25ba91c8a68cae Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 16:59:05 -0400 Subject: [PATCH 06/28] feat(knowledge): source-stubs + solid + object-calisthenics + smell-catalogue Completes the Plan-phase software-craft cluster (7/7). Each rethought for this flow against canonical sources: - source-stubs.md (88ln): source .pyi DERIVED from test bodies (inverse of conventional); signature-only ...; FIXED during build (escalate on gap); no prescribed layout; config 12-factor; structural artifacts keyed to the module (ORM->migration, adapter->cassette); scoped stubtest. - solid.md (55ln): the 5 SOLID principles (Martin 2000/2003) with a violation->smell->fix map; applied when a smell triggers, never speculatively. - object-calisthenics.md (60ln): Jeff Bay's 9 rules (ThoughtWorks Anthology 2008) as an exercise-turned-guideline; KT as the reference list, Content as the per-rule mechanism table; enforced as the quality bar, not a literal counter. - smell-catalogue.md (82ln): Fowler's (1999) 5 categories with Smell/Signal/Fix tables; a Comment is a symptom of code needing extraction (which the no-comments policy makes the rule). Knowledge progress: 12/18 authored (Discover 4/4, Explore 1/1, Plan software-craft 7/7). Remaining software-craft: Build (tdd, design-patterns, refactoring-techniques) + Deliver (git-conventions, versioning); plus requirements/spec-simulation (Plan). --- .../software-craft/object-calisthenics.md | 60 +++++++++++++ .../software-craft/smell-catalogue.md | 82 +++++++++++++++++ .opencode/knowledge/software-craft/solid.md | 55 ++++++++++++ .../knowledge/software-craft/source-stubs.md | 88 +++++++++++++++++++ TODO.md | 8 +- 5 files changed, 289 insertions(+), 4 deletions(-) create mode 100644 .opencode/knowledge/software-craft/object-calisthenics.md create mode 100644 .opencode/knowledge/software-craft/smell-catalogue.md create mode 100644 .opencode/knowledge/software-craft/solid.md create mode 100644 .opencode/knowledge/software-craft/source-stubs.md diff --git a/.opencode/knowledge/software-craft/object-calisthenics.md b/.opencode/knowledge/software-craft/object-calisthenics.md new file mode 100644 index 00000000..34bd1084 --- /dev/null +++ b/.opencode/knowledge/software-craft/object-calisthenics.md @@ -0,0 +1,60 @@ +--- +domain: software-craft +tags: [object-calisthenics, design-constraints, code-quality, oop] +last-updated: 2026-07-01 +--- + +# Object Calisthenics + +## Key Takeaways + +- OC-1: one level of indentation per method — deep nesting signals mixed concerns. +- OC-2: no `else` — guard clauses and early returns carry every branch. +- OC-3: wrap all primitives and strings in small domain types — `Age`, not `int`. +- OC-4: one dot per line — `a.b.c` is a Law of Demeter violation. +- OC-5: do not abbreviate — a long name means the scope is too broad or the concept unclear. +- OC-6: keep entities small — classes ≤ 50 lines, packages ≤ 10 classes. +- OC-7: no more than two instance variables per class — more signals multiple responsibilities (Bay, 2008). +- OC-8: first-class collections — a class holding a collection holds nothing else. +- OC-9: no getters, setters, or properties — tell an object to do work, do not ask for its data. + +## Concepts + +**An exercise, not a law.** Bay (2008) introduced the nine rules as a *calisthenic* — a 1000-line project written under deliberately excessive constraints to force a developer out of the procedural groove and into an object-oriented one. The rules are not universally attainable on real code; their value is the design habit they build, and once the habit is there they become guidelines applied where they clarify. This workflow applies them that way: as the quality bar a review enforces, with the understanding that a rule bent for good reason is a discussion, not an automatic rejection. + +**Control-flow and size force decomposition.** The first two rules (one indent, no `else`) and the sixth (small entities) attack the same habit from three angles: nested branches, alternative branches, and sheer length all grow a method past a single decision. Forced apart, each decision becomes a named method with a single responsibility, and a class that cannot exceed fifty lines has to distribute its behaviour across collaborators rather than accrete it. The result is a forest of small objects in place of one large procedure. + +**Domain typing and encapsulation keep behaviour home.** Wrapping primitives (OC-3) and first-class collections (OC-8) give the type system enforcement power — an `Age` cannot be added to a `Score` — and give behaviour a natural home attached to the data it describes. One dot per line (OC-4) and no getters (OC-9) finish the job: if a caller cannot reach through an object to its neighbour's data, it has to *tell* the object to act, and the behaviour stays where the data lives instead of leaking into the caller. + +**Names and cohesion expose the design.** Refusing abbreviations (OC-5) forces the cost of a too-broad scope to be paid in a name too long to read, which pressures the scope down. Capping instance variables at two (OC-7) is the most consequential constraint: each variable is a cohesive cluster of responsibility, and a third cluster is the signal that a collaborator wants extracting. Together these rules surface design pressure as naming and structure the team can see and act on. + +## Content + +### The exercise + +Bay's chapter in the *ThoughtWorks Anthology* (Pragmatic Bookshelf, 2008) prescribes a small project — about 1000 lines — written strictly under all nine rules at once. The restrictions are intentionally merciless: they exist to break procedural reflex, not to be met comfortably. At the end of the exercise the rules relax into guidelines; on real code they are applied where the pressure they apply produces a clearer design, not as a pass/fail gate applied blindly. A 51-line class is not a defect; it is a prompt to ask what responsibility could be its own object. + +### The nine rules + +| Rule | Mechanism | What it forces | +|---|---|---| +| OC-1 one indent | extract each nested block | one decision per method | +| OC-2 no `else` | guard clauses, early returns, polymorphism | one path per method; no branch-tracking | +| OC-3 wrap primitives | a small class per domain value | type safety; behaviour attached to data | +| OC-4 one dot | ask the neighbour, do not reach through it | encapsulation; Law of Demeter | +| OC-5 no abbreviations | refuse to shorten | scope pressure; clear concepts | +| OC-6 small entities | class ≤ 50 lines, package ≤ 10 classes | distribution over accretion | +| OC-7 two ivars | cap instance variables at two | one cohesive responsibility per class | +| OC-8 first-class collections | a collection is a class's only field | collection behaviour has a home | +| OC-9 no getters/setters | tell, do not ask | behaviour stays with the data | + +### Applied as a guideline, enforced as a bar + +`write-test-py`, `refactor-green`, and `review-implementation` all cite Object Calisthenics as part of the quality bar. The bar is real — a smell-laden implementation is rejected — but the rules operate as the diagnostic behind the bar, not as a literal counter. A reviewer who counts dots, indentation levels, or instance variables and rejects on the count alone has mistaken the calisthenic for the law; one who reads a Long Method, notices the fourth level of nesting, and asks for an extraction has used the rule as it was intended. + +## Related + +- [[software-craft/solid]] — the principles the rules prevent violations of (OC-7 → SRP; OC-4 → DIP) +- [[software-craft/smell-catalogue]] — the smells the rules head off (Primitive Obsession, Message Chains, Large Class) +- [[software-craft/refactoring-techniques]] — the moves that bring code back under a rule once broken +- [[software-craft/code-review]] — the review that applies the bar diff --git a/.opencode/knowledge/software-craft/smell-catalogue.md b/.opencode/knowledge/software-craft/smell-catalogue.md new file mode 100644 index 00000000..45e42fa7 --- /dev/null +++ b/.opencode/knowledge/software-craft/smell-catalogue.md @@ -0,0 +1,82 @@ +--- +domain: software-craft +tags: [code-smells, refactoring, fowler, code-quality] +last-updated: 2026-07-01 +--- + +# Smell Catalogue + +## Key Takeaways + +- **Bloaters** (Long Method, Large Class, Primitive Obsession, Long Parameter List, Data Clumps) are structures that grew too large; extract function or class, replace the primitive with an object, introduce a parameter object (Fowler, 1999). +- **Object-Oriented Abusers** (Switch Statements, Temporary Field, Refused Bequest, Alternative Classes with Different Interfaces) misapply OOP; reach for polymorphism, Extract Class, or delegation (Fowler, 1999). +- **Change Preventers** (Divergent Change, Shotgun Surgery, Parallel Inheritance Hierarchies) make change ripple; restructure along the axis of change or move the data (Fowler, 1999; Shvets, 2014). +- **Dispensables** (Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality) are dead weight to delete, inline, or merge — and a Comment is the symptom of code that should have been extracted or renamed instead. +- **Couplers** (Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man) over-couple objects; move the method, hide the delegate, or collapse the middle man (Fowler, 1999; Shvets, 2014). + +## Concepts + +**Bloaters** grow by accretion — one more line, one more field, one more parameter — until they block the reader. They are rarely introduced deliberately; they creep in because adding is cheaper than extracting. Long Method needs a section label to read; Large Class accretes responsibilities until its name swells with nouns; Primitive Obsession uses a bare `int` where an `Age` or a `Quantity` would carry meaning; Long Parameter List and Data Clumps signal that related values have not yet been recognised as the object they want to be (Fowler, 1999; Shvets, 2014). + +**Object-Oriented Abusers** are OOP applied incompletely. A Switch Statement selects on a kind field where polymorphism would dispatch; Temporary Field holds a value set on only some paths; Refused Bequest is a subclass that inherits what it does not want; Alternative Classes with Different Interfaces are two types doing one job under two names. Each is the wrong tool being used part-way — inheritance where delegation fits, conditionals where a type hierarchy belongs (Shvets, 2014). + +**Change Preventers** are the most damaging because they resist change. Divergent Change sends one class in several unrelated directions; Shotgun Surgery scatters one concept across many classes; Parallel Inheritance Hierarchies force new subclasses in lockstep. The shared symptom is that a single, coherent change makes the codebase bleed in many places at once, and the fix is to re-group code around the axes that actually change together (Fowler, 1999). + +**Dispensables** carry no weight. Duplicate Code repeats logic it should share; Lazy Class and Data Class earn too little of their keep; Dead Code is unreachable; Speculative Generality is abstraction bought on credit against a future that never arrives. A Comment belongs here in spirit: a comment that explains *what* the code does is usually standing in for an extraction or a rename that would make the comment unnecessary — and in a workflow that forbids comments outright, that pressure becomes the rule that the code itself has to be clear (Fowler, 1999). + +**Couplers** over-bind objects. Feature Envy reaches into a neighbour's data more than its own; Inappropriate Intimacy reads another's privates; Message Chains navigate `a.b().c().d()`; Middle Man forwards every call without adding a thought. Each replaces one coupling with another unless the fix moves behaviour to where the data already lives, so the conversation between objects shortens to the immediate neighbours (Fowler, 1999; Shvets, 2014). + +## Content + +### Bloaters + +| Smell | Signal | Fix | +|---|---|---| +| Long Method | a section needs a label to understand; > ~10 lines | Extract Method; Decompose Conditional | +| Large Class | too many fields/methods; name stuffed with nouns | Extract Class; Extract Subclass | +| Primitive Obsession | a bare primitive standing for a domain value | Replace Data Value with Object; Introduce Parameter Object | +| Long Parameter List | 3+ params, or a group recurring across signatures | Introduce Parameter Object; Preserve Whole Object | +| Data Clumps | the same 2–3 values always travel together | Extract Class; Introduce Parameter Object | + +### Object-Oriented Abusers + +| Smell | Signal | Fix | +|---|---|---| +| Switch Statements | `if/elif` or `match` on a kind/type/status | Replace Conditional with Polymorphism; State; Strategy | +| Temporary Field | a field set on only some paths; `None` "shouldn't happen" | Extract Class; Introduce Null Object | +| Refused Bequest | a subclass overrides to do nothing or to raise | Push Down Method; Replace Inheritance with Delegation | +| Alternative Classes w/ Different Interfaces | two classes, one job, different names | Rename Method; Extract Superclass; unify behind a Protocol | + +### Change Preventers + +| Smell | Signal | Fix | +|---|---|---| +| Divergent Change | one class changes for multiple unrelated reasons | Extract Class along each axis of change | +| Shotgun Surgery | one concept change edits many classes | Move Method/Field; Inline Class; co-locate | +| Parallel Inheritance Hierarchies | a new subclass here forces one there | Move Method/Field to flatten or unify | + +### Dispensables + +| Smell | Signal | Fix | +|---|---|---| +| Duplicate Code | the same logic in 2+ places | Extract Method; Pull Up Method; Form Template Method | +| Lazy Class | a class that does too little | Inline Class; Collapse Hierarchy | +| Data Class | fields with getters/setters, no behaviour | Move Method into it; Encapsulate Field | +| Dead Code | unreachable, unused | delete it | +| Speculative Generality | abstraction with no current caller | Inline Class/Method; remove the unused parameter | + +### Couplers + +| Smell | Signal | Fix | +|---|---|---| +| Feature Envy | a method uses another class's data more than its own | Move Method | +| Inappropriate Intimacy | reaching into another's privates | Move Method/Field; Extract Class; delegation | +| Message Chains | `a.b().c().d()` | Hide Delegate; Extract Method | +| Middle Man | most methods are one-line forwards | Inline Class; Remove Middle Man | + +## Related + +- [[software-craft/refactoring-techniques]] — the moves each smell entry points at +- [[software-craft/solid]] — the principle a smell usually violates +- [[software-craft/object-calisthenics]] — the rules that head the smells off at write time +- [[software-craft/code-review]] — the review that names a smell a defect diff --git a/.opencode/knowledge/software-craft/solid.md b/.opencode/knowledge/software-craft/solid.md new file mode 100644 index 00000000..3e001771 --- /dev/null +++ b/.opencode/knowledge/software-craft/solid.md @@ -0,0 +1,55 @@ +--- +domain: software-craft +tags: [solid, design-principles, oop, code-quality] +last-updated: 2026-07-01 +--- + +# SOLID + +## Key Takeaways + +- **SRP** — a class has one reason to change; multiple responsibilities mean multiple change axes that conflict (Martin, 2000). +- **OCP** — entities are open for extension, closed for modification: add behaviour by adding code, not by editing existing code. +- **LSP** — subtypes are substitutable for their base types; a subclass that breaks the parent's contract violates Liskov substitution. +- **ISP** — clients depend only on the interface they use; split fat interfaces into small, cohesive ones. +- **DIP** — depend on abstractions, not concretions; high-level policy and low-level detail both depend on abstractions. +- SOLID is applied **when a smell triggers it**, never speculatively — it is part of the quality bar a review enforces, not a checklist to satisfy in advance of a problem. + +## Concepts + +**Single Responsibility (SRP).** Martin (2000) frames responsibility as an axis of change: a class with more than one reason to change has more than one responsibility, and when requirements shift it changes in unrelated ways that couple concerns which never belonged together. The test is not "does it do one thing?" but "does it change for one reason?" — a class that edits both currency rates and audit logs will be touched by both a rate-change and an audit-change request, and those are two responsibilities however neatly the methods are named. + +**Open-Closed (OCP).** Adding a variant should add code, not edit it. When behaviour is selected by `if/elif` on a kind field, every new variant forces a change to every switch — the type is open for modification and closed for extension, the inverse of the principle. The fix is polymorphism (or Strategy/State): a new variant is a new type that fits an existing interface, and the dispatch sites are unchanged. + +**Liskov Substitution (LSP).** Liskov's (1987) subtyping rule, named as a principle by Martin: anywhere a base type is expected, any subtype must work without surprise. A subclass that overrides a method to do nothing, to raise, or to narrow a precondition breaks the parent's contract and will trip a caller that relied on it. The smell is *Refused Bequest*; the fix is usually delegation or pushing the method down, not a fragile inheritance. + +**Interface Segregation (ISP).** A client forced to depend on methods it never uses is coupled to changes that do not concern it. A fat interface split into one role-interface per client keeps each dependent small and each change local. The signal is a client importing an interface for two of its ten methods — the other eight are load it does not need. + +**Dependency Inversion (DIP).** High-level policy should not reach into low-level detail; both should sit behind abstractions. A module that imports a concrete database adapter is welded to that adapter's implementation; define a Protocol and inject the adapter, and the policy becomes independent of the mechanism. In this workflow the boundary is also where the cassettes and fixtures attach — the abstraction is what lets the real adapter and its replay double satisfy the same contract. + +## Content + +### Violation → smell → fix + +| Principle | Smell | Signal | Fix | +|---|---|---|---| +| SRP | Divergent Change | one class changes for multiple unrelated reasons | Extract Class by axis of change | +| SRP | Large Class | too many fields or methods | Extract Class, Extract Subclass | +| OCP | Switch Statements | `if/elif` on a kind/type/status, edited per variant | Replace Conditional with Polymorphism; Strategy; State | +| OCP | Shotgun Surgery | one variant forces edits across many call sites | move dispatch into the type hierarchy | +| LSP | Refused Bequest | subclass overrides to do nothing or to raise | Push Down Method; Replace Inheritance with Delegation | +| LSP | Alternative Classes w/ Different Interfaces | two classes, same job, different signatures | Extract Superclass; unify behind a Protocol | +| ISP | Fat Interface | client depends on methods it does not call | Extract Interface per client role | +| DIP | Direct Dependency on Concrete | module imports a concrete class | define a Protocol; inject it | +| DIP | Hard-coded Construction | `__init__` builds its own dependencies | inject dependencies; Factory if construction varies | + +### Applied when triggered, not speculatively + +SOLID is part of the quality bar `review-implementation` and `refactor-green` enforce, alongside Object Calisthenics and the smell catalogue. It is applied *when a smell points at it* — a Divergent Change points at SRP, a Switch Statement at OCP — not run at a class on the chance it might be violating something. Speculative SOLID produces abstraction for its own sake (the Speculative Generality smell), which is itself a defect the review then rejects. + +## Related + +- [[software-craft/smell-catalogue]] — each SOLID violation manifests as a named smell +- [[software-craft/object-calisthenics]] — the rules that prevent the violations at write time (OC-7 enforces SRP; OC-4 enforces DIP) +- [[software-craft/design-patterns]] — patterns that resolve violations (Strategy resolves OCP) +- [[software-craft/refactoring-techniques]] — the moves that fix a violation once found diff --git a/.opencode/knowledge/software-craft/source-stubs.md b/.opencode/knowledge/software-craft/source-stubs.md new file mode 100644 index 00000000..0a558f2e --- /dev/null +++ b/.opencode/knowledge/software-craft/source-stubs.md @@ -0,0 +1,88 @@ +--- +domain: software-craft +tags: [source-stubs, pyi, contract, derive-from-tests, pep-484] +last-updated: 2026-07-01 +--- + +# Source Stubs + +## Key Takeaways + +- A source stub is a PEP 484 `.pyi` **derived from the test bodies** — the inverse of conventional stub authoring. Every type the tests construct, every method they call, every relationship they assert is the specification of the source surface; the stub records exactly that and nothing speculative. +- `...` bodies only (PEP 484); never `raise NotImplementedError`. The stub is signature-only and compiles for the type checker with no runtime behaviour — behaviour lands in build's green. +- The source `.pyi` is a **fixed contract during build**: green implements the `.py` to satisfy it; refactor cannot edit it; if the body cannot satisfy the `.pyi` without changing it, that is a contract gap escalated at review — never an in-place stub edit. +- **No prescribed layout**, and config is twelve-factor: environment variables plus a gitignored `.env`; a typed Settings model is optional and, if warranted, a normal source stub. External adapters and connectors sit under the package alongside everything else, not as a separate category. +- Structural artifacts are **keyed on what a module is**: an ORM model carries an Alembic migration (the migration IS the schema spec); an external adapter replays the cassettes captured in explore. +- stubtest gates the source pair at green/review/merge — it imports the runtime module (transitive deps must be installed), runs scoped per cycle (the whole-suite run waits until every `.py` exists), and type-only imports go under `TYPE_CHECKING`. The drift mechanics are those of the test pair ([[software-craft/test-stubs]]). + +## Concepts + +**Derived from the tests, not imagined.** Conventional `.pyi` authoring describes an existing or imagined library's public interface for consumers (typing.python.org). Here the source `.pyi` is derived from the test bodies the plan phase already wrote: each type the tests construct, each method they call, each composition they wire is a demand for a definition, and the stub supplies it with an ellipsis body, placed wherever the source lives. Nothing enters the stub that no test references — speculative generality is structurally impossible, because the tests are the truth and the stub is their shadow. + +**Signature-only; `...` not `NotImplementedError`.** PEP 484 specifies that a stub's function bodies be a single ellipsis. `raise NotImplementedError` is runtime behaviour — it executes, and a stub that executes is no longer a pure signature. A `.pyi` with `...` bodies compiles for the type checker and is inert at runtime; the green step replaces each `...` with a real body in the sibling `.py`, never in the `.pyi`. + +**Fixed during build.** Once derived, the source `.pyi` is frozen for the whole build cycle: green writes the `.py` to satisfy it, refactor restructures the `.py` while the `.pyi` stays put, and the tests (already written) stay put too. If implementation discovers the `.pyi` is wrong — a missing parameter, a wrong return type, an impossible signature — the response is never to edit the stub in place; it is to escalate a contract gap at review, which routes back to plan for a proper re-derivation. The frozen stub is what keeps the contract the single source of truth. + +**No layout, no config artifact.** The tests say where the source lives and what it is called; the stub does not prescribe a package structure on top. Adapters, connectors, and domain types live under the package alongside one another — there is no separate skeleton category to author. Configuration is twelve-factor: environment variables are the default, loaded locally from a gitignored `.env`, and a typed Settings model is optional — if it earns its place, it is a normal source stub, not a special artifact the flow requires. + +**Structural artifacts keyed to the module.** Some modules carry an artifact beyond the `.py` pair. An ORM model owns an Alembic migration — the migration is the schema spec, born in green, committed in ship, never edited only appended. An external adapter replays the cassettes captured during explore (`VCR_RECORD_MODE=none`). The stub itself does not generate these; it declares the module's surface, and green emits whatever that surface implies. + +**stubtest, scoped.** The source pair is drift-checked by `mypy.stubtest` at green, review, and merge. The run is scoped to the modules built this cycle, because a whole-suite stubtest before every `.py` exists fails on unbuilt sibling stubs. stubtest imports the runtime module, so every transitive dependency must be installed in the project venv; imports that exist only for types go under `if typing.TYPE_CHECKING:` so stubtest does not drag heavy runtime deps in for type-only references. The mechanism — why the checker hides drift, why stubtest is the only detector — is the same as for the test pair. + +## Content + +### Derived from the tests + +| The test body asserts | The stub must declare | +|---|---| +| `RatesAdapter(base).fetch_rate("USD")` returns a `Rate` | class `RatesAdapter` with `__init__(self, base: str)` and `fetch_rate(...) -> Rate` | +| `History(db_url).record(c)` then `.recent()` | class `History` with `__init__(self, db_url: str)`, `record(...)`, `recent()` returning the iterator the test consumes | +| `Settings.from_env()` yields `.api_base` and `.db_url` | class `Settings` (frozen) with those attributes and the `from_env()` classmethod | + +If a value's representation is ambiguous across tests — a database URL passed as a bare filesystem path in one and a `sqlite:///path` URL in another — pin one canonical form once (the URL form) and state it in the stub, so every consumer agrees rather than each test improvising a shape the others break on. + +### Signature-only + +``` +class Rate: + base: str + value: float + def __init__(self, base: str, value: float) -> None: ... + def convert(self, amount: float) -> float: ... +``` + +No `raise NotImplementedError`, no `pass` body, no docstring — `...` only. The `.py` written in green fills these bodies with real logic; the `.pyi` never carries it. + +### Fixed during build + +| Phase | Who moves | Who stays | +|---|---|---| +| green | the `.py` (written to satisfy the `.pyi`) | `.pyi`, tests | +| refactor | the `.py` (restructured for quality) | `.pyi`, tests | +| review (gap found) | escalate to plan — re-derive | nothing edited in place | + +The asymmetry is deliberate: the `.pyi` and the tests are the contract, and contracts do not move while one party is implementing. A green or refactor that needs to change the `.pyi` is signalling the contract was wrong, which is a plan-phase decision, not a build-phase liberty. + +### No layout, no config artifact + +The package takes whatever shape the tests import from; there is no separate skeleton or ports layer to author. Configuration is twelve-factor — environment variables are the source, a gitignored `.env` carries local secrets, `python-dotenv` loads it. A `Settings` model is not required by the flow; if it is worth the code, it is one normal source stub among the rest, reading `os.environ` in its `from_env()`. + +### Structural artifacts keyed to the module + +| Module kind | Extra artifact | Born in | Lifecycle | +|---|---|---|---| +| ORM model | Alembic migration (the schema spec) | green | committed in ship; a new cycle adds a new migration, never edits an old one | +| external adapter | replayed cassette (`VCR_RECORD_MODE=none`) | explore | committed; re-recorded only on a real mismatch | + +The stub declares the module's surface; green emits whatever that surface implies. A pure domain service with no persistence and no external boundary carries no extra artifact at all. + +### stubtest, scoped + +stubtest gates the source pair the same way it gates the test pair; the mechanics — `.pyi`-preferred hides drift from pyright, stubtest imports at runtime via `inspect`, it checks structure not return-type accuracy — are in [[software-craft/test-stubs]]. The source-specific discipline is scoping: `stubtest . tests.` at green/review covers only the modules touched this cycle, because sibling source `.pyi` whose `.py` are not yet built would all false-fail a whole-suite run. The whole-suite `stubtest tests` runs once, at merge, when every `.py` exists. + +## Related + +- [[software-craft/test-stubs]] — the shared drift mechanics (`.pyi`-preferred; stubtest as the sole detector); the test pair +- [[software-craft/tdd]] — the red/green/refactor cycle that implements these stubs +- [[software-craft/design-patterns]] — patterns the implementation may apply to satisfy a stub cleanly +- [[software-craft/solid]], [[software-craft/object-calisthenics]] — the quality bar the implementation is held to diff --git a/TODO.md b/TODO.md index ac384ffc..596b4f58 100644 --- a/TODO.md +++ b/TODO.md @@ -239,10 +239,10 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [x] `software-craft/test-stubs.md` — PEP 484 `.pyi` signature files for tests (disambiguated from the Meszaros test double); `.pyi`-preferred hides drift from pyright, stubtest is the sole detector; mirror the complete module surface; stdlib-typing-only with types under `TYPE_CHECKING`. *(author-test-stubs, simulate-contracts)*. AUTHORED. - [x] `software-craft/test-design.md` — Observable behaviour not implementation; sociable tests at two grains only (integration narrow + E2E broad, no solitary unit); one behaviour per test; spec value fidelity; property tests (Hypothesis) prove invariants. *(author-test-stubs, write-test-py)*. AUTHORED. - [x] `software-craft/code-review.md` — Adversarial review (Fagan 1976; Tetlock); fail-fast at the first defect; reviewer reports APPROVED/REJECTED only, never edits, "minor" is not a pass; two modes (review-test-stubs = coverage/scope/happy-path vs interview; review-implementation = correctness/quality/drift/green); PASS/FAIL record per criterion. *(review-test-stubs, review-implementation)*. AUTHORED. -- [ ] `software-craft/solid.md` — SOLID principles (SRP/OCP/LSP/ISP/DIP) applied to source + test structure. *(write-test-py, refactor-green, review-implementation)* -- [ ] `software-craft/object-calisthenics.md` — Object Calisthenics rules (1-level indent, no getters, etc.) for structural quality. *(write-test-py, refactor-green)* -- [ ] `software-craft/smell-catalogue.md` — Code-smell detection signals (long method, god class, duplication, …). *(write-test-py, refactor-green, review-implementation)* -- [ ] `software-craft/source-stubs.md` — Source `.pyi` conventions: signature-only, ellipsis body, no prescribed layout, canonical data-shape pinning; stubtest scope rules. *(derive-source-stubs, implement-from-stub)* +- [x] `software-craft/solid.md` — The 5 SOLID principles (Martin 2000/2003), applied when a smell triggers, never speculatively; violation→smell→fix map. *(write-test-py, refactor-green, review-implementation)*. AUTHORED. +- [x] `software-craft/object-calisthenics.md` — Jeff Bay's 9 rules (ThoughtWorks Anthology, 2008): an exercise-turned-guideline, applied as the quality bar not a literal counter. *(write-test-py, refactor-green)*. AUTHORED. +- [x] `software-craft/smell-catalogue.md` — Fowler's (1999) 5 categories (Bloaters, OO Abusers, Change Preventers, Dispensables, Couplers) with Smell/Signal/Fix tables; a Comment is a symptom of code needing extraction. *(write-test-py, refactor-green, review-implementation)*. AUTHORED. +- [x] `software-craft/source-stubs.md` — Source `.pyi` derived from the test bodies (inverse of conventional); signature-only `...`; FIXED during build (escalate on gap); no prescribed layout; config 12-factor; structural artifacts keyed to the module; scoped stubtest. *(derive-source-stubs, implement-from-stub)*. AUTHORED. - [ ] `requirements/spec-simulation.md` — Mental-simulation technique: "if an impl passes these tests, is the result complete + correct?" *(simulate-contracts)* **Build (implement):** From e48289ee1d10027c98b3eef9cafa88b0d3bc4224 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 17:02:46 -0400 Subject: [PATCH 07/28] feat(knowledge): tdd + design-patterns + refactoring-techniques MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build-phase software-craft cluster, each rethought for this flow: - tdd.md (77ln): red/green/refactor ADAPTED — tests pre-exist, so red un-marks + confirms the right failure (ImportError=new, assertion=rework); minimum code YAGNI/KISS; refactor under green with .pyi frozen + design-only; per-contract cycle in outside-in dependency order; scoped stubtest. - design-patterns.md (64ln): GoF patterns applied only when a smell triggers (Gamma 1994, Shvets 2014); foregrounds the small set this flow's architecture hosts (Adapter at boundary, Repository, Facade/app-service, Strategy/State, Factory, value object); smell->pattern lookup. - refactoring-techniques.md (87ln): Fowler's (1999) moves organised by problem category as a reference index (drops step-by-step mechanics to skill/book); .pyi fixed under green; convention compliance is CI's job, not refactor's. Knowledge progress: 15/18 authored. Remaining software-craft: git-conventions, versioning (Deliver); plus requirements/spec-simulation (Plan). --- .../software-craft/design-patterns.md | 64 ++++++++++++++ .../software-craft/refactoring-techniques.md | 87 +++++++++++++++++++ .opencode/knowledge/software-craft/tdd.md | 77 ++++++++++++++++ TODO.md | 6 +- 4 files changed, 231 insertions(+), 3 deletions(-) create mode 100644 .opencode/knowledge/software-craft/design-patterns.md create mode 100644 .opencode/knowledge/software-craft/refactoring-techniques.md create mode 100644 .opencode/knowledge/software-craft/tdd.md diff --git a/.opencode/knowledge/software-craft/design-patterns.md b/.opencode/knowledge/software-craft/design-patterns.md new file mode 100644 index 00000000..d1829026 --- /dev/null +++ b/.opencode/knowledge/software-craft/design-patterns.md @@ -0,0 +1,64 @@ +--- +domain: software-craft +tags: [design-patterns, gof, oop, refactor, architecture] +last-updated: 2026-07-01 +--- + +# Design Patterns + +## Key Takeaways + +- Patterns are applied **only when a smell triggers them**, never speculatively — the smell points at the gap, the pattern supplies the structure (Gamma et al., 1994; Shvets, 2014). +- The patterns this workflow's architecture actually hosts are few and recur: **Adapter** at each external boundary, **Repository** for persistence, **Facade** / application service at the entry point, **Strategy / State** for variant behaviour, **Factory** for construction that must not be scattered. +- **Creational** smells (the same object built in several places, telescoping setup) trigger Factory Method or Builder. +- **Structural** smells (branching on a type field, feature envy, parallel hierarchies) trigger Strategy, Adapter, Move Method, or Bridge. +- **Behavioural** smells (one class's state field sprouting conditionals, fan-out notification, two functions sharing a skeleton) trigger State, Observer, or Template Method. +- The core heuristic: if adding a variant means editing existing functions, that is the smell a pattern removes — the code should be open for extension and closed for modification (OCP). + +## Concepts + +**Applied when triggered, not collected.** A pattern is a structural fix for a recurring problem, and the problem announces itself as a smell (Gamma et al., 1994; Shvets, 2014). Applying a pattern without the smell is Speculative Generality — an abstraction bought against a future that never arrives — which the smell catalogue rejects on sight. The discipline is to let the smell name the gap and the pattern fill it, never to fit the code to a pattern because the pattern is familiar. + +**A small, recurring set.** This workflow's outside-in layering produces a handful of patterns repeatedly. An external service attaches behind an **Adapter** that presents the boundary as a protocol the domain understands; persistence sits behind a **Repository** that loads and stores aggregates; the entry point (a CLI, a request handler) is a thin **Facade** or application service composing the pieces; variant behaviour is **Strategy** or **State**, not a type field with a switch; construction that several callers share is a **Factory**. Most contracts need none of these; when one does, the smell makes it obvious which. + +**Creational, structural, behavioural.** The GoF categories still sort the triggers. Creational smells cluster around *how objects are built* — scattered `__init__` calls, telescoping constructors — and yield Factory or Builder. Structural smells cluster around *how types are wired* — a switch on a kind, a method that envies its neighbour, two hierarchies growing in lockstep — and yield Strategy, Adapter, Move Method, or Bridge. Behavioural smells cluster around *how responsibility is distributed* — a state machine outgrowing its class, a change fanning out to many listeners, two algorithms sharing a skeleton — and yield State, Observer, or Template Method. + +**Open for extension, closed for modification.** The single thread through pattern selection is the Open-Closed Principle: a place in the code that must be edited every time the domain grows is a defect, and the pattern that removes it is the one that lets a new variant arrive as a new type fitting an existing interface. Procedural code is open to modification; the pattern closes it and opens it to extension instead. + +## Content + +### Smell → pattern lookup + +| Smell | Pattern | +|---|---| +| same object constructed in 3+ places | Factory Method | +| multi-step setup before an object is valid | Builder | +| `if/elif` branching on a type/kind/status field | Strategy (behaviour varies) or State (transitions) | +| a method uses another class's data more than its own | Move Method | +| two hierarchies growing in lockstep | Bridge | +| one state field sprouting conditionals across methods | State | +| a change fans out to many listeners directly | Observer | +| two functions share an algorithm skeleton, differ in a step | Template Method | +| an external service with the wrong interface | Adapter | +| a complex subsystem needs one simple entry point | Facade | +| primitive and composite objects must be treated the same | Composite | + +### The patterns this workflow hosts + +| Pattern | Where it appears in this flow | +|---|---| +| Adapter | wraps an external service behind a protocol the domain speaks (the cassettes replay through it) | +| Repository | loads and stores aggregates; hides the persistence mechanism behind a collection-like interface | +| Facade / application service | the entry point — a CLI command, a handler — that composes the pieces and owns no domain logic | +| Strategy / State | replaces a type-field switch with a polymorphic hierarchy | +| Factory | centralises construction shared by several callers | +| value object | a small, immutable, domain-typed wrapper (OC-3) — `Rate`, `Amount`, not bare `float` | + +A contract that needs none of these is the common case; a contract that needs one announces it through a smell that the review and refactor steps surface. + +## Related + +- [[software-craft/smell-catalogue]] — the smells that trigger pattern selection +- [[software-craft/solid]] — OCP, the principle behind "open for extension, closed for modification" +- [[software-craft/refactoring-techniques]] — the smaller moves applied before a pattern is warranted +- [[software-craft/source-stubs]] — the `.pyi` an adapter or repository is implemented to satisfy diff --git a/.opencode/knowledge/software-craft/refactoring-techniques.md b/.opencode/knowledge/software-craft/refactoring-techniques.md new file mode 100644 index 00000000..d16ee093 --- /dev/null +++ b/.opencode/knowledge/software-craft/refactoring-techniques.md @@ -0,0 +1,87 @@ +--- +domain: software-craft +tags: [refactoring, fowler, code-quality, refactor-moves] +last-updated: 2026-07-01 +--- + +# Refactoring Techniques + +## Key Takeaways + +- Refactoring moves are organised by the problem they solve: **composing methods, moving features between objects, organising data, simplifying conditional expressions, simplifying method calls, dealing with generalisation** (Fowler, 1999). +- **Extract Method is the workhorse** — most other moves depend on methods being small enough to name clearly; Long Method is the commonest smell and extraction its commonest fix. +- **Move features to the object that owns the data**: Feature Envy, Inappropriate Intimacy, and Message Chains are all resolved by relocating behaviour next to the data it depends on. +- **Replace conditionals with polymorphism or guard clauses**: Switch Statements and nested `if`s dissolve into a type hierarchy or a sequence of early returns. +- Every move runs **under green tests with the `.pyi` fixed** — a move that needs to change the `.pyi` is a contract gap escalated at review, not a refactor liberty. Mechanics live in Fowler and in the refactor skill; this is the index that points at the right move. + +## Concepts + +**Composing methods.** Most refactorings depend on methods being short enough to name, which makes composing methods the foundation (Fowler, 1999). Extract Method turns a fragment of a long method into a named helper; Inline Method inverts it when the name adds nothing; Replace Temp with Query turns a temporary variable into a method call so the value is available everywhere. These are the moves that make every other category possible, because they produce the small, named units the others rearrange. + +**Moving features between objects.** Behaviour belongs next to the data it uses. Feature Envy — a method that reaches into another class more than its own — is fixed by Move Method; a class doing too much is split by Extract Class; a class doing too little is collapsed by Inline Class; a chain `a.b().c()` is shortened by Hide Delegate. The shared move is relocation: put the method on the object that owns the data it depends on. + +**Organising data.** Primitive Obsession is fixed by wrapping a bare value in a domain type (Replace Data Value with Object — the OC-3 rule enforced after the fact); a directly-exposed collection is protected by Encapsulate Collection; a type code that selects behaviour is replaced by a State or Strategy hierarchy. The theme is giving data a home that carries both its meaning and its constraints. + +**Simplifying conditionals and calls.** A complex conditional is decomposed into named guards (Decompose Conditional, Replace Nested Conditional with Guard Clauses); a conditional that switches on type is replaced by polymorphism. Method calls are simplified in parallel — Rename Method for clarity, Introduce Parameter Object and Preserve Whole Object for parameter lists, Replace Constructor with Factory Method when construction itself is the responsibility. Clear conditionals and clear calls are the readable surface of a well-factored module. + +**Dealing with generalisation — under green, `.pyi` fixed.** Inheritance is refined by Pull Up / Push Down Method and Field, by Extract Superclass or Extract Interface, and by Form Template Method when two methods share a skeleton. Misapplied inheritance becomes composition via Replace Inheritance with Delegation. Throughout, the boundary is fixed: the `.py` is fluid under refactor, the `.pyi` and the tests are not, and conventions (docstrings, formatting) are CI's job, not refactor's. A refactor that needs the `.pyi` to move has found a contract gap and escalates rather than edits. + +## Content + +### Composing methods + +| Move | What it does | When | +|---|---|---| +| Extract Method | turn a fragment into a named helper | a method is long or needs a label to read | +| Inline Method | replace a call with the body | the name adds no clarity | +| Replace Temp with Query | turn a temp into a method call | a temp holds a reused expression | +| Extract Variable | name a complex sub-expression | an expression needs a readable intermediate | + +### Moving features between objects + +| Move | What it does | When | +|---|---|---| +| Move Method | relocate a method to the class it envies | Feature Envy | +| Move Field | relocate a field to its heavier user | a field is used mostly elsewhere | +| Extract Class | split a class along an axis | Large Class, too many ivars | +| Inline Class | merge a too-small class into its host | Lazy Class | +| Hide Delegate | route through the middle object | Message Chains | +| Remove Middle Man | call the delegate directly | Middle Man | + +### Organising data + +| Move | What it does | When | +|---|---|---| +| Replace Data Value with Object | wrap a primitive in a domain type | Primitive Obsession | +| Encapsulate Collection | expose a read view, not the collection | a collection field is directly writable | +| Replace Type Code with State/Strategy | replace a type field with a hierarchy | a type field selects behaviour | + +### Simplifying conditional expressions and calls + +| Move | What it does | When | +|---|---|---| +| Decompose Conditional | extract condition, then, else into named methods | a conditional is hard to follow | +| Replace Nested Conditional with Guard Clauses | early-return the edge cases | nested `if/else` | +| Replace Conditional with Polymorphism | move each branch into a subtype | Switch Statements | +| Introduce Null Object | a do-nothing stand-in for `None` | repeated null checks | +| Rename Method | a name that communicates purpose | the name does not say what it does | +| Introduce Parameter Object | bundle a clump into one value | Long Parameter List, Data Clumps | +| Replace Constructor with Factory Method | delegate construction | construction is shared or conditional | + +### Dealing with generalisation + +| Move | What it does | When | +|---|---|---| +| Pull Up Method / Field | hoist common code to the superclass | subclasses repeat it | +| Push Down Method / Field | drop specialised code to the subclass | only some subclasses use it | +| Extract Superclass / Interface | factor common shape up | two classes share an interface | +| Form Template Method | pull a shared skeleton up, vary the steps | two methods share structure, differ in a step | +| Replace Inheritance with Delegation | hold a reference instead of subclassing | Refused Bequest | + +## Related + +- [[software-craft/smell-catalogue]] — the smell that names the problem a move solves +- [[software-craft/object-calisthenics]] — the rules that head the needs off at write time +- [[software-craft/solid]] — the principle a move usually restores +- [[software-craft/design-patterns]] — the larger structure applied when a move is not enough +- [[software-craft/tdd]] — the refactor phase these moves belong to diff --git a/.opencode/knowledge/software-craft/tdd.md b/.opencode/knowledge/software-craft/tdd.md new file mode 100644 index 00000000..cbfde074 --- /dev/null +++ b/.opencode/knowledge/software-craft/tdd.md @@ -0,0 +1,77 @@ +--- +domain: software-craft +tags: [tdd, red-green-refactor, yagni, kiss, contract-driven] +last-updated: 2026-07-01 +--- + +# Test-Driven Development + +## Key Takeaways + +- The cycle is **red → green → refactor** (Beck, 2002). In this workflow the tests already exist — authored in plan with a `@pytest.mark.pending` mark — so red *removes the mark and confirms the right failure*, it does not write a test. +- **The right-reason rule**: a new contract fails with `ImportError` (source `.py` absent, the deferred in-body import cannot resolve); a reworked contract fails with an assertion (source stale against the changed contract). A red for any other reason — a typo, a bad fixture, a test that violates its own contract — is rejected, not patched. +- Green writes the **minimum code** to turn the tests green, implementing the `.py` from its fixed `.pyi`. YAGNI and KISS override every other principle; a hard-coded value is correct when the test needs only that value (Beck & Jeffries, 1999; North, 2006). +- Refactor restructures the `.py` while the `.pyi` and the tests stay **frozen and green**; it is design-only, never convention compliance — conventions run in CI. A change that needs the `.pyi` is a contract gap escalated at review. +- The cycle runs **per contract** — a source module and the tests that exercise it — in outside-in dependency order; stubtest is scoped to the modules built this cycle. + +## Concepts + +**The cycle, adapted.** Beck's (2002) red/green/refactor cycle is the spine, but the entry conditions differ from classical TDD. Here the plan phase has already written the tests as executable specifications (North, 2006), each marked pending so the suite stays green-with-skips. Red is therefore the act of un-marking the target contract's tests and confirming they fail for the right reason; green and refactor then proceed exactly as in classical TDD. The tests drive the implementation because they pre-exist it; what is removed is the test-authoring step, not the test-first discipline. + +**The right-reason rule.** A red that fails for the wrong reason is a broken contract, not a green target. The two right reasons track the two kinds of work: building a contract that has never been implemented yields an `ImportError`, because the deferred import inside each test body cannot resolve a module that does not exist; re-implementing a contract that has changed yields an assertion failure, because the stale source no longer satisfies the revised tests. A red caused by anything else — a name typo, a fixture that does not resolve, a test that contradicts its own `.pyi` — is a defect in the test or the stub, and the response is to reject and escalate, never to patch the test so it fails for an acceptable reason. + +**Minimum code, YAGNI first.** Green writes the simplest code that passes the tests, and "simplest" is enforced by a priority: YAGNI (Beck & Jeffries, 1999) trumps everything — if no test requires it, it is not written — and KISS trumps DRY, because a small duplication is often simpler than the wrong abstraction. Hard-coded values are not just permitted but correct when the test supplies only that value; a configurable constant invented for a future the tests do not describe is exactly the speculative generality YAGNI forbids. + +**Refactor under green, design only.** Refactor improves the `.py`'s structure while every test stays green, because the tests are the safety net that makes restructuring safe. Two boundaries are fixed: the `.pyi` does not move (a refactor that needs to change it has found a contract gap, escalated at review), and conventions do not run (no docstrings, no formatting pass — those are CI's job). Refactor is where SOLID, Object Calisthenics, and the smell catalogue are applied, each when its symptom appears, never speculatively. + +**Per contract, in dependency order.** The unit of work is one contract: a source module and the tests that exercise it, taken through the whole cycle. Contracts are picked in outside-in dependency order so that a module is built only after the modules it imports; a shared foundation module with no external boundary of its own is pulled in alongside the first contract that depends on it. stubtest runs scoped to the modules built this cycle, because the whole-suite run would false-fail on unbuilt sibling stubs. + +## Content + +### The cycle, adapted + +| Phase | Classical TDD | This workflow | +|---|---|---| +| red | write a failing test | un-mark an existing test; confirm it fails for the right reason | +| green | minimum code to pass | implement `.py` from its fixed `.pyi` | +| refactor | improve structure, stay green | improve `.py`; `.pyi` and tests frozen; design only | + +The discipline test-first is preserved — the tests still precede the implementation — by the plan phase writing them ahead of time, not by the build phase writing them inline. + +### The right-reason rule + +| Red reason | Kind of work | Verdict | +|---|---|---| +| `ImportError` on the deferred in-body import | new contract (source absent) | right reason — proceed to green | +| assertion failure against changed tests | rework (source stale) | right reason — re-implement | +| `NameError`, fixture resolution, test contradicts its `.pyi` | test or stub defect | reject — escalate, do not patch | + +### Minimum code, YAGNI first + +- if the test needs only `42`, return `42` — do not invent a configurable constant; +- no parameter, abstraction, or branch the test does not exercise; +- a small duplication beats a premature abstraction (KISS over DRY); +- when the trivial implementation passes, the next test is the cure, not more code. + +### Refactor under green, design only + +| Allowed in refactor | Not allowed | +|---|---| +| restructure the `.py` | edit the `.pyi` (escalate a contract gap) | +| apply SOLID / Object Calisthenics / smell fixes when triggered | edit the tests | +| design improvement only | convention compliance (docstrings, formatting — CI's job) | + +### Per contract, in dependency order + +- one contract per cycle: a source module and its tests, red through ship; +- pick the lowest-layer contract first; a module is built after what it imports; +- a shared foundation module rides alongside the first contract that needs it; +- stubtest is scoped: `stubtest . tests.` this cycle, whole-suite at merge. + +## Related + +- [[software-craft/test-design]] — what a good test looks like (the specifications red un-marks) +- [[software-craft/test-stubs]] — the `.pyi`/`.py` pair whose drift green keeps clean +- [[software-craft/source-stubs]] — the fixed `.pyi` green implements to +- [[software-craft/refactoring-techniques]] — the moves refactor applies +- [[software-craft/code-review]] — the review that gates the cycle's output diff --git a/TODO.md b/TODO.md index 596b4f58..ac86434d 100644 --- a/TODO.md +++ b/TODO.md @@ -246,9 +246,9 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [ ] `requirements/spec-simulation.md` — Mental-simulation technique: "if an impl passes these tests, is the result complete + correct?" *(simulate-contracts)* **Build (implement):** -- [ ] `software-craft/tdd.md` — Red-green-refactor cycle; right-reason-for-failure rule; pending-mark/backlog discipline; scoped-vs-whole stubtest. *(select-build-target, confirm-red-failure, implement-from-stub)* -- [ ] `software-craft/design-patterns.md` — Design patterns (adapter, facade, …) for composing source from a stub. *(implement-from-stub)* -- [ ] `software-craft/refactoring-techniques.md` — Refactoring moves (extract method, etc.) applied under green tests with `.pyi` fixed. *(refactor-green)* +- [x] `software-craft/tdd.md` — The red/green/refactor cycle adapted: tests pre-exist so red un-marks + confirms the right failure (ImportError = new, assertion = rework); minimum code YAGNI/KISS; refactor under green with `.pyi` frozen; per-contract in dependency order. *(select-build-target, confirm-red-failure, implement-from-stub)*. AUTHORED. +- [x] `software-craft/design-patterns.md` — GoF patterns applied only when a smell triggers (Gamma 1994; Shvets 2014); foregrounds the small set this flow's architecture hosts (Adapter, Repository, Facade, Strategy/State, Factory, value object); smell→pattern lookup. *(implement-from-stub)*. AUTHORED. +- [x] `software-craft/refactoring-techniques.md` — Fowler's (1999) refactor moves organised by problem (composing methods, moving features, organising data, simplifying conditionals/calls, generalisation); reference index pointing at the right move, mechanics deferred to the skill/book; `.pyi` fixed under green. *(refactor-green)*. AUTHORED. **Deliver (ship):** - [ ] `software-craft/git-conventions.md` — Commit + branch conventions (imperative messages, one logical change, feature/dev/release branches). *(ship-unit, merge-to-dev, publish-release)* From ab72a504642ed23b31d42faa1cd11765ac269277 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 17:05:40 -0400 Subject: [PATCH 08/28] feat(knowledge): git-conventions + versioning (software-craft complete) Deliver-phase software-craft cluster; completes all 13 software-craft knowledges: - git-conventions.md (75ln): Conventional Commits form; one logical change per commit (ship-unit = one contract, .pyi unchanged); refactor separate from feature; three-branch model feature->dev->release/main; squash-merge into dev gates whole-suite + whole-suite stubtest. - versioning.md (59ln): SemVer 2.0.0 bump rules + 0.x instability; PEP 440 for Python (X.Y.Z core, +local stripped by indexes); CalVer when timing beats compatibility; pyproject version is single source of truth; publish-release picks notes / PR to main / v{version} tag. Software-craft cluster complete (13/13). Overall knowledge: 17/18 authored. Sole remaining cited knowledge: requirements/spec-simulation (Plan phase, requirements/). --- .../software-craft/git-conventions.md | 75 +++++++++++++++++++ .../knowledge/software-craft/versioning.md | 59 +++++++++++++++ TODO.md | 4 +- 3 files changed, 136 insertions(+), 2 deletions(-) create mode 100644 .opencode/knowledge/software-craft/git-conventions.md create mode 100644 .opencode/knowledge/software-craft/versioning.md diff --git a/.opencode/knowledge/software-craft/git-conventions.md b/.opencode/knowledge/software-craft/git-conventions.md new file mode 100644 index 00000000..1cc8673e --- /dev/null +++ b/.opencode/knowledge/software-craft/git-conventions.md @@ -0,0 +1,75 @@ +--- +domain: software-craft +tags: [git, commits, conventional-commits, branching, squash-merge] +last-updated: 2026-07-01 +--- + +# Git Conventions + +## Key Takeaways + +- Commits follow **Conventional Commits**: `(): ` — types `feat`, `fix`, `test`, `refactor`, `chore`, `docs`, `ci`; no `wip`, `temp`, or untyped commit (Conventional Commits 1.0.0). +- **One logical change per commit** — `ship-unit` commits the built contract's `.py` plus the structural artifacts it required as one change, and the `.pyi` is unchanged (contracts are fixed during build). +- **Refactor commits are separate from feature commits**; a structural change is never mixed with a behaviour addition, so history stays bisectable and every commit leaves the tests green. +- The branch model is **`feature` → `dev` → `release`/`main`**: the build cycle runs on `feature`, squash-merges accumulate on `dev`, and publish targets `release` or `main`. Feature branches are short-lived and deleted after their squash-merge. +- `merge-to-dev` squash-merges the feature commits into `dev` as one commit, then verifies the whole suite and the whole-suite stubtest are clean — no pending markers remain, and no drift was smuggled in by the batch. + +## Concepts + +**Conventional Commits.** A commit message is a typed, scoped, imperative sentence: `feat(rates): fetch live rate from provider`, `fix(history): correct latest-first ordering`. The type carries meaning — `feat` and `fix` map to minor and patch version bumps, `refactor` signals no behaviour change, `test`/`chore`/`docs`/`ci` are self-explanatory — and the imperative mood keeps the message readable as a command the change performs. The discipline forbids `wip`, `temp`, and any untyped commit, because a history that cannot be read cannot be bisected. + +**One logical change per commit.** A commit answers one question; mixing concerns produces a history where each entry means several things at once. `ship-unit` commits exactly one contract — the implemented `.py` and the migrations, fixtures, or cassettes it required — and nothing else; the `.pyi` is the same at ship as it was at plan, because contracts do not move during build. The unit of a commit is the unit of a contract. + +**Refactor separate from feature.** A behaviour addition and a structural cleanup are different changes even when they land together, so they are different commits. Mixing them forces a reader (or a `git bisect`) to attribute a test failure to two unrelated changes at once; keeping them apart lets each commit stand as one defensible step, and every commit along the way leaves the tests green. + +**The three-branch model.** Work flows in one direction: a `feature` branch carries a build cycle (red through ship), `dev` accumulates squash-merged contracts and is where integration is verified, and `release` or `main` is the publish target. Feature branches are short-lived — created for a contract, deleted after the squash-merge — so only `dev` and the publish branch are long-lived. + +**Squash-merge into dev.** The granular per-contract commits on `feature` collapse into one commit on `dev`, carrying the contract's summary in its message. The merge is the gate where the whole suite and the whole-suite stubtest run: by now every `.pyi` has its `.py`, every pending marker is gone, and any drift the per-cycle scope hid is exposed across the full set. + +## Content + +### Branch model + +| Branch | Lives | Carries | +|---|---|---| +| `feature` | short — one build cycle | the per-contract commits (red → green → refactor → ship) | +| `dev` | long | squash-merged contracts; integration truth | +| `release` / `main` | long | the publish target | + +### Commit format + +``` +(): +``` + +| Type | Means | +|---|---| +| `feat` | a new behaviour (implies a minor bump) | +| `fix` | a bug fix (implies a patch bump) | +| `test` | test-only change | +| `refactor` | structural change, no behaviour change | +| `chore` | tooling, deps, CI | +| `docs` | documentation | +| `ci` | CI configuration | + +### One logical change — what ship-unit commits + +| In the commit | Not in the commit | +|---|---| +| the implemented source `.py` | the `.pyi` (unchanged from plan) | +| the migration / fixture / cassette the module required | unrelated contracts | +| nothing else | a refactor folded in (separate commit) | + +### Squash-merge into dev + +| Step | Check | +|---|---| +| squash `feature` → `dev` | one commit, contract summary in the message | +| run the full suite | every test green; no pending markers remain | +| run whole-suite `stubtest tests` | every source and test pair agrees — no batch drift | + +## Related + +- [[software-craft/tdd]] — the build cycle whose output ship-unit commits +- [[software-craft/code-review]] — the review that gates a commit +- [[software-craft/versioning]] — the version the publish step tags diff --git a/.opencode/knowledge/software-craft/versioning.md b/.opencode/knowledge/software-craft/versioning.md new file mode 100644 index 00000000..f0f67ebd --- /dev/null +++ b/.opencode/knowledge/software-craft/versioning.md @@ -0,0 +1,59 @@ +--- +domain: software-craft +tags: [versioning, semver, pep-440, calver, release] +last-updated: 2026-07-01 +--- + +# Versioning + +## Key Takeaways + +- **SemVer 2.0.0** is `major.minor.patch`: a breaking change bumps `major`, a backward-compatible feature bumps `minor`, a fix bumps `patch`. A `0.major.minor` line carries no stability promise — any release may break (semver.org). +- For a Python project the version in `pyproject.toml` must satisfy **PEP 440**; SemVer's `X.Y.Z` is a subset PEP 440 accepts. A `+local` build segment is stripped by package indexes, so `pyproject.toml` carries the core `X.Y.Z` only (PEP 440; SemVer §10). +- **CalVer** (`YYYY.MM.DD`, `YYYY.MINOR.MICRO`) fits time-released projects with no compatibility promise — it records *when*, not *whether compatible* (calver.org). +- The `version` field in `pyproject.toml` is the **single source of truth**; tags and release notes derive from it, never the reverse. +- `publish-release` chooses among **release notes, a PR to `main`, or a tagged release** (`v{version}`), per the project's release policy. + +## Concepts + +**SemVer, the default.** Semantic Versioning gives a dependency resolver something to reason about: `pkg>=1.2.0,<2.0.0` works because the major version signals a compatibility break. The bump rules are precise — a backward-incompatible change is a major bump however small the code, a backward-compatible addition is a minor bump, a fix is a patch. The special case is `0.x`: below 1.0.0 the spec declares the public API unstable, so a `0.2.0 → 0.3.0` step is allowed to break a consumer, and the major-version compatibility signal is understood to be absent. + +**PEP 440 for Python.** A Python project's version is read by tooling that obeys PEP 440, not raw SemVer; SemVer's `X.Y.Z` form is a subset PEP 440 accepts, so a plain `1.2.3` is valid in both. Where they diverge is build metadata: SemVer §10 allows a `+build` suffix, but PEP 440 treats `+local` as a *local* version segment that package indexes strip — a version like `1.2.3+20260701` publishes to the index as `1.2.3`. The consequence for a Python project is that the `pyproject.toml` `version` field carries the publishable core (`1.2.3`), and any date or build suffix is a tag-only concern, not a field that goes to the index. + +**CalVer, when timing matters more than compatibility.** Calendar Versioning leads with the date — `2026.4`, `26.7.1` — and suits projects that release on a cadence and make no consumer compatibility promise (operating systems, terminal apps, services with no external API). It carries timing clearly and fails to carry compatibility at all, so a consumer cannot bound an acceptable range the way SemVer's major version allows. Choose CalVer when the audience reads the date; choose SemVer when the audience bounds a range. + +**Single source of truth.** The version lives in `pyproject.toml` and nowhere else; a tag, a release note, and a changelog entry are all derived from it. Maintaining a version in two places (a field and a tag that drifts) is the same defect as any duplicated truth — they diverge, and the divergence is discovered at release time under pressure. + +**Publish is a policy choice.** `publish-release` does not assume one form of release; it picks among release notes, a PR to `main`, and a tagged release, according to what the project has decided its release policy is. A library tags and publishes; an internal service may merge a PR to `main` and stop; an early-stage project may ship only notes. The versioning knowledge fixes what a version *is*; the release policy fixes *how* a version ships. + +## Content + +### SemVer bump rules + +| Change | Bump | Example | +|---|---|---| +| breaking (API contract change) | major | `1.2.3` → `2.0.0` | +| backward-compatible feature | minor | `1.2.3` → `1.3.0` | +| bug fix | patch | `1.2.3` → `1.2.4` | +| anything, while below 1.0.0 | minor may break | `0.2.0` → `0.3.0` (breaking allowed) | + +### Scheme comparison + +| Scheme | Form | Carries | Fits | +|---|---|---|---| +| SemVer | `MAJOR.MINOR.PATCH` | compatibility | libraries, packages with consumers | +| CalVer | `YYYY.MINOR.MICRO` | timing | cadence-released apps, services, OS-like tools | +| SemVer + local tag | `X.Y.Z` (field), `vX.Y.Z+date` (tag) | both, split across field and tag | projects that want both but must keep the index field clean | + +### Tag and release forms + +| Output | Form | +|---|---| +| git tag | `v{version}` (e.g. `v1.2.3`) | +| pyproject field | `1.2.3` (PEP 440 core; no `+local`) | +| release notes / changelog | `## [v1.2.3] - {date}` | + +## Related + +- [[software-craft/git-conventions]] — the commit and branch discipline a release rides on +- [[software-craft/code-review]] — the review that gates what gets released diff --git a/TODO.md b/TODO.md index ac86434d..49f4c535 100644 --- a/TODO.md +++ b/TODO.md @@ -251,8 +251,8 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [x] `software-craft/refactoring-techniques.md` — Fowler's (1999) refactor moves organised by problem (composing methods, moving features, organising data, simplifying conditionals/calls, generalisation); reference index pointing at the right move, mechanics deferred to the skill/book; `.pyi` fixed under green. *(refactor-green)*. AUTHORED. **Deliver (ship):** -- [ ] `software-craft/git-conventions.md` — Commit + branch conventions (imperative messages, one logical change, feature/dev/release branches). *(ship-unit, merge-to-dev, publish-release)* -- [ ] `software-craft/versioning.md` — Semantic versioning + release tagging. *(publish-release)* +- [x] `software-craft/git-conventions.md` — Conventional Commits (`(): `); one logical change per commit (ship-unit: one contract, `.pyi` unchanged); refactor separate from feature; three-branch model `feature`→`dev`→`release`/`main`; squash-merge into dev gates whole-suite + stubtest. *(ship-unit, merge-to-dev, publish-release)*. AUTHORED. +- [x] `software-craft/versioning.md` — SemVer 2.0.0 bump rules + 0.x instability; PEP 440 for Python (`X.Y.Z` core, `+local` stripped by indexes); CalVer when timing matters more than compatibility; pyproject `version` is the single source of truth; publish picks notes / PR to main / `v{version}` tag. *(publish-release)*. AUTHORED. ## pyproject + tooling From 5a05203513199b5a83167be44cf520de61810a89 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 17:11:48 -0400 Subject: [PATCH 09/28] feat(knowledge): rethink spec-simulation; complete the 18/18 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete rewrite of spec-simulation, addressing that the prior approach created JSON I/O files for ceremony and did not catch the e2e-affecting issues (composition, cross-test coherence): - spec-simulation.md (105ln): simulation is a MENTAL EXECUTION of the contract set (test .pyi + test .py + source .pyi) — the tests ARE the spec, there is no domain_spec.md to walk. The e2e failures live in composition + cross-test coherence, which tools are blind to: a type imported from a module that does not re-export it; one value in two shapes across tests; a shared module with no test; a dependency cycle. Method: walk the e2e path hop-by-hop (type/value/side-effect tracing to a backing contract) + trace each domain value across tests. Tool floor (pyright/stubtest/no-orphans/traceability) necessary but not sufficient. Output is a judgment + named gaps — no per-walkthrough JSON, no cache. - simulate-contracts skill step 2 now DIRECTS the walkthrough per the leak principle (was a bare 'answer the question'); tool checks kept as the floor. Knowledge cluster COMPLETE: 18/18 authored (Discover 4/4, Explore 1/1, Plan 8/8, Build 3/3, Deliver 2/2). --- .../knowledge/requirements/spec-simulation.md | 105 ++++++++++++++++++ .opencode/skills/simulate-contracts/SKILL.md | 2 +- TODO.md | 2 +- 3 files changed, 107 insertions(+), 2 deletions(-) create mode 100644 .opencode/knowledge/requirements/spec-simulation.md diff --git a/.opencode/knowledge/requirements/spec-simulation.md b/.opencode/knowledge/requirements/spec-simulation.md new file mode 100644 index 00000000..9d6b49d6 --- /dev/null +++ b/.opencode/knowledge/requirements/spec-simulation.md @@ -0,0 +1,105 @@ +--- +domain: requirements +tags: [spec-simulation, mental-execution, composition, cross-test-coherence, gate] +last-updated: 2026-07-01 +--- + +# Spec Simulation + +## Key Takeaways + +- Simulation is a **mental execution of the contract set** — the test `.pyi`, the test `.py`, and the source `.pyi` together — asking whether a correct implementation that passes every test would actually work end-to-end and be complete. The spec is the tests, not prose; the simulation walks the tests. +- The e2e-affecting failures live in **composition and cross-test coherence**, where tools are blind: a type imported from a module that does not re-export it, a value whose shape differs between the tests that produce and consume it, a shared module no test drives, a dependency graph with no valid build order. These surface only when a human walks the contracts. +- **Walk the e2e path hop by hop** — entry point → adapter → domain → persistence. At each hop confirm the type passed, the value carried, and the side effect performed each trace to a backing contract; a broken hop is the simulation's main catch. +- **Trace each domain value across every test that touches it.** If two tests pass the same concept in different shapes, the contract is incoherent; pin one canonical form or split the concept. No tool performs this — it is a reading, not a check. +- The tool floor is **necessary but not sufficient**: pyright (zero errors, tolerate `reportMissingModuleSource` pre-build), stubtest over the test pairs (drift), no-orphans (every source symbol exercised, every test reference backed), traceability (every interview finding → a test or deferral; every external service → a captured cassette). Each catches a class of defect; none catches composition. +- The output is a **judgment with evidence, not an artifact.** No per-walkthrough JSON, no cache of I/O pairs — the simulation's value is the understanding, which lives in the gate decision and the specific gaps it names. + +## Concepts + +**Mental execution of the contract set.** The plan phase produces the contract set: every test written as an executable body, every source symbol recorded as a `.pyi` signature. Simulation is the act of reading that set as if it were already implemented and asking the one question that gates the build: *if a correct implementation made every one of these tests pass, would the resulting system work as intended and be complete?* It is a prediction of the future, made by walking the contracts the future will be built from. The spec being walked is the tests themselves — there is no separate prose document to simulate against — which is what makes the prediction answerable rather than a comparison of two texts. + +**Why the tool floor is not enough.** pyright, stubtest, and the traceability counts each police a class of defect the others miss, and together they form a real floor — but every one of them reads files in isolation or checks a structural invariant, and none of them reads *across* the contract set the way a reader does. A type imported from a module that does not re-export it resolves fine for the checker and breaks at the composition. A value carried as a bare filesystem path by one test and as a `sqlite:///` URL by another is typed `str` in both stubs and passes every check, while the contract it implies is incoherent. A shared data module with no external boundary of its own has no test driving it, and no tool notices the gap. These are the failures that ship to build and surface as e2e breakage; simulation is the step that exists to catch them, because nothing else does. + +**The e2e hop-by-hop walkthrough.** The most powerful reading centres on the broadest test — the one that exercises the entry point — and walks the implementation it implies one hop at a time. The entry point composes an adapter, the adapter calls into the domain, the domain persists through a boundary; at each hop the walkthrough confirms three things: the *type* handed across matches the type the receiver declares, the *value* carried matches the shape the producer emits, and the *side effect* the hop performs is one a contract actually specifies. A hop where the type comes from the wrong module, or the value arrives in a shape the receiver does not accept, is the simulation's main catch — the kind of defect that only appears when the pieces are imagined together. + +**Cross-test value tracing.** Alongside the e2e spine, each domain value is traced across every test that produces or consumes it. The discipline catches the contract that is internally contradicted: the same database URL arrives as a bare path in one test and a URL in another; the same amount is a `float` in the producer and an `int` in the consumer; the same identifier is a string here and a value object there. Two tests disagreeing on a value's shape is not a tolerance the build can paper over — it is an incoherent contract, and the fix is to pin one canonical form (the data-shape rule) or to recognise that two concepts were conflated and split them. A checker sees two well-typed tests; a reader sees the disagreement. + +**The tool floor.** Beneath the readings run the mechanical checks, and they are not optional. pyright at zero errors (tolerating `reportMissingModuleSource`, which is expected when source `.pyi` exist but no `.py` yet) confirms the types are internally consistent. stubtest over the test pairs confirms each test `.pyi` agrees with its `.pyi` sibling. The no-orphans check confirms every source symbol a test could reach is exercised and every test reference is backed by a source `.pyi`. Traceability confirms every interview finding maps to a test or an explicit deferral and every external service has a captured cassette its tests replay. Each is a real filter; none is the simulation. + +**Judgment, not artifact.** The old ceremony — a per-walkthrough JSON pair written to a cache directory to prove the simulation was thorough — is gone, because the artifact was the symptom of the failure: the understanding never made it into the gate decision, it was offloaded into files no one acted on, and the e2e issues shipped to build unsolved. The output of a real simulation is the gate decision itself — *the contract set is coherent and complete; a passing implementation will work* — backed by the specific walkthroughs and traces that justify it, or a named gap that routes back to plan. Where a gap is found it is stated precisely (which hop, which value, which contradiction); where none is found the understanding lives in the decision to advance, not in a file. + +## Content + +### What gets walked + +| Artefact | Role in the simulation | +|---|---| +| test `.py` (the bodies) | the specification — every type constructed, method called, relationship asserted | +| test `.pyi` | the declared module surface each body must agree with | +| source `.pyi` | the implementation surface the tests collectively demand | +| `docs/glossary.md` | the names the tests should use consistently | +| `tests/cassettes/**` | the real external shapes the boundary tests must assert against | + +There is no `domain_spec.md` to walk; the tests are the spec. A finding that cannot be grounded in one of these artefacts is not a simulation finding. + +### The composition failures tools miss + +| Failure | What a tool sees | What the walkthrough sees | +|---|---|---| +| a type imported from a module that does not re-export it | a resolved import | a consumer that will break the composition | +| one value in two shapes across tests | two well-typed values | an incoherent contract | +| a shared data module with no test of its own | no violation | a contract with no driver — who builds it, and when? | +| a dependency cycle in the build order | nothing | no valid outside-in sequence to build in | +| an e2e test whose hops do not all trace to a `.pyi` | a passing test on paper | an end-to-end path with a gap in the middle | + +These are the e2e-affecting failures; each ships silently to build if simulation does not catch it. + +### The e2e hop-by-hop walkthrough + +Walk the entry-point test as if the system were built, hop by hop: + +1. the entry point receives the input the test sends — confirm its type and shape; +2. it composes its first collaborator (an adapter, a service) — confirm the collaborator's `.pyi` exists and accepts what is passed; +3. the collaborator calls inward (domain, persistence) — confirm each call's type and the value's shape at the boundary; +4. any external hop asserts against a captured cassette — confirm the cassette exists and the shape matches; +5. the side effect at the end (a print, a write, a record) — confirm a contract specifies it. + +A hop that fails any confirmation is the gap; name it precisely (which hop, which type, which shape) and route back to plan. + +### Cross-test value tracing + +For each domain value that crosses a boundary, list every test that produces or consumes it and compare the shape: + +| the value | produced as | consumed as | verdict | +|---|---|---|---| +| a database URL | `sqlite:///{path}` (config test) | a bare `{path}` (history test) | **incoherent — pin one form** | +| a rate | a `Rate` value object (rates test) | a `Rate` (cli test) | coherent | +| an amount | `float` (one test) | `int` (another) | **incoherent — split or unify** | + +Two shapes for one concept is a defect to resolve at plan, not a tolerance for build to absorb. + +### The tool floor + +| Check | Catches | Does not catch | +|---|---|---| +| pyright (0 errors; tolerate `reportMissingModuleSource`) | internal type inconsistency | cross-file composition | +| stubtest over test pairs | `.pyi`↔`.py` drift | whether the contract is coherent | +| no-orphans | unexercised source symbols, dangling test references | shared-module coverage gaps | +| traceability | an untested finding, an un-cassocked service | whether the tests agree | + +### The output + +The simulation produces one of two outcomes, and nothing else: + +- **coherent and complete** — the walkthrough reached no broken hop, the value traces found no disagreement, the tool floor is clean; advance to build. +- **a named gap** — which hop broke, which value disagreed, which module has no driver; route back to plan with the specifics. + +No JSON, no cache directory, no I/O pairs. The understanding is the output, and it lives in the gate decision. + +## Related + +- [[software-craft/test-stubs]] — the `.pyi`/`.py` pairs the tool floor checks +- [[software-craft/test-design]] — what a complete test set looks like (the surface being walked) +- [[software-craft/source-stubs]] — the data-shape rule that resolves an incoherent value +- [[requirements/domain-decomposition]] — the traceability the simulation re-checks diff --git a/.opencode/skills/simulate-contracts/SKILL.md b/.opencode/skills/simulate-contracts/SKILL.md index 0f4a014b..a05c4d63 100644 --- a/.opencode/skills/simulate-contracts/SKILL.md +++ b/.opencode/skills/simulate-contracts/SKILL.md @@ -6,7 +6,7 @@ description: "Answer whether a correct implementation passing every test would y # Simulate Contracts 1. Load [[requirements/spec-simulation]], [[software-craft/test-stubs]] — the simulation method and test-pair drift rules. -2. Answer one question: IF a correct implementation made every test in the set pass THEN would the result work as intended and be complete per [[requirements/spec-simulation]]? +2. Answer the gate question per [[requirements/spec-simulation]]: IF a correct implementation made every test in the set pass THEN would the result work as intended and be complete? Answer it by walking — walk the e2e path hop by hop (each type handed across, each value carried, each side effect performed tracing to a backing contract), then trace each domain value across every test that touches it for shape coherence. The tool checks below are the floor that makes the walk safe to trust; they are not the walk. IF a hop breaks or two tests disagree on a value's shape THEN name the gap precisely and stop — route back to plan, do not advance on a clean tool run alone. 3. Run pyright on the combined set. The gate is zero errors; `reportMissingModuleSource` is expected (source .pyi exist but no .py yet) and is tolerated. 4. Check no-orphans: every source .pyi symbol is exercised by at least one test, and every test reference is backed by a source .pyi. 5. Check traceability: every consolidated interview finding maps to at least one test or an explicit deferral, and every external service has a captured cassette its tests replay. diff --git a/TODO.md b/TODO.md index 49f4c535..481ff04c 100644 --- a/TODO.md +++ b/TODO.md @@ -243,7 +243,7 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [x] `software-craft/object-calisthenics.md` — Jeff Bay's 9 rules (ThoughtWorks Anthology, 2008): an exercise-turned-guideline, applied as the quality bar not a literal counter. *(write-test-py, refactor-green)*. AUTHORED. - [x] `software-craft/smell-catalogue.md` — Fowler's (1999) 5 categories (Bloaters, OO Abusers, Change Preventers, Dispensables, Couplers) with Smell/Signal/Fix tables; a Comment is a symptom of code needing extraction. *(write-test-py, refactor-green, review-implementation)*. AUTHORED. - [x] `software-craft/source-stubs.md` — Source `.pyi` derived from the test bodies (inverse of conventional); signature-only `...`; FIXED during build (escalate on gap); no prescribed layout; config 12-factor; structural artifacts keyed to the module; scoped stubtest. *(derive-source-stubs, implement-from-stub)*. AUTHORED. -- [ ] `requirements/spec-simulation.md` — Mental-simulation technique: "if an impl passes these tests, is the result complete + correct?" *(simulate-contracts)* +- [x] `requirements/spec-simulation.md` — Mental execution of the contract SET (tests are the spec, not prose): walk the e2e path hop-by-hop + trace each domain value across tests for shape coherence; the tool floor (pyright/stubtest/no-orphans/traceability) is necessary but not sufficient — composition + cross-test coherence are tool-blind. Output is a judgment + named gaps, not JSON ceremony. *(simulate-contracts)*. AUTHORED. **Build (implement):** - [x] `software-craft/tdd.md` — The red/green/refactor cycle adapted: tests pre-exist so red un-marks + confirms the right failure (ImportError = new, assertion = rework); minimum code YAGNI/KISS; refactor under green with `.pyi` frozen; per-contract in dependency order. *(select-build-target, confirm-red-failure, implement-from-stub)*. AUTHORED. From 44e446b110933ddde12942ffbeb7f55cd233fb29 Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 1 Jul 2026 17:23:27 -0400 Subject: [PATCH 10/28] fix(knowledge): drop phantom-by-negation noise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Defining-by-negation against artifacts that do not exist in this project (referencing the backup's mechanisms a reader has never seen) is noise. - spec-simulation.md: drop 'there is no domain_spec.md', 'not prose', 'no separate prose document', and the 'old ceremony / per-walkthrough JSON / cache directory' contrast passage. Reframe KT6, the 'Judgment' concept, and the 'What gets walked' / 'The output' subsections positive. - source-stubs.md: drop 'skeleton category' / 'skeleton or ports layer' (backup hexagonal-ports phantom); state the layout point positive. Audited all 18 knowledge files: remaining negations ('no human in the loop', 'no third verdict', 'no way to traverse another aggregate', the runtime state-change 'no longer') are real constraints, not phantom contrasts — kept. --- .opencode/knowledge/requirements/spec-simulation.md | 12 ++++++------ .opencode/knowledge/software-craft/source-stubs.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.opencode/knowledge/requirements/spec-simulation.md b/.opencode/knowledge/requirements/spec-simulation.md index 9d6b49d6..13320369 100644 --- a/.opencode/knowledge/requirements/spec-simulation.md +++ b/.opencode/knowledge/requirements/spec-simulation.md @@ -8,16 +8,16 @@ last-updated: 2026-07-01 ## Key Takeaways -- Simulation is a **mental execution of the contract set** — the test `.pyi`, the test `.py`, and the source `.pyi` together — asking whether a correct implementation that passes every test would actually work end-to-end and be complete. The spec is the tests, not prose; the simulation walks the tests. +- Simulation is a **mental execution of the contract set** — the test `.pyi`, the test `.py`, and the source `.pyi` together — asking whether a correct implementation that passes every test would actually work end-to-end and be complete. - The e2e-affecting failures live in **composition and cross-test coherence**, where tools are blind: a type imported from a module that does not re-export it, a value whose shape differs between the tests that produce and consume it, a shared module no test drives, a dependency graph with no valid build order. These surface only when a human walks the contracts. - **Walk the e2e path hop by hop** — entry point → adapter → domain → persistence. At each hop confirm the type passed, the value carried, and the side effect performed each trace to a backing contract; a broken hop is the simulation's main catch. - **Trace each domain value across every test that touches it.** If two tests pass the same concept in different shapes, the contract is incoherent; pin one canonical form or split the concept. No tool performs this — it is a reading, not a check. - The tool floor is **necessary but not sufficient**: pyright (zero errors, tolerate `reportMissingModuleSource` pre-build), stubtest over the test pairs (drift), no-orphans (every source symbol exercised, every test reference backed), traceability (every interview finding → a test or deferral; every external service → a captured cassette). Each catches a class of defect; none catches composition. -- The output is a **judgment with evidence, not an artifact.** No per-walkthrough JSON, no cache of I/O pairs — the simulation's value is the understanding, which lives in the gate decision and the specific gaps it names. +- The output is a **judgment with evidence**: the gate decision — advance, or a named gap — backed by the walkthroughs and traces that justify it. The simulation's value is the understanding that informs the decision. ## Concepts -**Mental execution of the contract set.** The plan phase produces the contract set: every test written as an executable body, every source symbol recorded as a `.pyi` signature. Simulation is the act of reading that set as if it were already implemented and asking the one question that gates the build: *if a correct implementation made every one of these tests pass, would the resulting system work as intended and be complete?* It is a prediction of the future, made by walking the contracts the future will be built from. The spec being walked is the tests themselves — there is no separate prose document to simulate against — which is what makes the prediction answerable rather than a comparison of two texts. +**Mental execution of the contract set.** The plan phase produces the contract set: every test written as an executable body, every source symbol recorded as a `.pyi` signature. Simulation is the act of reading that set as if it were already implemented and asking the one question that gates the build: *if a correct implementation made every one of these tests pass, would the resulting system work as intended and be complete?* It is a prediction of the future, made by walking the contracts the future will be built from. Because the contracts are executable, the prediction is answerable: every type, call, and side effect the simulation reasons about is one a test will enforce. **Why the tool floor is not enough.** pyright, stubtest, and the traceability counts each police a class of defect the others miss, and together they form a real floor — but every one of them reads files in isolation or checks a structural invariant, and none of them reads *across* the contract set the way a reader does. A type imported from a module that does not re-export it resolves fine for the checker and breaks at the composition. A value carried as a bare filesystem path by one test and as a `sqlite:///` URL by another is typed `str` in both stubs and passes every check, while the contract it implies is incoherent. A shared data module with no external boundary of its own has no test driving it, and no tool notices the gap. These are the failures that ship to build and surface as e2e breakage; simulation is the step that exists to catch them, because nothing else does. @@ -27,7 +27,7 @@ last-updated: 2026-07-01 **The tool floor.** Beneath the readings run the mechanical checks, and they are not optional. pyright at zero errors (tolerating `reportMissingModuleSource`, which is expected when source `.pyi` exist but no `.py` yet) confirms the types are internally consistent. stubtest over the test pairs confirms each test `.pyi` agrees with its `.pyi` sibling. The no-orphans check confirms every source symbol a test could reach is exercised and every test reference is backed by a source `.pyi`. Traceability confirms every interview finding maps to a test or an explicit deferral and every external service has a captured cassette its tests replay. Each is a real filter; none is the simulation. -**Judgment, not artifact.** The old ceremony — a per-walkthrough JSON pair written to a cache directory to prove the simulation was thorough — is gone, because the artifact was the symptom of the failure: the understanding never made it into the gate decision, it was offloaded into files no one acted on, and the e2e issues shipped to build unsolved. The output of a real simulation is the gate decision itself — *the contract set is coherent and complete; a passing implementation will work* — backed by the specific walkthroughs and traces that justify it, or a named gap that routes back to plan. Where a gap is found it is stated precisely (which hop, which value, which contradiction); where none is found the understanding lives in the decision to advance, not in a file. +**Judgment with evidence.** The output is the gate decision itself — *the contract set is coherent and complete; a passing implementation will work* — backed by the walkthroughs and traces that justify it, or a named gap that routes back to plan. Where a gap is found it is stated precisely (which hop, which value, which contradiction); where none is found, the understanding lives in the decision to advance. The simulation's value is that understanding, held at the gate. ## Content @@ -41,7 +41,7 @@ last-updated: 2026-07-01 | `docs/glossary.md` | the names the tests should use consistently | | `tests/cassettes/**` | the real external shapes the boundary tests must assert against | -There is no `domain_spec.md` to walk; the tests are the spec. A finding that cannot be grounded in one of these artefacts is not a simulation finding. +A finding that cannot be grounded in one of these artefacts is not a simulation finding. ### The composition failures tools miss @@ -95,7 +95,7 @@ The simulation produces one of two outcomes, and nothing else: - **coherent and complete** — the walkthrough reached no broken hop, the value traces found no disagreement, the tool floor is clean; advance to build. - **a named gap** — which hop broke, which value disagreed, which module has no driver; route back to plan with the specifics. -No JSON, no cache directory, no I/O pairs. The understanding is the output, and it lives in the gate decision. +The understanding is the output, and it lives in the gate decision. ## Related diff --git a/.opencode/knowledge/software-craft/source-stubs.md b/.opencode/knowledge/software-craft/source-stubs.md index 0a558f2e..ccf9fc5f 100644 --- a/.opencode/knowledge/software-craft/source-stubs.md +++ b/.opencode/knowledge/software-craft/source-stubs.md @@ -23,7 +23,7 @@ last-updated: 2026-07-01 **Fixed during build.** Once derived, the source `.pyi` is frozen for the whole build cycle: green writes the `.py` to satisfy it, refactor restructures the `.py` while the `.pyi` stays put, and the tests (already written) stay put too. If implementation discovers the `.pyi` is wrong — a missing parameter, a wrong return type, an impossible signature — the response is never to edit the stub in place; it is to escalate a contract gap at review, which routes back to plan for a proper re-derivation. The frozen stub is what keeps the contract the single source of truth. -**No layout, no config artifact.** The tests say where the source lives and what it is called; the stub does not prescribe a package structure on top. Adapters, connectors, and domain types live under the package alongside one another — there is no separate skeleton category to author. Configuration is twelve-factor: environment variables are the default, loaded locally from a gitignored `.env`, and a typed Settings model is optional — if it earns its place, it is a normal source stub, not a special artifact the flow requires. +**No layout, no config artifact.** The tests say where the source lives and what it is called; the stub does not prescribe a package structure on top. Adapters, connectors, and domain types live under the package alongside one another. Configuration is twelve-factor: environment variables are the default, loaded locally from a gitignored `.env`, and a typed Settings model is optional — if it earns its place, it is a normal source stub alongside the rest. **Structural artifacts keyed to the module.** Some modules carry an artifact beyond the `.py` pair. An ORM model owns an Alembic migration — the migration is the schema spec, born in green, committed in ship, never edited only appended. An external adapter replays the cassettes captured during explore (`VCR_RECORD_MODE=none`). The stub itself does not generate these; it declares the module's surface, and green emits whatever that surface implies. @@ -65,7 +65,7 @@ The asymmetry is deliberate: the `.pyi` and the tests are the contract, and cont ### No layout, no config artifact -The package takes whatever shape the tests import from; there is no separate skeleton or ports layer to author. Configuration is twelve-factor — environment variables are the source, a gitignored `.env` carries local secrets, `python-dotenv` loads it. A `Settings` model is not required by the flow; if it is worth the code, it is one normal source stub among the rest, reading `os.environ` in its `from_env()`. +The package takes whatever shape the tests import from. Configuration is twelve-factor — environment variables are the source, a gitignored `.env` carries local secrets, `python-dotenv` loads it. A `Settings` model is optional; if it is worth the code, it is one normal source stub among the rest, reading `os.environ` in its `from_env()`. ### Structural artifacts keyed to the module From 728f498308fff318c452d4312107c368ed7252a8 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 00:26:53 -0400 Subject: [PATCH 11/28] chore(tooling): de-beehive pyproject; ruff = bug-catcher only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rethink pyproject + tooling per the project's intent: ruff catches real issues early without enforcing the style/sorting/docstrings that churn on every refactor. Ruff: - Drop the 'conventions' task — the style backdoor that enforced import sorting (I), annotations (ANN), naming (N), pycodestyle (E/W), etc. The main select was never the culprit; this backdoor was. - select kept: A ASYNC B C9 DTZ ERA F G LOG PYI RUF S SIM (bug + security + simplify; all stable + website-searchable). - select dropped: FURB (refactor suggestions = rework-on-refactor), PT (half stylistic), T20 (fights legitimate CLI prints), preview=true (unstable rules aren't reliably searchable). - per-file-ignores: tests/** -> [S101, S404] (drop vestigial ANN, D); drop scripts/*.py (no such dir). Deps + tooling: - De-beehive: drop pytest-beehave + [tool.beehave] + the 'deprecated' marker. - Consolidate to one [project.optional-dependencies].dev; delete [dependency-groups].dev. Move flowr from runtime to dev; drop flowr[viz]. - Drop pdoc + ghp-import + the 3 doc tasks (blocked on package; re-add later). - requires-python >=3.13 (flowr>=1.2.1 requires it; 3.12 was the intent). - CI Python 3.14 -> 3.13 (match the floor). - release-check = lint && static-check && stubtest && test (was conventions && ... && doc-build). - Identity (name/version/description/readme/urls) kept unchanged per decision. Verified: uv sync --extra dev clean; ruff check . clean; 6 flows validate. --- .github/workflows/ci.yml | 6 +- AGENTS.md | 4 +- TODO.md | 16 +- pyproject.toml | 45 +----- uv.lock | 328 +++++++++++++++++++-------------------- 5 files changed, 178 insertions(+), 221 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b07bef2..5fdf5248 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,7 @@ jobs: steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - - run: uv python install 3.14 + - run: uv python install 3.13 - run: uv sync --extra dev - run: uv run ruff check . - run: uv run ruff format . --check @@ -28,7 +28,7 @@ jobs: steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - - run: uv python install 3.14 + - run: uv python install 3.13 - run: uv sync --extra dev - run: bash -c 'for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done' @@ -37,7 +37,7 @@ jobs: steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - - run: uv python install 3.14 + - run: uv python install 3.13 - run: uv sync --extra dev - name: Resolve package id: pkg diff --git a/AGENTS.md b/AGENTS.md index 7c8bffbd..a759baac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -120,8 +120,8 @@ conventions live in the `methodology/` knowledge domain. ## Project commands Tasks are defined in `pyproject.toml` under `[tool.taskipy.tasks]`. The `app/` -package was removed during the reset, so package-dependent commands (`task run`, -`task test`, `task doc-serve`, ...) will not work until the package is rebuilt. +package is the placeholder, so package-dependent commands (`task run`, +`task test`, `task stubtest`, ...) resolve only once the package is created. | Command | Purpose | |---------|---------| diff --git a/TODO.md b/TODO.md index 481ff04c..db4e8927 100644 --- a/TODO.md +++ b/TODO.md @@ -256,14 +256,14 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. ## pyproject + tooling -- [ ] `[project].readme = "README.md"` and `[project.urls]` reference files deleted in the clean-slate commit (README.md, `docs/api/`) — pyproject points at ghosts. Author a fresh README + drop stale URLs, or remove the fields. -- [ ] Reset `version` and `description` (still "9.4.0" / "Spec-driven ... BDD traceability" — pre-clean-slate). -- [ ] Two dev-dependency sections overlap and diverge: `[project.optional-dependencies].dev` vs `[dependency-groups].dev` (the latter carries `flowr[viz]` + `pytest-beehave[html]`). Consolidate to one; decide `uv run --extra dev` vs `uv sync --group dev`. -- [ ] `conventions` task selects `ANN` (flake8-annotations) which flags the un-annotated `conftest.py` hook and diverges from `ruff check .` (main select has no ANN). Reconcile — drop `ANN` from `conventions`, or drop the `conventions` task in favour of `ruff check .`. -- [ ] Wire `stubtest` / `static-check` / coverage (`--cov`) / `doc-serve` / `doc-build` / `run` tasks to the real package once named (all target the stale `app` placeholder, matching `[tool.setuptools] packages = ["app"]`). -- [ ] Drop `beehave` / `pytest-beehave` deps + `[tool.beehave]` (feature-file stubbing is gone); keep `flowr`, `pytest`. -- [ ] Decide `requires-python` (currently `>=3.14`). -- [ ] Decide task runner: `taskipy` vs plain `uv run`. +- [x] `[project].readme` and `[project.urls]` — kept as-is (identity not reset per decision); README authoring tracked under Docs. +- [x] `version` and `description` — kept as-is per identity decision. +- [x] Consolidated to one `[project.optional-dependencies].dev`; deleted `[dependency-groups].dev`. `flowr` moved from runtime to dev; `flowr[viz]` dropped. +- [x] Dropped the `conventions` task (the style backdoor selecting `I`/`ANN`/`N`/`E`/`W`/…); `release-check` now uses `ruff check .` via `lint`. +- [ ] Wire `stubtest` / `static-check` / coverage (`--cov`) / `run` tasks to the real package once created (all target the `app` placeholder; `doc-serve`/`doc-build`/`doc-publish` dropped until the package exists). +- [x] Dropped `beehave` / `pytest-beehave` deps + `[tool.beehave]`. +- [x] `requires-python` set to `>=3.13` (flowr>=1.2.1 requires >=3.13; 3.12 was the intent but deps constrain it). +- [x] Task runner: `taskipy`, invoked via `uv run task `. ## Package + tests skeleton - [ ] Decide package name (old default `app`) and create the minimal package. diff --git a/pyproject.toml b/pyproject.toml index b7f9d6bb..89cc3103 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "temple8" version = "9.4.0" description = "Spec-driven agent orchestration template with YAML flow definitions, multi-agent dispatch, and BDD traceability" readme = "README.md" -requires-python = ">=3.14" +requires-python = ">=3.13" license = { file = "LICENSE" } authors = [ { name = "eol", email = "nullhack@users.noreply.github.com" } @@ -11,9 +11,7 @@ authors = [ maintainers = [ { name = "eol", email = "nullhack@users.noreply.github.com" } ] -dependencies = [ - "flowr>=1.2.1", -] +dependencies = [] [project.urls] Homepage = "https://nullhack.github.io/temple8/" @@ -22,7 +20,7 @@ Documentation = "https://github.com/nullhack/temple8/tree/main/docs/api/" [project.optional-dependencies] dev = [ - "pdoc>=14.0", + "flowr>=1.2.1", "pytest>=9.0.3", "pytest-cov>=6.1.1", "pytest-html>=4.0.0", @@ -34,8 +32,6 @@ dev = [ "hypothesis>=6.148.4", "pyright>=1.1.407", "mypy>=1.13.0", - "ghp-import>=2.1.0", - "pytest-beehave>=1.0.0", "safety>=3.7.0", ] @@ -45,19 +41,9 @@ sessions_dir = ".cache/sessions" default_flow = "pipeline-flow" default_session = "default" -[tool.beehave] -features_dir = "docs/features" -tests_dir = "tests/features" - [tool.setuptools] packages = ["app"] -[dependency-groups] -dev = [ - "flowr[viz]>=1.2.0", - "pytest-beehave[html]>=1.0.0", -] - [tool.ruff.lint] ignore = [] select = [ @@ -68,28 +54,22 @@ select = [ "DTZ", "ERA", "F", - "FURB", "G", "LOG", - "PT", "PYI", "RUF", "S", "SIM", - "T20", ] -preview = true mccabe.max-complexity = 10 [tool.ruff.lint.per-file-ignores] -"tests/**" = ["S101", "S404", "ANN", "D"] -"scripts/*.py" = ["T20"] +"tests/**" = ["S101", "S404"] [tool.pytest.ini_options] minversion = "6.0" markers = [ "slow: marks tests as slow (deselect with '-m \"not slow\"')", - "deprecated: marks tests for deprecated AC; automatically skipped by pytest-beehave (deselect with '-m \"not deprecated\"')", "bug: marks tests that reproduce a reported defect (deselect with '-m \"not bug\"')", "pending: contract test defined in discovery but not yet implemented; auto-skipped (the backlog). Remove the marker to activate (red). Query with: -m pending", ] @@ -137,26 +117,11 @@ pytest \ test-fast = "pytest -m \"not slow\" -q --no-header --tb=no" test-slow = "pytest -m slow" ruff-check = "ruff check ." -conventions = "ruff check . --select A,ANN,ASYNC,B,C4,C9,DTZ,E,ERA,F,FURB,G,I,ICN,LOG,N,NPY,PD,PT,PTH,PYI,RUF,S,SIM,T20,TD,W" ruff-format = "ruff format ." ruff-format-check = "ruff format . --check" lint = "task ruff-check && task ruff-format-check" -doc-serve = "pdoc ./app --host localhost --port 8080" -doc-build = """\ -pdoc ./app -o docs/api --search && \ -pytest \ - --cov-config=pyproject.toml \ - --cov-report html:docs/coverage \ - --cov=app \ - --html=docs/tests/report.html \ - --self-contained-html \ - -q -q \ -""" -doc-publish = "task doc-build && ghp-import -n -p -f docs" static-check = "pyright app tests" stubtest = "python -m mypy.stubtest app tests" validate-flows = "bash -c 'for f in .flowr/flows/*.yaml; do python -m flowr validate \"$f\"; done'" -release-check = "task conventions && task static-check && task stubtest && task test && task doc-build" - - +release-check = "task lint && task static-check && task stubtest && task test" diff --git a/uv.lock b/uv.lock index 1ca6c4f1..5e9a7847 100644 --- a/uv.lock +++ b/uv.lock @@ -1,6 +1,6 @@ version = 1 revision = 3 -requires-python = ">=3.14" +requires-python = ">=3.13" resolution-markers = [ "python_full_version >= '3.15'", "python_full_version < '3.15'", @@ -89,18 +89,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/fb/95/adcb68e20c34162e9135f370d6e31737719c2b6f94bc953fe7ed1f10fe21/authlib-1.7.2-py2.py3-none-any.whl", hash = "sha256:3e1faedc9d87e7d56a164eca3ccb6ace0d61b94abe83e92242f8dc8bba9b4a9f", size = 259548, upload-time = "2026-05-06T08:10:21.436Z" }, ] -[[package]] -name = "beehave" -version = "1.0.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "gherkin-official" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/77/01/9b90dec3e14a429b3a54fc69715152b3ca9b34bc5dc9852763d97487f27b/beehave-1.0.0.tar.gz", hash = "sha256:59e959959a0fa7a0e487b6bef4a2af8b9abcad55381e02bbfe11d2433d5aec42", size = 110601, upload-time = "2026-05-20T19:22:02.357Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/67/55/1ce4d584ba4e50a8dfcfafb1d27c3e61d17af5cc304ba3705b80a7ceb021/beehave-1.0.0-py3-none-any.whl", hash = "sha256:8ecc505d5a53d48cdb44fa28f67ff5b39840debe8df3733bc71b6470b3325054", size = 25557, upload-time = "2026-05-20T19:22:01.018Z" }, -] - [[package]] name = "certifi" version = "2026.6.17" @@ -119,6 +107,18 @@ dependencies = [ ] sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" }, + { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" }, + { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" }, + { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" }, + { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" }, + { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" }, + { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" }, + { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" }, + { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" }, + { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" }, + { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" }, + { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" }, { url = "https://files.pythonhosted.org/packages/92/c4/3ce07396253a83250ee98564f8d7e9789fab8e58858f35d07a9a2c78de9f/cffi-2.0.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:fc33c5141b55ed366cfaad382df24fe7dcbc686de5be719b207bb248e3053dc5", size = 185320, upload-time = "2025-09-08T23:23:18.087Z" }, { url = "https://files.pythonhosted.org/packages/59/dd/27e9fa567a23931c838c6b02d0764611c62290062a6d4e8ff7863daf9730/cffi-2.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c654de545946e0db659b3400168c9ad31b5d29593291482c43e3564effbcee13", size = 181487, upload-time = "2025-09-08T23:23:19.622Z" }, { url = "https://files.pythonhosted.org/packages/d6/43/0e822876f87ea8a4ef95442c3d766a06a51fc5298823f884ef87aaad168c/cffi-2.0.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:24b6f81f1983e6df8db3adc38562c83f7d4a0c36162885ec7f7b77c7dcbec97b", size = 220049, upload-time = "2025-09-08T23:23:20.853Z" }, @@ -170,6 +170,21 @@ version = "7.14.3" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/b4/91/0a7c28934e50d8ac9a7b117712d176f2953c3170bccced5eaacfa3e96175/coverage-7.14.3.tar.gz", hash = "sha256:1a7563a443f3d53fdeb040ec8c9f7466aed7ca3dc5891aa09d3ca3625fa4387f", size = 924398, upload-time = "2026-06-22T23:10:25.584Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/a9/83/7fefbf5df23ed2b7f489907564a7b34b9b07098128e12e0fdfa92626e456/coverage-7.14.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:47968988b367990ae4ab17523790c38cd125e02c6bfd379b6022be2d40bdc38c", size = 220699, upload-time = "2026-06-22T23:08:53.522Z" }, + { url = "https://files.pythonhosted.org/packages/31/e6/38c3653ff6d56d704b29241362387ca824e38e15b76fdcb7096538195790/coverage-7.14.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:0ee68f5c34812780f3a7063382c0a9fcbb99985b7ddcdcaa626e4f3fb2e0783a", size = 221068, upload-time = "2026-06-22T23:08:55.571Z" }, + { url = "https://files.pythonhosted.org/packages/20/86/4f5c45d51c5cd10a128933f0fd235393c9146abbfd2ce2dfa68b3267ead3/coverage-7.14.3-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:fa9e5c6857a7e80fa22ace5cf3550ae392bbfc322f1d8dd2d2d5a8be38cec027", size = 252060, upload-time = "2026-06-22T23:08:57.464Z" }, + { url = "https://files.pythonhosted.org/packages/82/50/dfce42eff2cecabcd5a9bbad5489449c87db3415f408d23ffee417ce01f6/coverage-7.14.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:98a0859b0e98e43e1178a9402e19c8127766b14f7109a374d976e5a62c0e5c73", size = 254657, upload-time = "2026-06-22T23:08:59.453Z" }, + { url = "https://files.pythonhosted.org/packages/ba/d2/639ceb1bc8038fd0d66768278d5dc22df3391918b8278c2a21aa2602a531/coverage-7.14.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:69918344541ed9c8368566c2adc03c0e33d4550d7faa87d1b35e49b6a3286ea9", size = 255892, upload-time = "2026-06-22T23:09:01.291Z" }, + { url = "https://files.pythonhosted.org/packages/8b/96/002094a10e113512500dc1e10430a449417e17b0f90f7d496bcb820208b7/coverage-7.14.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b7f300ac92cd4b570724c8ffbbd0c130fee298d2447f41d5a3abf58976fae1de", size = 258026, upload-time = "2026-06-22T23:09:03.017Z" }, + { url = "https://files.pythonhosted.org/packages/0b/ec/286a5d2fad9c4bee59bd724feeb7d5bf8303c6c9200b51d1dd945a9c72b0/coverage-7.14.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:11a7ec9f97ab950f4c5af62229befc7faf208fdbc0116d3902d7e306cf2c5abd", size = 252285, upload-time = "2026-06-22T23:09:04.773Z" }, + { url = "https://files.pythonhosted.org/packages/d9/7d/a17753a0b12dd48d0d50f5fab079ad99d3be1eac790494d89f3a417ca0b9/coverage-7.14.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a571bd889cd36c5922ce8e42e059f9d37d02301531d11374afa4c87a578625d5", size = 254023, upload-time = "2026-06-22T23:09:06.513Z" }, + { url = "https://files.pythonhosted.org/packages/86/ef/a76c6ceba6a2c313f905310abf2701d534cada22d372db11731831e9e209/coverage-7.14.3-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:de76caefc8deabb0dd1678b6a980be97d14c8d87e213ac194dbf8b09e96d63fb", size = 251989, upload-time = "2026-06-22T23:09:08.382Z" }, + { url = "https://files.pythonhosted.org/packages/d9/39/353013a75fec0fb49f7553519f9d52b4441e902e5178c93f38eb6c07cedb/coverage-7.14.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:d20a15c622194234161535459affa8f7905830391c9ccfa060d495dbfe3a1c7f", size = 256144, upload-time = "2026-06-22T23:09:10.369Z" }, + { url = "https://files.pythonhosted.org/packages/29/0e/613878555d734def11c5b20a2701a15cb3781b9e9ea749da27c5f436e928/coverage-7.14.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:b488bd4b23397db62e7a9459129d01ff06a846582a732efd24834b24a6ada498", size = 251808, upload-time = "2026-06-22T23:09:12.057Z" }, + { url = "https://files.pythonhosted.org/packages/af/76/359c058c9cfdcf1e8b107663881225b03b364a320017eda24a2a66e55102/coverage-7.14.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6a3693b4153394d265f44fb855fdc80e72403024d4d6f91c4871b334d028e4e0", size = 253579, upload-time = "2026-06-22T23:09:13.858Z" }, + { url = "https://files.pythonhosted.org/packages/1d/d9/4ba2f060933a30ebe363cef9f67a365b0a317e580c0d5d9169d56a73ef1c/coverage-7.14.3-cp313-cp313-win32.whl", hash = "sha256:338b19131ab1a6b767b462bfcbaa692e7ae22f24463e39d49b02a83410ff6b37", size = 222741, upload-time = "2026-06-22T23:09:15.636Z" }, + { url = "https://files.pythonhosted.org/packages/76/e8/196ebc25d8f34c06d43a6e9c8513c9266ef8dbf3b5672beb1a00cf5e29fa/coverage-7.14.3-cp313-cp313-win_amd64.whl", hash = "sha256:b3d77f7f196abdef7e01415de1bce09f216189e83e58159cfeef2b92d0464994", size = 223283, upload-time = "2026-06-22T23:09:17.478Z" }, + { url = "https://files.pythonhosted.org/packages/7c/af/51d2aac6417523a286f10fb25f09eb9518a84df9f1151e93ff6871f34849/coverage-7.14.3-cp313-cp313-win_arm64.whl", hash = "sha256:e6230e688c7c3e65cedd41a774eb4ec221adc6bfee13768231015b702d5e4150", size = 222678, upload-time = "2026-06-22T23:09:19.7Z" }, { url = "https://files.pythonhosted.org/packages/61/56/14e3b97facbfa1304dd19e676e26599ad359f04714bed32f7f1c5a88efdc/coverage-7.14.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:605ab2b566a22bd94834529d66d295c364aba84afd3e5498285c7a524017b1fc", size = 220741, upload-time = "2026-06-22T23:09:21.616Z" }, { url = "https://files.pythonhosted.org/packages/12/1d/db378b5cca433b90b893f26dab728b280ddd89f272a1fdfed4aeaa05c686/coverage-7.14.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a3c2134809e80fac091bfed18a6991b5a5eb5df5ae32b17ac4f4f99864b73dd7", size = 221068, upload-time = "2026-06-22T23:09:23.452Z" }, { url = "https://files.pythonhosted.org/packages/47/f0/3f8421b20d9c4fcd39be9a8ca3c3fda8bc204b44efbd09fede153afd3e2f/coverage-7.14.3-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c02efd507227bde9969cab0db8f48890eb3b5dcad6afac57a4792df4133543ce", size = 252117, upload-time = "2026-06-22T23:09:25.458Z" }, @@ -265,22 +280,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/56/26/035d1c308882514a1e6ddca27f9d3e570d67a0e293e7b4d910a70c8fe32b/dparse-0.6.4-py3-none-any.whl", hash = "sha256:fbab4d50d54d0e739fbb4dedfc3d92771003a5b9aa8545ca7a7045e3b174af57", size = 11925, upload-time = "2024-11-08T16:52:03.844Z" }, ] -[[package]] -name = "fastapi" -version = "0.138.2" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "annotated-doc" }, - { name = "pydantic" }, - { name = "starlette" }, - { name = "typing-extensions" }, - { name = "typing-inspection" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/0c/a9/9f8f7e00195c29836e9bf58bbbaf579e29878b8a67851efff93d9b6d4eb7/fastapi-0.138.2.tar.gz", hash = "sha256:6432359d067a432134620e7c5e4c6e5063e7f37815bbbbf20acef14b0d2e3fc8", size = 420423, upload-time = "2026-06-29T12:44:12.556Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/f2/b3/38be2c074bdd0c986340db1d72d7b2321b805b1c5a68069aa00b5d31fd02/fastapi-0.138.2-py3-none-any.whl", hash = "sha256:db90c1ffb5517fba5d4a9f80e866daa008747e646310c9ce155c8c535f9d1615", size = 129271, upload-time = "2026-06-29T12:44:13.905Z" }, -] - [[package]] name = "filelock" version = "3.29.4" @@ -302,36 +301,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/81/8f/bf95a539faac78a07c0e9c811756fd5529b2b0a4f63faf0e88eb8a1f3b2a/flowr-1.2.1-py3-none-any.whl", hash = "sha256:e3871ae0ab94e30c87f1f31362792257bb14ce584f5fb662964767f62862ffb7", size = 214708, upload-time = "2026-05-22T18:23:54.71Z" }, ] -[package.optional-dependencies] -viz = [ - { name = "fastapi" }, - { name = "uvicorn" }, -] - -[[package]] -name = "gherkin-official" -version = "41.0.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "typing-extensions" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/4c/4f/525b5a98134a47e5009d910ed60e7e046d55be35796e34b6997ebf4d8241/gherkin_official-41.0.0.tar.gz", hash = "sha256:3e63a45c6daa43a25b159cdfd84c9703c2956c0736fe42119501a441c151b3db", size = 33992, upload-time = "2026-06-20T07:06:30.064Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/45/f5/2a8c9bc5a0e281f44d96316466e9181c2684e4f67154009a81948fab90d9/gherkin_official-41.0.0-py3-none-any.whl", hash = "sha256:e8c4ea8fee8350f22eacdf13ea5ac16e84273f95839b7c3fac600c3a4f1daca3", size = 38823, upload-time = "2026-06-20T07:06:28.812Z" }, -] - -[[package]] -name = "ghp-import" -version = "2.1.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "python-dateutil" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" }, -] - [[package]] name = "h11" version = "0.16.0" @@ -438,6 +407,19 @@ version = "0.11.0" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/40/08/9e7f6b5d2b5bed6ad055cdd5925f192bb403a51280f86b56554d9d0699a2/librt-0.11.0.tar.gz", hash = "sha256:075dc3ef4458a278e0195cbf6ac9d38808d9b906c5a6c7f7f79c3888276a3fb1", size = 200139, upload-time = "2026-05-10T18:17:25.138Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/82/61/e59168d4d0bf2bf90f4f0caf7a001bfc60254c3af4586013b04dc3ef517b/librt-0.11.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:78dc31f7fdfe9c9d0eb0e8f42d139db230e826415bbcabd9f0e9faaaee909894", size = 144119, upload-time = "2026-05-10T18:16:11.771Z" }, + { url = "https://files.pythonhosted.org/packages/61/fd/caa1d60b12f7dd79ccea23054e06eeaebe266a5f52c40a6b651069200ce5/librt-0.11.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:fa475675db22290c3158e1d42326d0f5a65f04f44a0e68c3630a25b53560fb9c", size = 143565, upload-time = "2026-05-10T18:16:13.334Z" }, + { url = "https://files.pythonhosted.org/packages/b8/a9/dc744f5c2b4978d48db970be29f22716d3413d28b14ad99740817315cf2c/librt-0.11.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:621db29691044bdeda22e789e482e1b0f3a985d90e3426c9c6d17606416205ea", size = 485395, upload-time = "2026-05-10T18:16:14.729Z" }, + { url = "https://files.pythonhosted.org/packages/8f/21/7f8e97a1e4dae952a5a95948f6f8507a173bc1e669f54340bba6ca1ca31b/librt-0.11.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:a9010e2ed5b3a9e158c5fd966b3ab7e834bb3d3aacc8f66c91dd4b57a3799230", size = 479383, upload-time = "2026-05-10T18:16:16.321Z" }, + { url = "https://files.pythonhosted.org/packages/a6/6d/d8ee9c114bebf2c50e29ec2aa940826fccb62a645c3e4c18760987d0e16d/librt-0.11.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7c39513d8b7477a2e1ed8c43fc21c524e8d5a0f8d4e8b7b074dbdbe7820a08e2", size = 513010, upload-time = "2026-05-10T18:16:17.647Z" }, + { url = "https://files.pythonhosted.org/packages/f0/43/0b5708af2bd30a46400e72ba6bdaa8f066f15fb9a688527e34220e8d6c06/librt-0.11.0-cp313-cp313-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7aef3cf1d5af86e770ab04bfd993dfc4ae8b8c17f66fb77dd4a7d50de7bbb1a3", size = 508433, upload-time = "2026-05-10T18:16:19.309Z" }, + { url = "https://files.pythonhosted.org/packages/4a/50/356187247d09013490481033183b3532b58acf8028bcb34b2b56a375c9b2/librt-0.11.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:557183ddc36babe46b27dd60facbd5adb4492181a5be887587d57cda6e092f21", size = 522595, upload-time = "2026-05-10T18:16:20.642Z" }, + { url = "https://files.pythonhosted.org/packages/40/e7/c6ac4240899c7f3248079d5a9900debe0dadb3fdeaf856684c987105ba47/librt-0.11.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:83d3e1f72bd42f6c5c0b7daec530c3f829bd02db42c70b8ddf0c2d90a2459930", size = 527255, upload-time = "2026-05-10T18:16:22.352Z" }, + { url = "https://files.pythonhosted.org/packages/eb/b5/a81322dbeedeeaf9c1ee6f001734d28a09d8383ac9e6779bc24bbd0743c6/librt-0.11.0-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:4ce1f21fbe589bc1afd7872dece84fb0e1144f794a288e58a10d2c54a55c43be", size = 516847, upload-time = "2026-05-10T18:16:23.627Z" }, + { url = "https://files.pythonhosted.org/packages/ae/66/6e6323787d592b55204a42595ff1102da5115601b53a7e9ddebc889a6da5/librt-0.11.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:970b09f7044ea2b64c9da42fd3d335666518cfd1c6e8a182c95da73d0214b41e", size = 553920, upload-time = "2026-05-10T18:16:25.025Z" }, + { url = "https://files.pythonhosted.org/packages/9c/21/623f8ca230857102066d9ca8c6c1734995908c4d0d1bee7bb2ef0021cb33/librt-0.11.0-cp313-cp313-win32.whl", hash = "sha256:78fddc31cd4d3caa897ad5d31f856b1faadc9474021ad6cb182b9018793e254e", size = 101898, upload-time = "2026-05-10T18:16:26.649Z" }, + { url = "https://files.pythonhosted.org/packages/b3/1d/b4ebd44dd723f768469007515cb92251e0ae286c94c140f374801140fa74/librt-0.11.0-cp313-cp313-win_amd64.whl", hash = "sha256:8ca8aa88751a775870b764e93bad5135385f563cb8dcee399abf034ea4d3cb47", size = 119812, upload-time = "2026-05-10T18:16:27.859Z" }, + { url = "https://files.pythonhosted.org/packages/3b/e4/b2f4ca7965ca373b491cdb4bc25cdb30c1649ca81a8782056a83850292a9/librt-0.11.0-cp313-cp313-win_arm64.whl", hash = "sha256:96f044bb325fd9cf1a723015638c219e9143f0dfbc0ca54c565df2b7fc748b44", size = 103448, upload-time = "2026-05-10T18:16:29.066Z" }, { url = "https://files.pythonhosted.org/packages/29/eb/dbce197da4e227779e56b5735f2decc3eb36e55a1cdbf1bd65d6639d76c1/librt-0.11.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:4a017a95e5837dc15a8c5661d60e05daa96b90908b1aa6b7acdf443cd25c8ebd", size = 143345, upload-time = "2026-05-10T18:16:30.674Z" }, { url = "https://files.pythonhosted.org/packages/76/a3/254bebd0c11c8ba684018efb8006ff22e466abce445215cca6c778e7d9de/librt-0.11.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:b1ecbd9819deccc39b7542bf4d2a740d8a620694d39989e58661d3763458f8d4", size = 143131, upload-time = "2026-05-10T18:16:32.037Z" }, { url = "https://files.pythonhosted.org/packages/f1/3f/f77d6122d21ac7bf6ae8a7dfced1bd2a7ac545d3273ebdcaf8042f6d619f/librt-0.11.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7da327dacd7be8f8ec36547373550744a3cc0e536d54665cd83f8bcd961200e8", size = 477024, upload-time = "2026-05-10T18:16:33.493Z" }, @@ -478,21 +460,34 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" }, ] -[[package]] -name = "markdown2" -version = "2.5.5" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/e4/ae/07d4a5fcaa5509221287d289323d75ac8eda5a5a4ac9de2accf7bbcc2b88/markdown2-2.5.5.tar.gz", hash = "sha256:001547e68f6e7fcf0f1cb83f7e82f48aa7d48b2c6a321f0cd20a853a8a2d1664", size = 157249, upload-time = "2026-03-02T20:46:53.411Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/43/af/4b3891eb0a49d6cfd5cbf3e9bf514c943afc2b0f13e2c57cc57cd88ecc21/markdown2-2.5.5-py3-none-any.whl", hash = "sha256:be798587e09d1f52d2e4d96a649c4b82a778c75f9929aad52a2c95747fa26941", size = 56250, upload-time = "2026-03-02T20:46:52.032Z" }, -] - [[package]] name = "markupsafe" version = "3.0.3" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/38/2f/907b9c7bbba283e68f20259574b13d005c121a0fa4c175f9bed27c4597ff/markupsafe-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", size = 11622, upload-time = "2025-09-27T18:36:41.777Z" }, + { url = "https://files.pythonhosted.org/packages/9c/d9/5f7756922cdd676869eca1c4e3c0cd0df60ed30199ffd775e319089cb3ed/markupsafe-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", size = 12029, upload-time = "2025-09-27T18:36:43.257Z" }, + { url = "https://files.pythonhosted.org/packages/00/07/575a68c754943058c78f30db02ee03a64b3c638586fba6a6dd56830b30a3/markupsafe-3.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", size = 24374, upload-time = "2025-09-27T18:36:44.508Z" }, + { url = "https://files.pythonhosted.org/packages/a9/21/9b05698b46f218fc0e118e1f8168395c65c8a2c750ae2bab54fc4bd4e0e8/markupsafe-3.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", size = 22980, upload-time = "2025-09-27T18:36:45.385Z" }, + { url = "https://files.pythonhosted.org/packages/7f/71/544260864f893f18b6827315b988c146b559391e6e7e8f7252839b1b846a/markupsafe-3.0.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", size = 21990, upload-time = "2025-09-27T18:36:46.916Z" }, + { url = "https://files.pythonhosted.org/packages/c2/28/b50fc2f74d1ad761af2f5dcce7492648b983d00a65b8c0e0cb457c82ebbe/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", size = 23784, upload-time = "2025-09-27T18:36:47.884Z" }, + { url = "https://files.pythonhosted.org/packages/ed/76/104b2aa106a208da8b17a2fb72e033a5a9d7073c68f7e508b94916ed47a9/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", size = 21588, upload-time = "2025-09-27T18:36:48.82Z" }, + { url = "https://files.pythonhosted.org/packages/b5/99/16a5eb2d140087ebd97180d95249b00a03aa87e29cc224056274f2e45fd6/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", size = 23041, upload-time = "2025-09-27T18:36:49.797Z" }, + { url = "https://files.pythonhosted.org/packages/19/bc/e7140ed90c5d61d77cea142eed9f9c303f4c4806f60a1044c13e3f1471d0/markupsafe-3.0.3-cp313-cp313-win32.whl", hash = "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", size = 14543, upload-time = "2025-09-27T18:36:51.584Z" }, + { url = "https://files.pythonhosted.org/packages/05/73/c4abe620b841b6b791f2edc248f556900667a5a1cf023a6646967ae98335/markupsafe-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", size = 15113, upload-time = "2025-09-27T18:36:52.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/3a/fa34a0f7cfef23cf9500d68cb7c32dd64ffd58a12b09225fb03dd37d5b80/markupsafe-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", size = 13911, upload-time = "2025-09-27T18:36:53.513Z" }, + { url = "https://files.pythonhosted.org/packages/e4/d7/e05cd7efe43a88a17a37b3ae96e79a19e846f3f456fe79c57ca61356ef01/markupsafe-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", size = 11658, upload-time = "2025-09-27T18:36:54.819Z" }, + { url = "https://files.pythonhosted.org/packages/99/9e/e412117548182ce2148bdeacdda3bb494260c0b0184360fe0d56389b523b/markupsafe-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", size = 12066, upload-time = "2025-09-27T18:36:55.714Z" }, + { url = "https://files.pythonhosted.org/packages/bc/e6/fa0ffcda717ef64a5108eaa7b4f5ed28d56122c9a6d70ab8b72f9f715c80/markupsafe-3.0.3-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", size = 25639, upload-time = "2025-09-27T18:36:56.908Z" }, + { url = "https://files.pythonhosted.org/packages/96/ec/2102e881fe9d25fc16cb4b25d5f5cde50970967ffa5dddafdb771237062d/markupsafe-3.0.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", size = 23569, upload-time = "2025-09-27T18:36:57.913Z" }, + { url = "https://files.pythonhosted.org/packages/4b/30/6f2fce1f1f205fc9323255b216ca8a235b15860c34b6798f810f05828e32/markupsafe-3.0.3-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", size = 23284, upload-time = "2025-09-27T18:36:58.833Z" }, + { url = "https://files.pythonhosted.org/packages/58/47/4a0ccea4ab9f5dcb6f79c0236d954acb382202721e704223a8aafa38b5c8/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", size = 24801, upload-time = "2025-09-27T18:36:59.739Z" }, + { url = "https://files.pythonhosted.org/packages/6a/70/3780e9b72180b6fecb83a4814d84c3bf4b4ae4bf0b19c27196104149734c/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", size = 22769, upload-time = "2025-09-27T18:37:00.719Z" }, + { url = "https://files.pythonhosted.org/packages/98/c5/c03c7f4125180fc215220c035beac6b9cb684bc7a067c84fc69414d315f5/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", size = 23642, upload-time = "2025-09-27T18:37:01.673Z" }, + { url = "https://files.pythonhosted.org/packages/80/d6/2d1b89f6ca4bff1036499b1e29a1d02d282259f3681540e16563f27ebc23/markupsafe-3.0.3-cp313-cp313t-win32.whl", hash = "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", size = 14612, upload-time = "2025-09-27T18:37:02.639Z" }, + { url = "https://files.pythonhosted.org/packages/2b/98/e48a4bfba0a0ffcf9925fe2d69240bfaa19c6f7507b8cd09c70684a53c1e/markupsafe-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", size = 15200, upload-time = "2025-09-27T18:37:03.582Z" }, + { url = "https://files.pythonhosted.org/packages/0e/72/e3cc540f351f316e9ed0f092757459afbc595824ca724cbc5a5d4263713f/markupsafe-3.0.3-cp313-cp313t-win_arm64.whl", hash = "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", size = 13973, upload-time = "2025-09-27T18:37:04.929Z" }, { url = "https://files.pythonhosted.org/packages/33/8a/8e42d4838cd89b7dde187011e97fe6c3af66d8c044997d2183fbd6d31352/markupsafe-3.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", size = 11619, upload-time = "2025-09-27T18:37:06.342Z" }, { url = "https://files.pythonhosted.org/packages/b5/64/7660f8a4a8e53c924d0fa05dc3a55c9cee10bbd82b11c5afb27d44b096ce/markupsafe-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", size = 12029, upload-time = "2025-09-27T18:37:07.213Z" }, { url = "https://files.pythonhosted.org/packages/da/ef/e648bfd021127bef5fa12e1720ffed0c6cbb8310c8d9bea7266337ff06de/markupsafe-3.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", size = 24408, upload-time = "2025-09-27T18:37:09.572Z" }, @@ -557,6 +552,13 @@ dependencies = [ ] sdist = { url = "https://files.pythonhosted.org/packages/82/15/cca9d88503549ed6fedeaa1d448cdddd542ee8a490232d732e278036fbf2/mypy-2.1.0.tar.gz", hash = "sha256:81e76ad12c2d804512e9b13240d1588316531bfba07558286078bfbce9613633", size = 3898359, upload-time = "2026-05-11T18:37:36.237Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/6e/dd/c7191469c777f07689c032a8f7326e393ea34c92d6d76eb7ce5ba57ea66d/mypy-2.1.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:35aac3bb114e03888f535d5eb51b8bafbb3266586b599da1940f9b1be3ec5bd5", size = 14852174, upload-time = "2026-05-11T18:31:38.929Z" }, + { url = "https://files.pythonhosted.org/packages/55/8c/aed55408879043d72bb9135f4d0d19a02b886dd569631e113e3d2706cb8d/mypy-2.1.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8de55a8c861f2a49331f807be98d90caeceeef520bde13d43a160207f8af613e", size = 13651542, upload-time = "2026-05-11T18:36:04.636Z" }, + { url = "https://files.pythonhosted.org/packages/3a/8e/f371a824b1f1fa8ea6e3dbb8703d232977d572be2329554a3bc4d960302f/mypy-2.1.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5fdf2941a07434af755837d9880f7d7d25f1dacb1af9dcd4b9b66f2220a3024e", size = 14033929, upload-time = "2026-05-11T18:35:55.742Z" }, + { url = "https://files.pythonhosted.org/packages/94/21/f54be870d6dd53a82c674407e0f8eed7174b05ec78d42e5abd7b42e84fd5/mypy-2.1.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e195b817c13f02352a9c124301f9f30f078405444679b6753c1b96b6eed37285", size = 15039200, upload-time = "2026-05-11T18:33:10.281Z" }, + { url = "https://files.pythonhosted.org/packages/17/99/bf21748626a40ce59fd29a39386ab46afec88b7bd2f0fa6c3a97c995523f/mypy-2.1.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5431d42af987ebd92ba2f71d45c85ed41d8e6ca9f5fd209a69f68f707d2469e5", size = 15272690, upload-time = "2026-05-11T18:32:07.205Z" }, + { url = "https://files.pythonhosted.org/packages/d6/d7/9e90d2cf47100bea550ed2bc7b0d4de3a62181d84d5e37da0003e8462637/mypy-2.1.0-cp313-cp313-win_amd64.whl", hash = "sha256:767fe8c66dc3e01e19e1737d4c38ebefead16125e1b8e58ad421903b376f5c65", size = 11147435, upload-time = "2026-05-11T18:33:56.477Z" }, + { url = "https://files.pythonhosted.org/packages/ec/46/e5c449e858798e35ffc90946282a27c62a77be743fe17480e4977374eb91/mypy-2.1.0-cp313-cp313-win_arm64.whl", hash = "sha256:ecfe70d43775ab99562ab128ce49854a362044c9f894961f68f898c23cb7429d", size = 10035052, upload-time = "2026-05-11T18:32:30.049Z" }, { url = "https://files.pythonhosted.org/packages/b0/ca/b279a672e874aedd5498ae25f722dacc8aa86bbffb939b3f97cbb1cf6686/mypy-2.1.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:7354c5a7f69d9345c3d6e69921d57088eea3ddeeb6b20d34c1b3855b02c36ec2", size = 14848422, upload-time = "2026-05-11T18:35:45.984Z" }, { url = "https://files.pythonhosted.org/packages/27/e6/3efe56c631d959b9b4454e208b0ac4b7f4f58b404c89f8bec7b49efdfc21/mypy-2.1.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:49890d4f76ac9e06ec117f9e09f3174da70a620a0c300953d8595c926e80947f", size = 13677374, upload-time = "2026-05-11T18:36:57.188Z" }, { url = "https://files.pythonhosted.org/packages/84/7f/8107ea87a44fd1f1b59882442f033c9c3488c127201b1d1d15f1cbd6022e/mypy-2.1.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:761be68e023ef5d94678772396a8af1220030f80837a3afd8d0aef3b419666f4", size = 14055743, upload-time = "2026-05-11T18:35:18.361Z" }, @@ -625,21 +627,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" }, ] -[[package]] -name = "pdoc" -version = "16.0.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "jinja2" }, - { name = "markdown2" }, - { name = "markupsafe" }, - { name = "pygments" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/ac/fe/ab3f34a5fb08c6b698439a2c2643caf8fef0d61a86dd3fdcd5501c670ab8/pdoc-16.0.0.tar.gz", hash = "sha256:fdadc40cc717ec53919e3cd720390d4e3bcd40405cb51c4918c119447f913514", size = 111890, upload-time = "2025-10-27T16:02:16.345Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/16/a1/56a17b7f9e18c2bb8df73f3833345d97083b344708b97bab148fdd7e0b82/pdoc-16.0.0-py3-none-any.whl", hash = "sha256:070b51de2743b9b1a4e0ab193a06c9e6c12cf4151cf9137656eebb16e8556628", size = 100014, upload-time = "2025-10-27T16:02:15.007Z" }, -] - [[package]] name = "pluggy" version = "1.6.0" @@ -697,6 +684,21 @@ dependencies = [ ] sdist = { url = "https://files.pythonhosted.org/packages/9d/56/921726b776ace8d8f5db44c4ef961006580d91dc52b803c489fafd1aa249/pydantic_core-2.46.4.tar.gz", hash = "sha256:62f875393d7f270851f20523dd2e29f082bcc82292d66db2b64ea71f64b6e1c1", size = 471464, upload-time = "2026-05-06T13:37:06.98Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/51/a2/5d30b469c5267a17b39dec53208222f76a8d351dfac4af661888c5aee77d/pydantic_core-2.46.4-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:5d5902252db0d3cedf8d4a1bc68f70eeb430f7e4c7104c8c476753519b423008", size = 2106306, upload-time = "2026-05-06T13:37:48.029Z" }, + { url = "https://files.pythonhosted.org/packages/c1/81/4fa520eaffa8bd7d1525e644cd6d39e7d60b1592bc5b516693c7340b50f1/pydantic_core-2.46.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c94f0688e7b8d0a67abf40e57a7eaaecd17cc9586706a31b76c031f63df052b4", size = 1951906, upload-time = "2026-05-06T13:37:17.012Z" }, + { url = "https://files.pythonhosted.org/packages/03/d5/fd02da45b659668b05923b17ba3a0100a0a3d5541e3bd8fcc4ecb711309e/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f027324c56cd5406ca49c124b0db10e56c69064fec039acc571c29020cc87c76", size = 1976802, upload-time = "2026-05-06T13:37:35.113Z" }, + { url = "https://files.pythonhosted.org/packages/21/f2/95727e1368be3d3ed485eaab7adbd7dda408f33f7a36e8b48e0144002b91/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e739fee756ba1010f8bcccb534252e85a35fe45ae92c295a06059ce58b74ccd3", size = 2052446, upload-time = "2026-05-06T13:37:12.313Z" }, + { url = "https://files.pythonhosted.org/packages/9c/86/5d99feea3f77c7234b8718075b23db11532773c1a0dbd9b9490215dc2eeb/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9d56801be94b86a9da183e5f3766e6310752b99ff647e38b09a9500d88e46e76", size = 2232757, upload-time = "2026-05-06T13:39:01.149Z" }, + { url = "https://files.pythonhosted.org/packages/d2/3a/508ac615935ef7588cf6d9e9b91309fdc2da751af865e02a9098de88258c/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2412e734dcb48da14d4e4006b82b46b74f2518b8a26ee7e58c6844a6cd6d03c4", size = 2309275, upload-time = "2026-05-06T13:37:41.406Z" }, + { url = "https://files.pythonhosted.org/packages/07/f8/41db9de19d7987d6b04715a02b3b40aea467000275d9d758ffaa31af7d50/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9551187363ffc0de2a00b2e47c25aeaeb1020b69b668762966df15fc5659dd5a", size = 2094467, upload-time = "2026-05-06T13:39:18.847Z" }, + { url = "https://files.pythonhosted.org/packages/2c/e2/f35033184cb11d0052daf4416e8e10a502ea2ac006fc4f459aee872727d1/pydantic_core-2.46.4-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:0186750b482eefa11d7f435892b09c5c606193ef3375bcf94aa00ae6bfb66262", size = 2134417, upload-time = "2026-05-06T13:40:17.944Z" }, + { url = "https://files.pythonhosted.org/packages/7e/7b/6ceeb1cc90e193862f444ebe373d8fdf613f0a82572dde03fb10734c6c71/pydantic_core-2.46.4-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5855698a4856556d86e8e6cd8434bc3ac0314ee8e12089ae0e143f64c6256e4e", size = 2179782, upload-time = "2026-05-06T13:40:32.618Z" }, + { url = "https://files.pythonhosted.org/packages/5a/f2/c8d7773ede6af08036423a00ae0ceffce266c3c52a096c435d68c896083f/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:cbaf13819775b7f769bf4a1f066cb6df7a28d4480081a589828ef190226881cd", size = 2188782, upload-time = "2026-05-06T13:36:51.018Z" }, + { url = "https://files.pythonhosted.org/packages/59/31/0c864784e31f09f05cdd87606f08923b9c9e7f6e51dd27f20f62f975ce9f/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:633147d34cf4550417f12e2b1a0383973bdf5cdfde212cb09e9a581cf10820be", size = 2328334, upload-time = "2026-05-06T13:40:37.764Z" }, + { url = "https://files.pythonhosted.org/packages/c2/eb/4f6c8a41efa30baa755590f4141abf3a8c370fab610915733e74134a7270/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:82cf5301172168103724d49a1444d3378cb20cdee30b116a1bd6031236298a5d", size = 2372986, upload-time = "2026-05-06T13:39:34.152Z" }, + { url = "https://files.pythonhosted.org/packages/5b/24/b375a480d53113860c299764bfe9f349a3dc9108b3adc0d7f0d786492ebf/pydantic_core-2.46.4-cp313-cp313-win32.whl", hash = "sha256:9fa8ae11da9e2b3126c6426f147e0fba88d96d65921799bb30c6abd1cb2c97fb", size = 1973693, upload-time = "2026-05-06T13:37:55.072Z" }, + { url = "https://files.pythonhosted.org/packages/7e/e8/cff247591966f2d22ec8c003cd7587e27b7ba7b81ab2fb888e3ab75dc285/pydantic_core-2.46.4-cp313-cp313-win_amd64.whl", hash = "sha256:6b3ace8194b0e5204818c92802dcdca7fc6d88aabbb799d7c795540d9cd6d292", size = 2071819, upload-time = "2026-05-06T13:38:49.139Z" }, + { url = "https://files.pythonhosted.org/packages/c6/1a/f4aee670d5670e9e148e0c82c7db98d780be566c6e6a97ee8035528ca0b3/pydantic_core-2.46.4-cp313-cp313-win_arm64.whl", hash = "sha256:184c081504d17f1c1066e430e117142b2c77d9448a97f7b65c6ac9fd9aee238d", size = 2027411, upload-time = "2026-05-06T13:40:45.796Z" }, { url = "https://files.pythonhosted.org/packages/8d/74/228a26ddad29c6672b805d9fd78e8d251cd04004fa7eed0e622096cd0250/pydantic_core-2.46.4-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:428e04521a40150c85216fc8b85e8d39fece235a9cf5e383761238c7fa9b96fb", size = 2102079, upload-time = "2026-05-06T13:38:41.019Z" }, { url = "https://files.pythonhosted.org/packages/ad/1f/8970b150a4b4365623ae00fc88603491f763c627311ae8031e3111356d6e/pydantic_core-2.46.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:23ace664830ee0bfe014a0c7bc248b1f7f25ed7ad103852c317624a1083af462", size = 1952179, upload-time = "2026-05-06T13:36:59.812Z" }, { url = "https://files.pythonhosted.org/packages/95/30/5211a831ae054928054b2f79731661087a2bc5c01e825c672b3a4a8f1b3e/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce5c1d2a8b27468f433ca974829c44060b8097eedc39933e3c206a90ee49c4a9", size = 1978926, upload-time = "2026-05-06T13:37:39.933Z" }, @@ -767,23 +769,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" }, ] -[[package]] -name = "pytest-beehave" -version = "1.0.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "beehave" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/85/29/5137c2909394ae2933e5be6aa034a7584c9e7e66b7731e46042408f7e6e4/pytest_beehave-1.0.0.tar.gz", hash = "sha256:e2d745027a58619a06568b3bdb2f88986be6bb4a863e2c5c6fe1a2824cdf2c71", size = 13324, upload-time = "2026-05-20T20:15:11.988Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/8d/60/6c0e9ca196f6634a0cc1654b6ea0f46e41269ad3b5868ceae241ed901e20/pytest_beehave-1.0.0-py3-none-any.whl", hash = "sha256:2cbcfdf44fc6f328590e324901388731596f0d4c2ab402a593a79363e6b1bd8d", size = 10183, upload-time = "2026-05-20T20:15:10.272Z" }, -] - -[package.optional-dependencies] -html = [ - { name = "pytest-html" }, -] - [[package]] name = "pytest-cov" version = "7.1.0" @@ -849,24 +834,22 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/9d/d3/ff520d11e6ee400602711d1ece8168dcfc5b6d8146fb7db4244a6ad6a9c3/pytest_vcr-1.0.2-py2.py3-none-any.whl", hash = "sha256:2f316e0539399bea0296e8b8401145c62b6f85e9066af7e57b6151481b0d6d9c", size = 4137, upload-time = "2019-04-26T19:03:57.034Z" }, ] -[[package]] -name = "python-dateutil" -version = "2.9.0.post0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "six" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, -] - [[package]] name = "pyyaml" version = "6.0.3" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" }, + { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" }, + { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" }, + { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" }, + { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" }, + { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" }, + { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" }, + { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" }, { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" }, { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" }, @@ -893,6 +876,38 @@ version = "2026.6.28" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/f1/05/e4f219230e11e774a6c9987d2ab0d0c6b8573e13a17e143d0015bee710ef/regex-2026.6.28.tar.gz", hash = "sha256:3cb4b6c5cb3060cc31efdc1fbb27c25fb9b29044afd87e40601a1c4d9db54342", size = 416101, upload-time = "2026-06-28T19:56:55.302Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/b6/53/d5c1b3cc0b5a0c985563ad6fac93d73ff2b300cb84342d89f044625d6bc7/regex-2026.6.28-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:b295a83426e0e44e9e60fde99789e181bd26788a1890ae7fe2a24c69bb6246ca", size = 490329, upload-time = "2026-06-28T19:54:35.775Z" }, + { url = "https://files.pythonhosted.org/packages/8d/9f/0c3503e819e91ca0e7a901a8e989ebf840ac7c7aea20b1fc7f31b6759f77/regex-2026.6.28-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0c31665c0deb5c111557a1cac8c27bd5629e2f9e7fd5058900a03576c33b601c", size = 292039, upload-time = "2026-06-28T19:54:37.977Z" }, + { url = "https://files.pythonhosted.org/packages/bb/7f/cd004e13fcad23b3794a82307dfd222e6365eb7f598bd3caab148a830bff/regex-2026.6.28-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:6bf295f2c59de77d1ea7de053607ae4dc9ceb3d57bbb6c7ec51ef4acc4ccff94", size = 289488, upload-time = "2026-06-28T19:54:39.545Z" }, + { url = "https://files.pythonhosted.org/packages/73/4c/293fb34586fbcdc47eac436069e9c11f71fae5dadfd4889b475d7d2e5f7a/regex-2026.6.28-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:17c077586770f67e05bbffeba07fbee6b2b22244f4d4caf8d94e59d574befe04", size = 796772, upload-time = "2026-06-28T19:54:41.347Z" }, + { url = "https://files.pythonhosted.org/packages/92/fa/c0cd1a90b7d12d9dc155cfc8bdea8df9720988ea5b07e8fa1eccbd0ab2dd/regex-2026.6.28-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0e6cb5a61486f9062397d2e189573b39d38ecfaed698fd9fb6e2756a8ebb8762", size = 865467, upload-time = "2026-06-28T19:54:43.485Z" }, + { url = "https://files.pythonhosted.org/packages/4e/db/0b479973046d005a1eaea299d5d536aeecb9488a16d9cbb8286338102e2d/regex-2026.6.28-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e86e91a2664f44c3a4e363a7d78fb17c27d5046882e30ea5a877f5e89b28d2ba", size = 912345, upload-time = "2026-06-28T19:54:46.091Z" }, + { url = "https://files.pythonhosted.org/packages/5b/5b/d65adfbd02f32212431bca1f06d1e2eb763a20b12978b454bafaf23dacb7/regex-2026.6.28-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4dfd1331c49233998d84fc5f1f4436cf7a435a7655f6cf0f490229bb5c7254e5", size = 801291, upload-time = "2026-06-28T19:54:48.3Z" }, + { url = "https://files.pythonhosted.org/packages/fc/09/2103686defaf9a0a31c1663782359d5b45f42524c64cca681f5481e44a5e/regex-2026.6.28-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cadea12805a1bce0b091c302b814207be26fb60a9c0e7f9ad2f9e21790a429fe", size = 777106, upload-time = "2026-06-28T19:54:50.326Z" }, + { url = "https://files.pythonhosted.org/packages/85/5a/b57593c0aa23ed269ec332fbcf07852abcb6b746e811d9464e0d09b4e25f/regex-2026.6.28-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5f2c1682b67ad5d2376498f2a5a2a8f782fa2e4a06d0465b5e357799806e8a20", size = 785175, upload-time = "2026-06-28T19:54:52.172Z" }, + { url = "https://files.pythonhosted.org/packages/79/59/c36e756ad29bf14d7b6c6d7138952476b21f6160286cedb98ac13481c993/regex-2026.6.28-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:64e142eb55e84868087da1375d7c36ff97d55010951849f515322a91d5fef1b4", size = 860186, upload-time = "2026-06-28T19:54:54.11Z" }, + { url = "https://files.pythonhosted.org/packages/61/66/49808aea0da9649c300139360708fb91b7144be1f962fcebf96755fde948/regex-2026.6.28-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:abb4daabe7be63273787a62dfd6164dadf8f7a63fbec3d2730e5e5e7126d858c", size = 765754, upload-time = "2026-06-28T19:54:56.04Z" }, + { url = "https://files.pythonhosted.org/packages/be/c5/52bbd436cf2200decdf48825fa38363eaaeebb77011ea9928a1ef9e0b9f2/regex-2026.6.28-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:ec2b2ad00ab8c16a2798cc8db80c53c4d5b8b3a2441f6cbaef06625f5ca25854", size = 852085, upload-time = "2026-06-28T19:54:57.988Z" }, + { url = "https://files.pythonhosted.org/packages/f9/c3/0390b66e3019497143fe768b3ba567b64d8b24f3812d09506deb86f4a0f0/regex-2026.6.28-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:bfc9677982c914d9085b8e1c3b3ae6e88f139fb56531c2416d6c8f338093c22b", size = 789600, upload-time = "2026-06-28T19:54:59.977Z" }, + { url = "https://files.pythonhosted.org/packages/88/fd/ab5b03653a244975069fed93d73f4f5f7484c03a84cedb238292510d7182/regex-2026.6.28-cp313-cp313-win32.whl", hash = "sha256:bf54bc693fc4e0530e666ba5ec4bcba14dbe8f66b7cfc15c27317d1a6e40b9a5", size = 267088, upload-time = "2026-06-28T19:55:02.159Z" }, + { url = "https://files.pythonhosted.org/packages/68/55/21022f7d3143210ae8d4ff905c45306237b657375cc0b97883f49db3d423/regex-2026.6.28-cp313-cp313-win_amd64.whl", hash = "sha256:e128feaf65bf3d9eb91bec92322a8f7e4835e9c798f3e9ea4b69f4def85620e3", size = 277680, upload-time = "2026-06-28T19:55:04.185Z" }, + { url = "https://files.pythonhosted.org/packages/b6/99/7f664804f1aef924542b0b233996b78b3e4d0a52d9951358aac99f129f51/regex-2026.6.28-cp313-cp313-win_arm64.whl", hash = "sha256:695873e0ea8d3815ea9e92e2c68faf039cc450e2c0a62a31afe2049eb11be767", size = 277017, upload-time = "2026-06-28T19:55:06.29Z" }, + { url = "https://files.pythonhosted.org/packages/cb/e1/9eb83518e159d719fd681c4932dc2aaff855ce72451e1d05d69466f25a96/regex-2026.6.28-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:189dbf9fc4252d9f1352bf4bd1bef885edb6cc4b7341df202a65f821aaa3891c", size = 494195, upload-time = "2026-06-28T19:55:08.292Z" }, + { url = "https://files.pythonhosted.org/packages/fd/e2/e259c5f2f7be269d0e2fb54275c1fa6a13fb47019f389c3f3ae457447825/regex-2026.6.28-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:9277a4c6503390aa39cb4483b87ec0384faee0850a23b5cea33d008b5d8d83f1", size = 293976, upload-time = "2026-06-28T19:55:10.014Z" }, + { url = "https://files.pythonhosted.org/packages/8d/4e/9bdf444014d22b045d0c82ca114fac7e07a597b5b5331b7c4ce6328426e2/regex-2026.6.28-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:17eddca4e8ea9af0b5739314776cdf0172a49731ab61f2e1ea66e066ddd46c97", size = 292340, upload-time = "2026-06-28T19:55:11.88Z" }, + { url = "https://files.pythonhosted.org/packages/fd/3a/f49b11e59cbfe187ace0053a460bd72a0169b8cd52e7db9421a074ce7a43/regex-2026.6.28-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e4466b8641e00c697aab5a73150150d2b2ea96b131c595691f42031abafd9f4d", size = 811704, upload-time = "2026-06-28T19:55:13.612Z" }, + { url = "https://files.pythonhosted.org/packages/2f/fb/ad04c39e149bf8b6cf357df5fff78341733ec366780a00c803a36735818c/regex-2026.6.28-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9cfcd4b0bdcf768c498415c170d1ed2a25a99bf0b65fa253bbd02f68ceba6475", size = 871157, upload-time = "2026-06-28T19:55:15.797Z" }, + { url = "https://files.pythonhosted.org/packages/7f/64/0e5ba31c11eb8ef7aac19a690c1211fc9aa9990caf09565785ebb0081b9a/regex-2026.6.28-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:80c7adf1ef647f6b1e8aa2ca280e517174cd08bdf7a2e412cdfb68bd6a0917cb", size = 917287, upload-time = "2026-06-28T19:55:18.692Z" }, + { url = "https://files.pythonhosted.org/packages/11/75/6b78df2b858c2fcbbc4858fdc3f2975cf2703be374b2842db7d2c32591a7/regex-2026.6.28-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a043f5770e82283a22aed4cefef1a4e0f9dd8fd7184cb6ce0ad2e579e2134a9e", size = 816333, upload-time = "2026-06-28T19:55:20.973Z" }, + { url = "https://files.pythonhosted.org/packages/b4/01/ecfe665a3694d5eda9f3ec686c856438ada0943947b6005e90556a1e2cdf/regex-2026.6.28-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3bd630a8dba06b55254ea5ee862194edab52ec783100d2ef1cd15a9c512fee27", size = 785518, upload-time = "2026-06-28T19:55:23.003Z" }, + { url = "https://files.pythonhosted.org/packages/b4/0a/88f9cd88ff1e82881605c4ffd62d77ee67d051232cfe6f8e9a64b86cf0e8/regex-2026.6.28-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:b77207e3cee13086f1906a6a2a12b41244c577e8ad9370d4b35ae1d548d354f3", size = 801371, upload-time = "2026-06-28T19:55:24.888Z" }, + { url = "https://files.pythonhosted.org/packages/a8/97/601483732f93275482ceb9fed57813dfed7c47d3a019db6ec4a3bb6e23e0/regex-2026.6.28-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:6de82c268e5d101ee9e3ffd869924aa9a371e3a21e752cf4fa17b6ce50d219f7", size = 866517, upload-time = "2026-06-28T19:55:27.232Z" }, + { url = "https://files.pythonhosted.org/packages/81/ed/385c2a0351b994a693453c1d1a6e9af9eb35db3c9460d76b5078acd70c62/regex-2026.6.28-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:b15859e3908544fb99cf47341dcf0bfd089147d258c4c4d8a29e5b087f8085cb", size = 772834, upload-time = "2026-06-28T19:55:29.154Z" }, + { url = "https://files.pythonhosted.org/packages/06/bc/bbf4a5b3b29770d7f307d3c28b5b1bca0105b0cb424be0a4eb1339bc92cf/regex-2026.6.28-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:c91487a917edd48a1ea646fdf60d7936d304f0e686fa7ea8326e47efca51d816", size = 856606, upload-time = "2026-06-28T19:55:32.186Z" }, + { url = "https://files.pythonhosted.org/packages/28/26/51d74fff82f682819979249f8d700267108ba5dc4eb284b0e11b9c85e4b3/regex-2026.6.28-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:c4ac65f3e3a99fd8f3a4a74e7a6610acd1ce9dfe9b8a03d346a4922380d68aeb", size = 803475, upload-time = "2026-06-28T19:55:34.328Z" }, + { url = "https://files.pythonhosted.org/packages/7c/3e/6be10cefdc813533fe604dbf5d3c77d2638e7ee658b2749ebadc113b6b2e/regex-2026.6.28-cp313-cp313t-win32.whl", hash = "sha256:3f6316f258bc7e6c9c2acbe9954947bbd397a81be3742a637a555f1855d6618d", size = 269126, upload-time = "2026-06-28T19:55:36.565Z" }, + { url = "https://files.pythonhosted.org/packages/3c/3c/32cda905ea1a6eeeb798291c294d8ec66ee0efe0cdba28b061e248b1d396/regex-2026.6.28-cp313-cp313t-win_amd64.whl", hash = "sha256:1484bdd6fba28422df9b5ebb04055b2e1b680e8e4f08490bb21ff0f3cc50d0ab", size = 279961, upload-time = "2026-06-28T19:55:38.456Z" }, + { url = "https://files.pythonhosted.org/packages/ea/b9/69f4e5cd6fbe0bb420cb2dbae441ca118f2495bdda522a74da75aa9829e7/regex-2026.6.28-cp313-cp313t-win_arm64.whl", hash = "sha256:3f15020f0b69cafe57baa067ff65b29acef68ff6b1670a53bef1ca11d708e02d", size = 279266, upload-time = "2026-06-28T19:55:40.62Z" }, { url = "https://files.pythonhosted.org/packages/3b/fb/fad3b810a5bb1e09b9e5d6913fc6ba88cab738fdf283196827a3c59a4c10/regex-2026.6.28-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:f7c032b0c8a73739ff8ff1aaf30c281fa19c17bf7f1543256c8507390db7807c", size = 490407, upload-time = "2026-06-28T19:55:42.724Z" }, { url = "https://files.pythonhosted.org/packages/d6/52/b8c79d12276d93e90e707e939b396034c04980caf1235312ef790f8e11fc/regex-2026.6.28-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:f6710f512c57b84f127a23d0f59560a03b64136eff419ae1be5ab557577fe5e3", size = 291988, upload-time = "2026-06-28T19:55:44.549Z" }, { url = "https://files.pythonhosted.org/packages/23/d2/6a911f18279daa8d7bb8b20d771ddb6ef31fabd35f5921f9d3ba21640e80/regex-2026.6.28-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c0013958f427bd82509a186b9ff206d66cb8d60a81fc797a4c717afd18c5b0ba", size = 289704, upload-time = "2026-06-28T19:55:46.365Z" }, @@ -1028,15 +1043,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" }, ] -[[package]] -name = "six" -version = "1.17.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, -] - [[package]] name = "sortedcontainers" version = "2.4.0" @@ -1046,18 +1052,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" }, ] -[[package]] -name = "starlette" -version = "1.3.1" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "anyio" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" }, -] - [[package]] name = "taskipy" version = "1.14.1" @@ -1077,19 +1071,14 @@ wheels = [ name = "temple8" version = "9.4.0" source = { virtual = "." } -dependencies = [ - { name = "flowr" }, -] [package.optional-dependencies] dev = [ - { name = "ghp-import" }, + { name = "flowr" }, { name = "hypothesis" }, { name = "mypy" }, - { name = "pdoc" }, { name = "pyright" }, { name = "pytest" }, - { name = "pytest-beehave" }, { name = "pytest-cov" }, { name = "pytest-html" }, { name = "pytest-mock" }, @@ -1100,22 +1089,13 @@ dev = [ { name = "vcrpy" }, ] -[package.dev-dependencies] -dev = [ - { name = "flowr", extra = ["viz"] }, - { name = "pytest-beehave", extra = ["html"] }, -] - [package.metadata] requires-dist = [ - { name = "flowr", specifier = ">=1.2.1" }, - { name = "ghp-import", marker = "extra == 'dev'", specifier = ">=2.1.0" }, + { name = "flowr", marker = "extra == 'dev'", specifier = ">=1.2.1" }, { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.148.4" }, { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" }, - { name = "pdoc", marker = "extra == 'dev'", specifier = ">=14.0" }, { name = "pyright", marker = "extra == 'dev'", specifier = ">=1.1.407" }, { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" }, - { name = "pytest-beehave", marker = "extra == 'dev'", specifier = ">=1.0.0" }, { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=6.1.1" }, { name = "pytest-html", marker = "extra == 'dev'", specifier = ">=4.0.0" }, { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.14.0" }, @@ -1127,12 +1107,6 @@ requires-dist = [ ] provides-extras = ["dev"] -[package.metadata.requires-dev] -dev = [ - { name = "flowr", extras = ["viz"], specifier = ">=1.2.0" }, - { name = "pytest-beehave", extras = ["html"], specifier = ">=1.0.0" }, -] - [[package]] name = "tenacity" version = "9.1.4" @@ -1148,6 +1122,15 @@ version = "2.4.1" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/22/de/48c59722572767841493b26183a0d1cc411d54fd759c5607c4590b6563a6/tomli-2.4.1.tar.gz", hash = "sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f", size = 17543, upload-time = "2026-03-25T20:22:03.828Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/07/06/b823a7e818c756d9a7123ba2cda7d07bc2dd32835648d1a7b7b7a05d848d/tomli-2.4.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54", size = 155866, upload-time = "2026-03-25T20:21:31.65Z" }, + { url = "https://files.pythonhosted.org/packages/14/6f/12645cf7f08e1a20c7eb8c297c6f11d31c1b50f316a7e7e1e1de6e2e7b7e/tomli-2.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a", size = 149887, upload-time = "2026-03-25T20:21:33.028Z" }, + { url = "https://files.pythonhosted.org/packages/5c/e0/90637574e5e7212c09099c67ad349b04ec4d6020324539297b634a0192b0/tomli-2.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897", size = 243704, upload-time = "2026-03-25T20:21:34.51Z" }, + { url = "https://files.pythonhosted.org/packages/10/8f/d3ddb16c5a4befdf31a23307f72828686ab2096f068eaf56631e136c1fdd/tomli-2.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f", size = 251628, upload-time = "2026-03-25T20:21:36.012Z" }, + { url = "https://files.pythonhosted.org/packages/e3/f1/dbeeb9116715abee2485bf0a12d07a8f31af94d71608c171c45f64c0469d/tomli-2.4.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d", size = 247180, upload-time = "2026-03-25T20:21:37.136Z" }, + { url = "https://files.pythonhosted.org/packages/d3/74/16336ffd19ed4da28a70959f92f506233bd7cfc2332b20bdb01591e8b1d1/tomli-2.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5", size = 251674, upload-time = "2026-03-25T20:21:38.298Z" }, + { url = "https://files.pythonhosted.org/packages/16/f9/229fa3434c590ddf6c0aa9af64d3af4b752540686cace29e6281e3458469/tomli-2.4.1-cp313-cp313-win32.whl", hash = "sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd", size = 97976, upload-time = "2026-03-25T20:21:39.316Z" }, + { url = "https://files.pythonhosted.org/packages/6a/1e/71dfd96bcc1c775420cb8befe7a9d35f2e5b1309798f009dca17b7708c1e/tomli-2.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36", size = 108755, upload-time = "2026-03-25T20:21:40.248Z" }, + { url = "https://files.pythonhosted.org/packages/83/7a/d34f422a021d62420b78f5c538e5b102f62bea616d1d75a13f0a88acb04a/tomli-2.4.1-cp313-cp313-win_arm64.whl", hash = "sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd", size = 95265, upload-time = "2026-03-25T20:21:41.219Z" }, { url = "https://files.pythonhosted.org/packages/3c/fb/9a5c8d27dbab540869f7c1f8eb0abb3244189ce780ba9cd73f3770662072/tomli-2.4.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf", size = 155726, upload-time = "2026-03-25T20:21:42.23Z" }, { url = "https://files.pythonhosted.org/packages/62/05/d2f816630cc771ad836af54f5001f47a6f611d2d39535364f148b6a92d6b/tomli-2.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac", size = 149859, upload-time = "2026-03-25T20:21:43.386Z" }, { url = "https://files.pythonhosted.org/packages/ce/48/66341bdb858ad9bd0ceab5a86f90eddab127cf8b046418009f2125630ecb/tomli-2.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662", size = 244713, upload-time = "2026-03-25T20:21:44.474Z" }, @@ -1235,19 +1218,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" }, ] -[[package]] -name = "uvicorn" -version = "0.49.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "click" }, - { name = "h11" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/c4/1f/fa18009dea8469069cca78a4e877a008ab78f08b064bfc9ab891579077ff/uvicorn-0.49.0.tar.gz", hash = "sha256:ebf4271aa580d9de97f93192d4595176df6e91f9aae919ca73e4fc07df1e66a3", size = 91284, upload-time = "2026-06-03T22:01:30.448Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/88/fa/e1388bbcf24ef3274f45c0c1c7b501fd14971037c1b6ee23610553307497/uvicorn-0.49.0-py3-none-any.whl", hash = "sha256:ba3d14c3ee7e41c6c654c46c9eb489d33213cdd30aa1696eab1374337c13f68f", size = 71376, upload-time = "2026-06-03T22:01:29.037Z" }, -] - [[package]] name = "vcrpy" version = "8.2.1" @@ -1267,6 +1237,28 @@ version = "2.2.2" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/fe/a4/282c8e64300a59fc834518a54bf0afabb4ff9218b5fa76958b450459a844/wrapt-2.2.2.tar.gz", hash = "sha256:0788e321027c999bf221b667bd4a54aaefd1a36283749a860ac3eb77daed0302", size = 129068, upload-time = "2026-06-20T23:49:44.49Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/43/fc/f32f4b22c6511173c11d9e541ab4e7d8467a0f1b3455acaf784115d31ff8/wrapt-2.2.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:9e8b648270c613720a202d9a45ebabc33261b22c3a839b115ac5bce8c0bb0d69", size = 81296, upload-time = "2026-06-20T23:48:15.881Z" }, + { url = "https://files.pythonhosted.org/packages/72/06/4d117d5d77a9344776c0248b24dae3d3dd2f58e5f765fa08cf887072e719/wrapt-2.2.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e6fb7e94e8fe3e4c3067bb1653a91cce7c5e83acc119fdd41501b1bf74654617", size = 81841, upload-time = "2026-06-20T23:48:17.262Z" }, + { url = "https://files.pythonhosted.org/packages/15/ff/63ad96f98eb58a742b1a20d80f21da88924405910149950b912368150468/wrapt-2.2.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:fb18fc51e813df0d9c98049e3bf2298a5495a648602040e21fa3c7329371159e", size = 167882, upload-time = "2026-06-20T23:48:18.764Z" }, + { url = "https://files.pythonhosted.org/packages/20/1f/8bb62d8933df7acf3247194e6e9fc68edf9d2fa203252c89c94b319dd472/wrapt-2.2.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:94b00b00f806eb3ef2abe9049ed45994a81ee9284884d96e6b8314927c6cea3d", size = 167411, upload-time = "2026-06-20T23:48:20.315Z" }, + { url = "https://files.pythonhosted.org/packages/17/09/8789dcb09ee1de715727db7521aabbb68ffa68dfade3a49468440cfced49/wrapt-2.2.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:62415fd095bc590b842b6d092f2b5d9ccbaeb7e0b28535c03dcea2718b48636b", size = 158607, upload-time = "2026-06-20T23:48:21.728Z" }, + { url = "https://files.pythonhosted.org/packages/9c/20/66e02562d53ee67d841f175e38e3c993c2d78a3e104c576cad61c028b43c/wrapt-2.2.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a41e758d80dc0ab8c210f641ac892009d356cf1f955d97db544c8dd317b4d14c", size = 166367, upload-time = "2026-06-20T23:48:23.177Z" }, + { url = "https://files.pythonhosted.org/packages/bd/a3/832ac4e41222fb263b3042d42c2f08d305db7d0f0c9b1d3a271a9eede8f6/wrapt-2.2.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:b84cd4058001c9727b0e9980b7a9e66325b5ca748b1b578e822cade1bc6b304f", size = 157176, upload-time = "2026-06-20T23:48:24.711Z" }, + { url = "https://files.pythonhosted.org/packages/b7/01/1bd5e4d2df9c0178989ac8da9186543465388588ee2ef153e2591accebef/wrapt-2.2.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:26fc73a1b15e0946d2942b9a4426d162b51676338327dc067ccd8d2d76385f94", size = 167025, upload-time = "2026-06-20T23:48:26.118Z" }, + { url = "https://files.pythonhosted.org/packages/1c/69/583ed25291ab53e1ec117135fb1c33425e2f46d2bc8f29c17f7a94cf4274/wrapt-2.2.2-cp313-cp313-win32.whl", hash = "sha256:3c4095803491f6ef72128914c28ec05bbad9758433bb35f6715a3e9c8e46fb2d", size = 77605, upload-time = "2026-06-20T23:48:27.643Z" }, + { url = "https://files.pythonhosted.org/packages/29/68/e69fc6d06e1523c68e0d00f95c9aed1158ce9908ee41603f7f2eae3d5db6/wrapt-2.2.2-cp313-cp313-win_amd64.whl", hash = "sha256:2cb07f414fab25dbe6b5c7398e1491423a5c81a6209533639969a6c928d474a4", size = 80508, upload-time = "2026-06-20T23:48:29.013Z" }, + { url = "https://files.pythonhosted.org/packages/55/21/fe7a393d9e5dc0923bed8f5d857e9dcff210f1fa0888c02cc8f3ffaa55aa/wrapt-2.2.2-cp313-cp313-win_arm64.whl", hash = "sha256:1fc7691f070220215cccb2a20836b9adbaecb8ff22ad47abe63de5f110994fac", size = 79565, upload-time = "2026-06-20T23:48:30.429Z" }, + { url = "https://files.pythonhosted.org/packages/b6/e5/c120d13bf5091164f68c3c1657e84f16f57e71d978421b626393ac5bd7eb/wrapt-2.2.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:ec8f83949028366531383603139403cac7a826e4011955813cdd640017845ce5", size = 83264, upload-time = "2026-06-20T23:48:31.807Z" }, + { url = "https://files.pythonhosted.org/packages/d3/b0/d4a1eb97e0e286625bdf21bc7f702637f9607787ffbbdb5ec14d50c79dbf/wrapt-2.2.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4b481fb0c40d9fd90a5809911208da700987d373a20a4709dc9e3944af7a6bec", size = 83791, upload-time = "2026-06-20T23:48:33.482Z" }, + { url = "https://files.pythonhosted.org/packages/18/1e/f060df47755e87b57684cee7bfc1362b204df55fac96ffebc0631b697b79/wrapt-2.2.2-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0065a3b657cec06813b4241d2462ccec287f6863103d7445b725fb3a889736f9", size = 203399, upload-time = "2026-06-20T23:48:34.97Z" }, + { url = "https://files.pythonhosted.org/packages/c4/de/2316a757a1abb6453700b79d83e532146dcef2611348282d4d8889792161/wrapt-2.2.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:30f7424af5c5c345b7f26490e097f74a2ef45b3d08b664dc33571aee3bd3b56c", size = 210461, upload-time = "2026-06-20T23:48:36.569Z" }, + { url = "https://files.pythonhosted.org/packages/ed/29/d1160785ae18ca2495a6d82a21154103d74f656c9fd457fb35f6b11b965a/wrapt-2.2.2-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:07fdcb012821859168641acf68afad61ef9783cf37100af85f152550e9677194", size = 195313, upload-time = "2026-06-20T23:48:38.175Z" }, + { url = "https://files.pythonhosted.org/packages/f5/2d/7caa9598ae61a9cf0989cc501739cbeeb7d650ab3193cca1407b9af0c6ab/wrapt-2.2.2-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:f90038ab58fafb584801ca62d72384d7d5225d93c76f7b773c22fae545bd8066", size = 206116, upload-time = "2026-06-20T23:48:39.804Z" }, + { url = "https://files.pythonhosted.org/packages/ac/02/281ea1088b8650d865f311b35cf86fd21df89128e2909714f1161e01c9d0/wrapt-2.2.2-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:c5d7825491bfa2d08b97e9557768987952c7b9ae687d06c3320b40a37ccb7f20", size = 192668, upload-time = "2026-06-20T23:48:41.346Z" }, + { url = "https://files.pythonhosted.org/packages/be/7d/976e2d5b4b5c5babda40974edd54d0a5585cb60132ed86b46f4b80239b16/wrapt-2.2.2-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:0ad520e6daa9bbf136f14de735474dbec7dcc0891f718e1d274ce8dc92e645af", size = 198891, upload-time = "2026-06-20T23:48:43.056Z" }, + { url = "https://files.pythonhosted.org/packages/59/b7/e47651797c097f75a37e2ce86dcf04048ff576f3a674f7c558df7b5e9622/wrapt-2.2.2-cp313-cp313t-win32.whl", hash = "sha256:25904acb9475f46c24fe0423dbc8fda8cc5fbc282ab3dc6e72e919748c53f4e9", size = 78537, upload-time = "2026-06-20T23:48:44.509Z" }, + { url = "https://files.pythonhosted.org/packages/d1/6f/9fa5d59fb06d890defb5a8f727ce6a14d2932c8760153f96956628559fee/wrapt-2.2.2-cp313-cp313t-win_amd64.whl", hash = "sha256:305d4c247d61c4115794a169141823c62f719525ddb90b23aa332741c77d2c28", size = 82005, upload-time = "2026-06-20T23:48:46.391Z" }, + { url = "https://files.pythonhosted.org/packages/15/80/4c7bd9873d1f9f7d138d93556b500469dbe24f42710b877519c2b9eb380d/wrapt-2.2.2-cp313-cp313t-win_arm64.whl", hash = "sha256:c20279cd1a29800815d7b2d6338b60a6c6e78263f9d6e62e0eda251ba9cae2d0", size = 80762, upload-time = "2026-06-20T23:48:47.964Z" }, { url = "https://files.pythonhosted.org/packages/24/05/7fd9c3f83b2c74cbfc572a0b88aa37431e04bd8aed70d2c0efd3464206de/wrapt-2.2.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0e64826f920c42d9d9f87e8cc09ffae66c51ede12d59061a5a426deb9aa71745", size = 81341, upload-time = "2026-06-20T23:48:49.39Z" }, { url = "https://files.pythonhosted.org/packages/4b/68/1bfa43100dd90d4ef74a05897b86275cf57e1313ca14aae2545bc9f872c9/wrapt-2.2.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:dcaa5e1451bd8751d7bd1568dfa3321c78092a52a7ecb5d1a0f18a5791e1fd00", size = 81921, upload-time = "2026-06-20T23:48:50.986Z" }, { url = "https://files.pythonhosted.org/packages/74/eb/df7b7f0b631dbbc750f39be27d8b55f65777d8ac86da80e12be41a644c4b/wrapt-2.2.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0abfd648dac9ac9c5b3aa9b523d27f1789046640b58dcd5652a720ddb325e1fc", size = 167713, upload-time = "2026-06-20T23:48:52.598Z" }, From 6fee978e04df970111761834345ef34d0ce2b769 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 00:55:01 -0400 Subject: [PATCH 12/28] feat(dogfood): weather-lookup discovery + explore (real cassettes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First real pipeline run (session: dogfood) through discover + explore. Discover (condensed interview, product-owner role): - .cache/dogfood/interview-notes.md — 4-level funnel for weather-lookup (general/cross-cutting/building-blocks/consolidation); 4 contracts emerge: Settings, WeatherAdapter (external), History (persistence), WeatherService (CLI e2e); outside-in order; zero gaps. - docs/glossary.md — 6 terms across weather-lookup + history contexts. Explore (integration-engineer role; real network probes of open-meteo): - tests/cassettes/open-meteo/geocoding.yaml — Berlin hit + Xyzqwerty miss (200 with no 'results' is the unknown-city error, branched on body not status). - tests/cassettes/open-meteo/forecast.yaml — Berlin current conditions. - Cassettes scrubbed: bodies decoded (decode_compressed_response), volatile headers stripped (date/server/cf-ray/content-encoding/...). - .cache/dogfood/{probe-target,probe-research,external-contracts}.md + .cache/explore/open-meteo/probe.py (gitignored working state). Validated: pipeline auto-enters discovery subflow; 4-state discover chain; discover->explore->plan subflow chaining fires on real exits. Session now at plan-flow/author-test-stubs. --- docs/glossary.md | 42 +++++++++++++++++ tests/cassettes/open-meteo/forecast.yaml | 27 +++++++++++ tests/cassettes/open-meteo/geocoding.yaml | 55 +++++++++++++++++++++++ 3 files changed, 124 insertions(+) create mode 100644 docs/glossary.md create mode 100644 tests/cassettes/open-meteo/forecast.yaml create mode 100644 tests/cassettes/open-meteo/geocoding.yaml diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..6dd31e97 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,42 @@ +# Glossary: temple8 + +> The ubiquitous language for this project — terms shared across conversation, +> code, and documentation (Evans, 2003). Curated from the interview for the +> IMPORTANT domain concepts, not every code symbol. Grouped by bounded context, +> where each term has one meaning. The tests are the source of truth for +> behaviour; this glossary is the source of truth for names. Extend or revise +> entries as understanding shifts. + +## Context: weather-lookup + +### City +A place name that the user supplies as the lookup target, resolved to +coordinates through the geocoding service. +*Aliases: none · Source: weather lookup* + +### Coordinates +A geographic position that the geocoding service returns for a city, carrying +the latitude and longitude the forecast service needs. +*Aliases: lat/lon · Source: weather lookup* + +### Conditions +A snapshot of the current weather at a coordinate — temperature, wind speed, +and weather code — produced by the forecast service. +*Aliases: current weather · Source: weather lookup* + +### WeatherAdapter +An anti-corruption layer that translates the open-meteo geocoding and forecast +endpoints into the domain's `Coordinates` and `Conditions` types. +*Aliases: none · Source: weather lookup* + +## Context: history + +### Lookup +A single completed weather check — the city asked, the conditions returned, and +the time it was recorded — stored as one entry in the history. +*Aliases: LookupRecord · Source: weather lookup* + +### History +An ordered, latest-first log of past lookups that the system appends to on each +check and recalls on demand. +*Aliases: lookup log · Source: weather lookup* diff --git a/tests/cassettes/open-meteo/forecast.yaml b/tests/cassettes/open-meteo/forecast.yaml new file mode 100644 index 00000000..dd4ec200 --- /dev/null +++ b/tests/cassettes/open-meteo/forecast.yaml @@ -0,0 +1,27 @@ +interactions: +- request: + body: '' + headers: + accept: + - '*/*' + accept-encoding: + - gzip, deflate + connection: + - keep-alive + host: + - api.open-meteo.com + method: GET + uri: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41¤t=temperature_2m%2Cwind_speed_10m%2Cweather_code + response: + body: + string: "{\"latitude\":52.52,\"longitude\":13.419998,\"generationtime_ms\":0.07045269012451172,\"utc_offset_seconds\":0,\"timezone\":\"GMT\",\"timezone_abbreviation\":\"GMT\",\"elevation\":38.0,\"current_units\":{\"time\":\"iso8601\",\"interval\":\"seconds\",\"temperature_2m\":\"\xB0C\",\"wind_speed_10m\":\"km/h\",\"weather_code\":\"wmo + code\"},\"current\":{\"time\":\"2026-07-02T04:45\",\"interval\":900,\"temperature_2m\":15.9,\"wind_speed_10m\":6.6,\"weather_code\":0}}" + headers: + content-length: + - '409' + content-type: + - application/json; charset=utf-8 + status: + code: 200 + message: OK +version: 1 diff --git a/tests/cassettes/open-meteo/geocoding.yaml b/tests/cassettes/open-meteo/geocoding.yaml new file mode 100644 index 00000000..5ab728fb --- /dev/null +++ b/tests/cassettes/open-meteo/geocoding.yaml @@ -0,0 +1,55 @@ +interactions: +- request: + body: '' + headers: + accept: + - '*/*' + accept-encoding: + - gzip, deflate + connection: + - keep-alive + host: + - geocoding-api.open-meteo.com + method: GET + uri: https://geocoding-api.open-meteo.com/v1/search?name=Berlin&count=1&language=en&format=json + response: + body: + string: '{"results":[{"id":2950159,"name":"Berlin","latitude":52.52437,"longitude":13.41053,"elevation":74.0,"feature_code":"PPLC","country_code":"DE","admin1_id":2950157,"admin3_id":6547383,"admin4_id":6547539,"timezone":"Europe/Berlin","population":3426354,"postcodes":["10967","13347"],"country_id":2921044,"country":"Germany","admin1":"State + of Berlin","admin3":"Berlin, Stadt","admin4":"Berlin"}],"generationtime_ms":0.5326271}' + headers: + content-length: + - '423' + content-type: + - application/json; charset=utf-8 + x-encoding-time: + - 0.003993511199951172 ms + status: + code: 200 + message: OK +- request: + body: '' + headers: + accept: + - '*/*' + accept-encoding: + - gzip, deflate + connection: + - keep-alive + host: + - geocoding-api.open-meteo.com + method: GET + uri: https://geocoding-api.open-meteo.com/v1/search?name=Xyzqwerty&count=1&language=en&format=json + response: + body: + string: '{"generationtime_ms":0.096678734}' + headers: + content-length: + - '33' + content-type: + - application/json; charset=utf-8 + x-encoding-time: + - 0.0016450881958007812 ms + status: + code: 200 + message: OK +version: 1 From f203444344740cd552c78e68c26b4b6a6b6225ed Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 01:08:58 -0400 Subject: [PATCH 13/28] feat(dogfood): plan phase - test + source stubs for 4 contracts Plan phase of the dogfood pipeline run (session: dogfood). author-test-stubs -> review -> write-test-py -> derive-source-stubs -> simulate: - tests/integration/{settings,weather,history}_test.{py,pyi} - tests/e2e/cli_test.{py,pyi} 9 tests, all @pytest.mark.pending, deferred SUT imports, skipping cleanly. - app/{__init__,settings,weather,history,cli}.pyi derived from the test bodies. - Cassette consolidated to one per service (tests/cassettes/open-meteo/open-meteo.yaml, 3 interactions) so the e2e flow replays both calls from a single file; drops the per-endpoint geocoding.yaml + forecast.yaml. Coherence fix surfaced by the simulate walkthrough: the forecast interaction was recorded with geocoded coords (52.52437/13.41053) so geocode->forecast shares one coordinate shape across the forecast test, the e2e test, and the cassette (vcr matches on query). Forecast value 16.1/6.5/weather_code 0. Gates: pyright 0 errors (9 reportMissingModuleSource = expected, no source .py yet); stubtest on test pairs Success; 6 evidence asserted at simulate -> contracts-ready. Session now at tdd-flow/select. --- app/__init__.pyi | 0 app/cli.pyi | 4 ++ app/history.pyi | 15 ++++++ app/settings.pyi | 12 +++++ app/weather.pyi | 20 ++++++++ tests/cassettes/open-meteo/forecast.yaml | 27 ----------- .../{geocoding.yaml => open-meteo.yaml} | 35 ++++++++++++-- tests/e2e/cli_test.py | 23 ++++++++++ tests/e2e/cli_test.pyi | 6 +++ tests/integration/history_test.py | 44 ++++++++++++++++++ tests/integration/history_test.pyi | 10 ++++ tests/integration/settings_test.py | 33 +++++++++++++ tests/integration/settings_test.pyi | 7 +++ tests/integration/weather_test.py | 46 +++++++++++++++++++ tests/integration/weather_test.pyi | 12 +++++ 15 files changed, 262 insertions(+), 32 deletions(-) create mode 100644 app/__init__.pyi create mode 100644 app/cli.pyi create mode 100644 app/history.pyi create mode 100644 app/settings.pyi create mode 100644 app/weather.pyi delete mode 100644 tests/cassettes/open-meteo/forecast.yaml rename tests/cassettes/open-meteo/{geocoding.yaml => open-meteo.yaml} (55%) create mode 100644 tests/e2e/cli_test.py create mode 100644 tests/e2e/cli_test.pyi create mode 100644 tests/integration/history_test.py create mode 100644 tests/integration/history_test.pyi create mode 100644 tests/integration/settings_test.py create mode 100644 tests/integration/settings_test.pyi create mode 100644 tests/integration/weather_test.py create mode 100644 tests/integration/weather_test.pyi diff --git a/app/__init__.pyi b/app/__init__.pyi new file mode 100644 index 00000000..e69de29b diff --git a/app/cli.pyi b/app/cli.pyi new file mode 100644 index 00000000..7ee2ea60 --- /dev/null +++ b/app/cli.pyi @@ -0,0 +1,4 @@ +from collections.abc import Sequence + + +def main(argv: Sequence[str]) -> None: ... diff --git a/app/history.pyi b/app/history.pyi new file mode 100644 index 00000000..931cd0da --- /dev/null +++ b/app/history.pyi @@ -0,0 +1,15 @@ +from dataclasses import dataclass + + +@dataclass(frozen=True) +class LookupRecord: + city: str + temperature: float + wind_speed: float + weather_code: int + + +class History: + def __init__(self, database_url: str) -> None: ... + def record(self, lookup: LookupRecord) -> None: ... + def recent(self) -> list[LookupRecord]: ... diff --git a/app/settings.pyi b/app/settings.pyi new file mode 100644 index 00000000..1abce396 --- /dev/null +++ b/app/settings.pyi @@ -0,0 +1,12 @@ +from dataclasses import dataclass +from typing import Self + + +@dataclass(frozen=True) +class Settings: + geocoding_base: str + forecast_base: str + database_url: str + + @classmethod + def from_env(cls) -> Self: ... diff --git a/app/weather.pyi b/app/weather.pyi new file mode 100644 index 00000000..97a81af0 --- /dev/null +++ b/app/weather.pyi @@ -0,0 +1,20 @@ +from dataclasses import dataclass + + +@dataclass(frozen=True) +class Coordinates: + latitude: float + longitude: float + + +@dataclass(frozen=True) +class Conditions: + temperature: float + wind_speed: float + weather_code: int + + +class WeatherAdapter: + def __init__(self, geocoding_base: str, forecast_base: str) -> None: ... + def geocode(self, city: str) -> Coordinates: ... + def forecast(self, coordinates: Coordinates) -> Conditions: ... diff --git a/tests/cassettes/open-meteo/forecast.yaml b/tests/cassettes/open-meteo/forecast.yaml deleted file mode 100644 index dd4ec200..00000000 --- a/tests/cassettes/open-meteo/forecast.yaml +++ /dev/null @@ -1,27 +0,0 @@ -interactions: -- request: - body: '' - headers: - accept: - - '*/*' - accept-encoding: - - gzip, deflate - connection: - - keep-alive - host: - - api.open-meteo.com - method: GET - uri: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41¤t=temperature_2m%2Cwind_speed_10m%2Cweather_code - response: - body: - string: "{\"latitude\":52.52,\"longitude\":13.419998,\"generationtime_ms\":0.07045269012451172,\"utc_offset_seconds\":0,\"timezone\":\"GMT\",\"timezone_abbreviation\":\"GMT\",\"elevation\":38.0,\"current_units\":{\"time\":\"iso8601\",\"interval\":\"seconds\",\"temperature_2m\":\"\xB0C\",\"wind_speed_10m\":\"km/h\",\"weather_code\":\"wmo - code\"},\"current\":{\"time\":\"2026-07-02T04:45\",\"interval\":900,\"temperature_2m\":15.9,\"wind_speed_10m\":6.6,\"weather_code\":0}}" - headers: - content-length: - - '409' - content-type: - - application/json; charset=utf-8 - status: - code: 200 - message: OK -version: 1 diff --git a/tests/cassettes/open-meteo/geocoding.yaml b/tests/cassettes/open-meteo/open-meteo.yaml similarity index 55% rename from tests/cassettes/open-meteo/geocoding.yaml rename to tests/cassettes/open-meteo/open-meteo.yaml index 5ab728fb..58b2fd07 100644 --- a/tests/cassettes/open-meteo/geocoding.yaml +++ b/tests/cassettes/open-meteo/open-meteo.yaml @@ -15,14 +15,14 @@ interactions: response: body: string: '{"results":[{"id":2950159,"name":"Berlin","latitude":52.52437,"longitude":13.41053,"elevation":74.0,"feature_code":"PPLC","country_code":"DE","admin1_id":2950157,"admin3_id":6547383,"admin4_id":6547539,"timezone":"Europe/Berlin","population":3426354,"postcodes":["10967","13347"],"country_id":2921044,"country":"Germany","admin1":"State - of Berlin","admin3":"Berlin, Stadt","admin4":"Berlin"}],"generationtime_ms":0.5326271}' + of Berlin","admin3":"Berlin, Stadt","admin4":"Berlin"}],"generationtime_ms":0.6958246}' headers: content-length: - '423' content-type: - application/json; charset=utf-8 x-encoding-time: - - 0.003993511199951172 ms + - 0.0037431716918945312 ms status: code: 200 message: OK @@ -41,14 +41,39 @@ interactions: uri: https://geocoding-api.open-meteo.com/v1/search?name=Xyzqwerty&count=1&language=en&format=json response: body: - string: '{"generationtime_ms":0.096678734}' + string: '{"generationtime_ms":0.09262562}' headers: content-length: - - '33' + - '32' content-type: - application/json; charset=utf-8 x-encoding-time: - - 0.0016450881958007812 ms + - 0.001239776611328125 ms + status: + code: 200 + message: OK +- request: + body: '' + headers: + accept: + - '*/*' + accept-encoding: + - gzip, deflate + connection: + - keep-alive + host: + - api.open-meteo.com + method: GET + uri: https://api.open-meteo.com/v1/forecast?latitude=52.52437&longitude=13.41053¤t=temperature_2m%2Cwind_speed_10m%2Cweather_code + response: + body: + string: "{\"latitude\":52.52,\"longitude\":13.419998,\"generationtime_ms\":0.10025501251220703,\"utc_offset_seconds\":0,\"timezone\":\"GMT\",\"timezone_abbreviation\":\"GMT\",\"elevation\":46.0,\"current_units\":{\"time\":\"iso8601\",\"interval\":\"seconds\",\"temperature_2m\":\"\xB0C\",\"wind_speed_10m\":\"km/h\",\"weather_code\":\"wmo + code\"},\"current\":{\"time\":\"2026-07-02T05:00\",\"interval\":900,\"temperature_2m\":16.1,\"wind_speed_10m\":6.5,\"weather_code\":0}}" + headers: + content-length: + - '409' + content-type: + - application/json; charset=utf-8 status: code: 200 message: OK diff --git a/tests/e2e/cli_test.py b/tests/e2e/cli_test.py new file mode 100644 index 00000000..721bf819 --- /dev/null +++ b/tests/e2e/cli_test.py @@ -0,0 +1,23 @@ +from typing import Any + +import pytest + +CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" + + +@pytest.mark.pending +def test_cli_prints_current_conditions_for_a_city(capsys: Any, monkeypatch: Any) -> None: + import vcr + + from app.cli import main + + monkeypatch.setenv("WEATHER_GEOCODING_BASE", "https://geocoding-api.open-meteo.com") + monkeypatch.setenv("WEATHER_FORECAST_BASE", "https://api.open-meteo.com") + monkeypatch.setenv("DATABASE_URL", "sqlite:///:memory:") + + with vcr.use_cassette(CASSETTE): + main(["Berlin"]) + + out = capsys.readouterr().out + assert "Berlin" in out + assert "16.1" in out diff --git a/tests/e2e/cli_test.pyi b/tests/e2e/cli_test.pyi new file mode 100644 index 00000000..e2d88dee --- /dev/null +++ b/tests/e2e/cli_test.pyi @@ -0,0 +1,6 @@ +from typing import Any + +CASSETTE: str + + +def test_cli_prints_current_conditions_for_a_city(capsys: Any, monkeypatch: Any) -> None: ... diff --git a/tests/integration/history_test.py b/tests/integration/history_test.py new file mode 100644 index 00000000..25d3a5f9 --- /dev/null +++ b/tests/integration/history_test.py @@ -0,0 +1,44 @@ +from typing import Any + +import pytest + + +@pytest.mark.pending +def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: + from app.history import History, LookupRecord + + history = History(f"sqlite:///{tmp_path / 'weather.db'}") + history.record( + LookupRecord(city="Berlin", temperature=16.2, wind_speed=6.5, weather_code=0) + ) + + recent = history.recent() + + assert len(recent) == 1 + assert recent[0].city == "Berlin" + + +@pytest.mark.pending +def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: + from app.history import History, LookupRecord + + history = History(f"sqlite:///{tmp_path / 'weather.db'}") + history.record( + LookupRecord(city="Berlin", temperature=16.2, wind_speed=6.5, weather_code=0) + ) + history.record( + LookupRecord(city="Paris", temperature=20.0, wind_speed=5.0, weather_code=1) + ) + + recent = history.recent() + + assert [r.city for r in recent] == ["Paris", "Berlin"] + + +@pytest.mark.pending +def test_recent_returns_empty_list_when_none_recorded(tmp_path: Any) -> None: + from app.history import History + + history = History(f"sqlite:///{tmp_path / 'weather.db'}") + + assert history.recent() == [] diff --git a/tests/integration/history_test.pyi b/tests/integration/history_test.pyi new file mode 100644 index 00000000..e75dc49d --- /dev/null +++ b/tests/integration/history_test.pyi @@ -0,0 +1,10 @@ +from typing import Any + + +def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: ... + + +def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: ... + + +def test_recent_returns_empty_list_when_none_recorded(tmp_path: Any) -> None: ... diff --git a/tests/integration/settings_test.py b/tests/integration/settings_test.py new file mode 100644 index 00000000..3bafe31f --- /dev/null +++ b/tests/integration/settings_test.py @@ -0,0 +1,33 @@ +from typing import Any + +import pytest + + +@pytest.mark.pending +def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: + from app.settings import Settings + + monkeypatch.setenv("WEATHER_GEOCODING_BASE", "https://geo.example.com") + monkeypatch.setenv("WEATHER_FORECAST_BASE", "https://forecast.example.com") + monkeypatch.setenv("DATABASE_URL", "sqlite:///tmp/test.db") + + settings = Settings.from_env() + + assert settings.geocoding_base == "https://geo.example.com" + assert settings.forecast_base == "https://forecast.example.com" + assert settings.database_url == "sqlite:///tmp/test.db" + + +@pytest.mark.pending +def test_from_env_applies_defaults_when_env_unset(monkeypatch: Any) -> None: + from app.settings import Settings + + monkeypatch.delenv("WEATHER_GEOCODING_BASE", raising=False) + monkeypatch.delenv("WEATHER_FORECAST_BASE", raising=False) + monkeypatch.delenv("DATABASE_URL", raising=False) + + settings = Settings.from_env() + + assert settings.geocoding_base == "https://geocoding-api.open-meteo.com" + assert settings.forecast_base == "https://api.open-meteo.com" + assert settings.database_url == "sqlite:///weather.db" diff --git a/tests/integration/settings_test.pyi b/tests/integration/settings_test.pyi new file mode 100644 index 00000000..49eacfaf --- /dev/null +++ b/tests/integration/settings_test.pyi @@ -0,0 +1,7 @@ +from typing import Any + + +def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: ... + + +def test_from_env_applies_defaults_when_env_unset(monkeypatch: Any) -> None: ... diff --git a/tests/integration/weather_test.py b/tests/integration/weather_test.py new file mode 100644 index 00000000..65d65576 --- /dev/null +++ b/tests/integration/weather_test.py @@ -0,0 +1,46 @@ +import pytest + +GEOCODING_BASE = "https://geocoding-api.open-meteo.com" +FORECAST_BASE = "https://api.open-meteo.com" +CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" + + +@pytest.mark.pending +def test_geocode_returns_coordinates_for_a_known_city() -> None: + import vcr + + from app.weather import WeatherAdapter + + adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) + with vcr.use_cassette(CASSETTE): + coordinates = adapter.geocode("Berlin") + + assert coordinates.latitude == pytest.approx(52.52437) + assert coordinates.longitude == pytest.approx(13.41053) + + +@pytest.mark.pending +def test_geocode_raises_for_an_unknown_city() -> None: + import vcr + + from app.weather import WeatherAdapter + + adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) + with vcr.use_cassette(CASSETTE): + with pytest.raises(LookupError): + adapter.geocode("Xyzqwerty") + + +@pytest.mark.pending +def test_forecast_returns_conditions_for_coordinates() -> None: + import vcr + + from app.weather import Coordinates, WeatherAdapter + + adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) + with vcr.use_cassette(CASSETTE): + conditions = adapter.forecast(Coordinates(52.52437, 13.41053)) + + assert conditions.temperature == pytest.approx(16.1) + assert conditions.wind_speed == pytest.approx(6.5) + assert conditions.weather_code == 0 diff --git a/tests/integration/weather_test.pyi b/tests/integration/weather_test.pyi new file mode 100644 index 00000000..6c4ca4ac --- /dev/null +++ b/tests/integration/weather_test.pyi @@ -0,0 +1,12 @@ +GEOCODING_BASE: str +FORECAST_BASE: str +CASSETTE: str + + +def test_geocode_returns_coordinates_for_a_known_city() -> None: ... + + +def test_geocode_raises_for_an_unknown_city() -> None: ... + + +def test_forecast_returns_conditions_for_coordinates() -> None: ... From daf82998d5fdfc7b91ef6488ce80719180b4f9c9 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 01:26:28 -0400 Subject: [PATCH 14/28] feat(settings): implement Settings config contract Frozen dataclass + from_env classmethod reading WEATHER_GEOCODING_BASE / WEATHER_FORECAST_BASE / DATABASE_URL with open-meteo defaults. Un-marks the 2 settings tests. --- app/settings.py | 22 ++++++++++++++++++++++ tests/integration/settings_test.py | 4 ---- 2 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 app/settings.py diff --git a/app/settings.py b/app/settings.py new file mode 100644 index 00000000..104b68e4 --- /dev/null +++ b/app/settings.py @@ -0,0 +1,22 @@ +import os +from dataclasses import dataclass +from typing import Self + + +@dataclass(frozen=True) +class Settings: + geocoding_base: str + forecast_base: str + database_url: str + + @classmethod + def from_env(cls) -> Self: + return cls( + geocoding_base=os.environ.get( + "WEATHER_GEOCODING_BASE", "https://geocoding-api.open-meteo.com" + ), + forecast_base=os.environ.get( + "WEATHER_FORECAST_BASE", "https://api.open-meteo.com" + ), + database_url=os.environ.get("DATABASE_URL", "sqlite:///weather.db"), + ) diff --git a/tests/integration/settings_test.py b/tests/integration/settings_test.py index 3bafe31f..d850b8de 100644 --- a/tests/integration/settings_test.py +++ b/tests/integration/settings_test.py @@ -1,9 +1,6 @@ from typing import Any -import pytest - -@pytest.mark.pending def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: from app.settings import Settings @@ -18,7 +15,6 @@ def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: assert settings.database_url == "sqlite:///tmp/test.db" -@pytest.mark.pending def test_from_env_applies_defaults_when_env_unset(monkeypatch: Any) -> None: from app.settings import Settings From 74e54755fa961823b08b41541e5b4545fbe67b90 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 01:31:35 -0400 Subject: [PATCH 15/28] feat(weather): implement WeatherAdapter over open-meteo httpx client; geocode raises LookupError on unknown city (body has no 'results'); forecast returns Conditions. Replays tests/cassettes/open-meteo. Adds httpx as a project dependency. --- app/weather.py | 51 +++++++++++++++++++++++++++++++ pyproject.toml | 2 +- tests/integration/weather_test.py | 8 ++--- 3 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 app/weather.py diff --git a/app/weather.py b/app/weather.py new file mode 100644 index 00000000..a28b1b9f --- /dev/null +++ b/app/weather.py @@ -0,0 +1,51 @@ +import httpx +from dataclasses import dataclass + + +@dataclass(frozen=True) +class Coordinates: + latitude: float + longitude: float + + +@dataclass(frozen=True) +class Conditions: + temperature: float + wind_speed: float + weather_code: int + + +class WeatherAdapter: + def __init__(self, geocoding_base: str, forecast_base: str) -> None: + self._geocoding_base = geocoding_base + self._forecast_base = forecast_base + self._client = httpx.Client() + + def geocode(self, city: str) -> Coordinates: + response = self._client.get( + f"{self._geocoding_base}/v1/search", + params={"name": city, "count": 1, "language": "en", "format": "json"}, + ) + response.raise_for_status() + results = response.json().get("results") + if not results: + raise LookupError(city) + hit = results[0] + return Coordinates(latitude=hit["latitude"], longitude=hit["longitude"]) + + def forecast(self, coordinates: Coordinates) -> Conditions: + response = self._client.get( + f"{self._forecast_base}/v1/forecast", + params={ + "latitude": coordinates.latitude, + "longitude": coordinates.longitude, + "current": "temperature_2m,wind_speed_10m,weather_code", + }, + ) + response.raise_for_status() + current = response.json()["current"] + return Conditions( + temperature=current["temperature_2m"], + wind_speed=current["wind_speed_10m"], + weather_code=current["weather_code"], + ) diff --git a/pyproject.toml b/pyproject.toml index 89cc3103..b1960257 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ authors = [ maintainers = [ { name = "eol", email = "nullhack@users.noreply.github.com" } ] -dependencies = [] +dependencies = ["httpx>=0.27.0"] [project.urls] Homepage = "https://nullhack.github.io/temple8/" diff --git a/tests/integration/weather_test.py b/tests/integration/weather_test.py index 65d65576..3032fc06 100644 --- a/tests/integration/weather_test.py +++ b/tests/integration/weather_test.py @@ -5,7 +5,6 @@ CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" -@pytest.mark.pending def test_geocode_returns_coordinates_for_a_known_city() -> None: import vcr @@ -19,19 +18,16 @@ def test_geocode_returns_coordinates_for_a_known_city() -> None: assert coordinates.longitude == pytest.approx(13.41053) -@pytest.mark.pending def test_geocode_raises_for_an_unknown_city() -> None: import vcr from app.weather import WeatherAdapter adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) - with vcr.use_cassette(CASSETTE): - with pytest.raises(LookupError): - adapter.geocode("Xyzqwerty") + with vcr.use_cassette(CASSETTE), pytest.raises(LookupError): + adapter.geocode("Xyzqwerty") -@pytest.mark.pending def test_forecast_returns_conditions_for_coordinates() -> None: import vcr From af98dce81b34e3969137e5beb2b8a87abe9f1b55 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 01:33:56 -0400 Subject: [PATCH 16/28] feat(history): implement History persistence over sqlite3 Normalizes database_url (strips sqlite:/// prefix); record inserts; recent returns LookupRecords latest-first (ORDER BY id DESC). --- app/history.py | 45 +++++++++++++++++++++++++++++++ tests/integration/history_test.py | 5 ---- 2 files changed, 45 insertions(+), 5 deletions(-) create mode 100644 app/history.py diff --git a/app/history.py b/app/history.py new file mode 100644 index 00000000..545b1e7a --- /dev/null +++ b/app/history.py @@ -0,0 +1,45 @@ +import sqlite3 +from dataclasses import dataclass + + +@dataclass(frozen=True) +class LookupRecord: + city: str + temperature: float + wind_speed: float + weather_code: int + + +class History: + def __init__(self, database_url: str) -> None: + path = database_url.removeprefix("sqlite:///") + self._connection = sqlite3.connect(path) + self._connection.execute( + "CREATE TABLE IF NOT EXISTS lookups" + " (id INTEGER PRIMARY KEY AUTOINCREMENT," + " city TEXT, temperature REAL, wind_speed REAL, weather_code INTEGER)" + ) + self._connection.commit() + + def record(self, lookup: LookupRecord) -> None: + self._connection.execute( + "INSERT INTO lookups (city, temperature, wind_speed, weather_code)" + " VALUES (?, ?, ?, ?)", + (lookup.city, lookup.temperature, lookup.wind_speed, lookup.weather_code), + ) + self._connection.commit() + + def recent(self) -> list[LookupRecord]: + rows = self._connection.execute( + "SELECT city, temperature, wind_speed, weather_code" + " FROM lookups ORDER BY id DESC" + ).fetchall() + return [ + LookupRecord( + city=row[0], + temperature=row[1], + wind_speed=row[2], + weather_code=row[3], + ) + for row in rows + ] diff --git a/tests/integration/history_test.py b/tests/integration/history_test.py index 25d3a5f9..3bc306aa 100644 --- a/tests/integration/history_test.py +++ b/tests/integration/history_test.py @@ -1,9 +1,6 @@ from typing import Any -import pytest - -@pytest.mark.pending def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: from app.history import History, LookupRecord @@ -18,7 +15,6 @@ def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: assert recent[0].city == "Berlin" -@pytest.mark.pending def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: from app.history import History, LookupRecord @@ -35,7 +31,6 @@ def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: assert [r.city for r in recent] == ["Paris", "Berlin"] -@pytest.mark.pending def test_recent_returns_empty_list_when_none_recorded(tmp_path: Any) -> None: from app.history import History From 39b69e18951ec33b348e0e47753ddbc4cf07ce49 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 01:36:06 -0400 Subject: [PATCH 17/28] feat(cli): implement WeatherService CLI composition main composes Settings.from_env + WeatherAdapter + History; geocode -> forecast -> record -> print. E2E replays the open-meteo cassette. --- app/cli.py | 22 ++++++++++++++++++++++ tests/e2e/cli_test.py | 7 +++---- 2 files changed, 25 insertions(+), 4 deletions(-) create mode 100644 app/cli.py diff --git a/app/cli.py b/app/cli.py new file mode 100644 index 00000000..45fa7160 --- /dev/null +++ b/app/cli.py @@ -0,0 +1,22 @@ +from collections.abc import Sequence + +from app.history import History, LookupRecord +from app.settings import Settings +from app.weather import WeatherAdapter + + +def main(argv: Sequence[str]) -> None: + settings = Settings.from_env() + adapter = WeatherAdapter(settings.geocoding_base, settings.forecast_base) + history = History(settings.database_url) + city = argv[0] + conditions = adapter.forecast(adapter.geocode(city)) + history.record( + LookupRecord( + city=city, + temperature=conditions.temperature, + wind_speed=conditions.wind_speed, + weather_code=conditions.weather_code, + ) + ) + print(f"{city} {conditions.temperature}") diff --git a/tests/e2e/cli_test.py b/tests/e2e/cli_test.py index 721bf819..392d7d86 100644 --- a/tests/e2e/cli_test.py +++ b/tests/e2e/cli_test.py @@ -1,12 +1,11 @@ from typing import Any -import pytest - CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" -@pytest.mark.pending -def test_cli_prints_current_conditions_for_a_city(capsys: Any, monkeypatch: Any) -> None: +def test_cli_prints_current_conditions_for_a_city( + capsys: Any, monkeypatch: Any +) -> None: import vcr from app.cli import main From 3ba85990912128627350909b1a2e58a4ed68c553 Mon Sep 17 00:00:00 2001 From: nullhack Date: Thu, 2 Jul 2026 13:43:27 -0400 Subject: [PATCH 18/28] feat(template): methodology layer expansion + dogfood revert - Revert dogfood instance from the template root (app/, tests/, docs/glossary.md, cassettes); it lives in /tmp as a separate instance project. - New knowledge: research folder (29 source cards + card template + research-files knowledge), secrets-and-config (12-factor secrets/config split, LLM-agent threat model, dotenv_values over load_dotenv, agent instruct/ask protocol), design-patterns rework (language-agnostic 22-pattern catalog), and the journal/plan->explore escalation wiring (needs-capture exit + cross-phase journal.md). - New templates: glossary, state (living spec), README, research card, ADR, .env.example. - ADR model (docs/decisions/2026-07-02-use-pyi-first-contracts.md) + standalone record-decision skill + system-architect identity carrying the ADR-awareness. - Flow description slim (orientation kernels); input artifacts point at .pyi; skill and knowledge cross-links de-duplicated. - CI: gitleaks secret-scanner job; ruff bug-catcher select (no docstrings, D dropped). - pyproject: de-beehave, consolidated dev deps, requires-python >=3.13, httpx reverted. --- .flowr/flows/pipeline-flow.yaml | 1 + .flowr/flows/plan-flow.yaml | 10 +- .flowr/flows/tdd-flow.yaml | 7 +- .github/workflows/ci.yml | 10 ++ .opencode/agents/system-architect.md | 2 + .../knowledge/methodology/research-files.md | 75 ++++++++++++ .../methodology/separation-of-concerns.md | 5 + .../software-craft/design-patterns.md | 81 ++++++++----- .../software-craft/external-fixtures.md | 6 +- .../software-craft/secrets-and-config.md | 104 +++++++++++++++++ .../software-craft/smell-catalogue.md | 3 +- .../knowledge/software-craft/source-stubs.md | 8 +- .opencode/knowledge/software-craft/tdd.md | 2 + .opencode/skills/author-test-stubs/SKILL.md | 14 ++- .opencode/skills/confirm-red-failure/SKILL.md | 5 +- .opencode/skills/derive-source-stubs/SKILL.md | 12 +- .opencode/skills/implement-from-stub/SKILL.md | 2 +- .opencode/skills/merge-to-dev/SKILL.md | 2 +- .opencode/skills/record-cassette/SKILL.md | 2 +- .opencode/skills/record-decision/SKILL.md | 14 +++ .opencode/skills/refactor-green/SKILL.md | 2 +- .opencode/skills/research-provider/SKILL.md | 2 +- .../skills/review-implementation/SKILL.md | 3 +- .opencode/skills/ship-unit/SKILL.md | 2 +- .opencode/skills/simulate-contracts/SKILL.md | 2 + .opencode/skills/write-probe/SKILL.md | 2 +- .opencode/skills/write-test-py/SKILL.md | 14 ++- .templates/.env.example.template | 20 ++++ .templates/README.md.template | 45 ++++++++ .../YYYY-MM-DD-.md.template | 60 ++++++++++ .templates/docs/research/card.md.template | 41 +++++++ .templates/docs/state.md.template | 65 +++++++++++ AGENTS.md | 3 +- README.md | 107 ++++++++++++++++++ TODO.md | 17 ++- app/__init__.pyi | 0 app/cli.py | 22 ---- app/cli.pyi | 4 - app/history.py | 45 -------- app/history.pyi | 15 --- app/settings.py | 22 ---- app/settings.pyi | 12 -- app/weather.py | 51 --------- app/weather.pyi | 20 ---- .../2026-07-02-use-pyi-first-contracts.md | 99 ++++++++++++++++ docs/glossary.md | 42 ------- docs/research/README.md | 36 ++++++ .../documentation/procida_2021.md | 38 +++++++ .../domain-modeling/brandolini_2012.md | 38 +++++++ .../domain-modeling/evans_2003.md | 38 +++++++ .../domain-modeling/vernon_2013.md | 38 +++++++ .../cognitive/fisher_geiselman_1987.md | 40 +++++++ .../psychology/cognitive/flanagan_1954.md | 40 +++++++ .../cognitive/hattie_timperley_2007.md | 41 +++++++ .../cognitive/reynolds_gutman_1988.md | 40 +++++++ .../cognitive/tversky_kahneman_1974.md | 39 +++++++ .../psychology/social/rogers_farson_1957.md | 40 +++++++ .../psychology/social/tetlock_1985.md | 38 +++++++ .../process/fagan_1976.md | 38 +++++++ .../process/gotel_cleland_huang_2012.md | 37 ++++++ .../jeffries_anderson_hendrickson_2000.md | 42 +++++++ .../process/niessen_2026.md | 30 +++++ .../process/wiggins_2011.md | 29 +++++ .../software-engineering/quality/bay_2008.md | 39 +++++++ .../software-engineering/quality/beck_2002.md | 41 +++++++ .../quality/env_dev_2026.md | 33 ++++++ .../quality/fowler_1999.md | 39 +++++++ .../quality/fowler_2006.md | 37 ++++++ .../quality/fowler_2014.md | 38 +++++++ .../quality/gamma_et_al_1994.md | 39 +++++++ .../quality/heigh_2023.md | 30 +++++ .../quality/maciver_2016.md | 40 +++++++ .../quality/martin_2000_solid.md | 40 +++++++ .../quality/meszaros_2007.md | 39 +++++++ .../quality/moskvin_2025.md | 38 +++++++ .../quality/north_2006.md | 39 +++++++ .../quality/python-dotenv_theskumar.md | 30 +++++ .../quality/shvets_2014.md | 39 +++++++ .../quality/turmyshev_2026.md | 37 ++++++ .../quality/young_gao_2026.md | 31 +++++ .../requirements/patton_2014.md | 38 +++++++ pyproject.toml | 7 +- tests/cassettes/open-meteo/open-meteo.yaml | 80 ------------- tests/e2e/cli_test.py | 22 ---- tests/e2e/cli_test.pyi | 6 - tests/integration/history_test.py | 39 ------- tests/integration/history_test.pyi | 10 -- tests/integration/settings_test.py | 29 ----- tests/integration/settings_test.pyi | 7 -- tests/integration/weather_test.py | 42 ------- tests/integration/weather_test.pyi | 12 -- uv.lock | 55 +++++++++ 92 files changed, 2144 insertions(+), 556 deletions(-) create mode 100644 .opencode/knowledge/methodology/research-files.md create mode 100644 .opencode/knowledge/software-craft/secrets-and-config.md create mode 100644 .opencode/skills/record-decision/SKILL.md create mode 100644 .templates/.env.example.template create mode 100644 .templates/README.md.template create mode 100644 .templates/docs/decisions/YYYY-MM-DD-.md.template create mode 100644 .templates/docs/research/card.md.template create mode 100644 .templates/docs/state.md.template create mode 100644 README.md delete mode 100644 app/__init__.pyi delete mode 100644 app/cli.py delete mode 100644 app/cli.pyi delete mode 100644 app/history.py delete mode 100644 app/history.pyi delete mode 100644 app/settings.py delete mode 100644 app/settings.pyi delete mode 100644 app/weather.py delete mode 100644 app/weather.pyi create mode 100644 docs/decisions/2026-07-02-use-pyi-first-contracts.md delete mode 100644 docs/glossary.md create mode 100644 docs/research/README.md create mode 100644 docs/research/information-science/documentation/procida_2021.md create mode 100644 docs/research/information-science/domain-modeling/brandolini_2012.md create mode 100644 docs/research/information-science/domain-modeling/evans_2003.md create mode 100644 docs/research/information-science/domain-modeling/vernon_2013.md create mode 100644 docs/research/psychology/cognitive/fisher_geiselman_1987.md create mode 100644 docs/research/psychology/cognitive/flanagan_1954.md create mode 100644 docs/research/psychology/cognitive/hattie_timperley_2007.md create mode 100644 docs/research/psychology/cognitive/reynolds_gutman_1988.md create mode 100644 docs/research/psychology/cognitive/tversky_kahneman_1974.md create mode 100644 docs/research/psychology/social/rogers_farson_1957.md create mode 100644 docs/research/psychology/social/tetlock_1985.md create mode 100644 docs/research/software-engineering/process/fagan_1976.md create mode 100644 docs/research/software-engineering/process/gotel_cleland_huang_2012.md create mode 100644 docs/research/software-engineering/process/jeffries_anderson_hendrickson_2000.md create mode 100644 docs/research/software-engineering/process/niessen_2026.md create mode 100644 docs/research/software-engineering/process/wiggins_2011.md create mode 100644 docs/research/software-engineering/quality/bay_2008.md create mode 100644 docs/research/software-engineering/quality/beck_2002.md create mode 100644 docs/research/software-engineering/quality/env_dev_2026.md create mode 100644 docs/research/software-engineering/quality/fowler_1999.md create mode 100644 docs/research/software-engineering/quality/fowler_2006.md create mode 100644 docs/research/software-engineering/quality/fowler_2014.md create mode 100644 docs/research/software-engineering/quality/gamma_et_al_1994.md create mode 100644 docs/research/software-engineering/quality/heigh_2023.md create mode 100644 docs/research/software-engineering/quality/maciver_2016.md create mode 100644 docs/research/software-engineering/quality/martin_2000_solid.md create mode 100644 docs/research/software-engineering/quality/meszaros_2007.md create mode 100644 docs/research/software-engineering/quality/moskvin_2025.md create mode 100644 docs/research/software-engineering/quality/north_2006.md create mode 100644 docs/research/software-engineering/quality/python-dotenv_theskumar.md create mode 100644 docs/research/software-engineering/quality/shvets_2014.md create mode 100644 docs/research/software-engineering/quality/turmyshev_2026.md create mode 100644 docs/research/software-engineering/quality/young_gao_2026.md create mode 100644 docs/research/software-engineering/requirements/patton_2014.md delete mode 100644 tests/cassettes/open-meteo/open-meteo.yaml delete mode 100644 tests/e2e/cli_test.py delete mode 100644 tests/e2e/cli_test.pyi delete mode 100644 tests/integration/history_test.py delete mode 100644 tests/integration/history_test.pyi delete mode 100644 tests/integration/settings_test.py delete mode 100644 tests/integration/settings_test.pyi delete mode 100644 tests/integration/weather_test.py delete mode 100644 tests/integration/weather_test.pyi diff --git a/.flowr/flows/pipeline-flow.yaml b/.flowr/flows/pipeline-flow.yaml index 5ef7bfcd..df76ff75 100644 --- a/.flowr/flows/pipeline-flow.yaml +++ b/.flowr/flows/pipeline-flow.yaml @@ -37,6 +37,7 @@ states: flow-version: "^1" next: contracts-ready: build + needs-capture: explore needs-elicitation: discover - id: build diff --git a/.flowr/flows/plan-flow.yaml b/.flowr/flows/plan-flow.yaml index 5d2590d8..ca2b3724 100644 --- a/.flowr/flows/plan-flow.yaml +++ b/.flowr/flows/plan-flow.yaml @@ -2,6 +2,7 @@ flow: plan-flow version: 1.5.0 exits: - contracts-ready + - needs-capture - needs-elicitation states: - id: author-test-stubs @@ -18,6 +19,7 @@ states: - "docs/glossary.md" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//journal.md" output artifacts: - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" @@ -66,6 +68,7 @@ states: - "tests/e2e/**/*_test.pyi" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//journal.md" output artifacts: - "tests/integration/**/*_test.py" - "tests/e2e/**/*_test.py" @@ -84,6 +87,7 @@ states: input artifacts: - "tests/integration/**/*_test.py" - "tests/e2e/**/*_test.py" + - ".cache//journal.md" output artifacts: - "/**/*.pyi" next: @@ -105,7 +109,9 @@ states: - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" - "/**/*.pyi" - output artifacts: [] + - ".cache//journal.md" + output artifacts: + - ".cache//journal.md" conditions: accepted: pyright-consistent: "==true" @@ -113,6 +119,7 @@ states: traceability-complete: "==true" layer-order-respected: "==true" test-stubs-consistent: "==true" + lint-clean: "==true" simulation-passed: "==true" next: accepted: @@ -120,4 +127,5 @@ states: when: accepted needs-source-stubs: derive-source-stubs needs-test-bodies: write-test-py + needs-capture: needs-capture needs-elicitation: needs-elicitation diff --git a/.flowr/flows/tdd-flow.yaml b/.flowr/flows/tdd-flow.yaml index c1acaccc..130308c3 100644 --- a/.flowr/flows/tdd-flow.yaml +++ b/.flowr/flows/tdd-flow.yaml @@ -35,7 +35,8 @@ states: - "/**/*.pyi" - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" - output artifacts: [] + output artifacts: + - ".cache//journal.md" conditions: really_red: test-status: red @@ -63,7 +64,6 @@ states: output artifacts: - "/**/*.py" - "migrations/**" - - "tests/cassettes/**" - "tests/fixtures/**" conditions: green: @@ -105,7 +105,8 @@ states: - "/**/*.py" - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" - output artifacts: [] + output artifacts: + - ".cache//journal.md" conditions: approved: impl-matches-contract: "==true" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5fdf5248..ff92bb46 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,6 +23,16 @@ jobs: - run: uv run ruff check . - run: uv run ruff format . --check + secrets: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + validate-flows: runs-on: ubuntu-latest steps: diff --git a/.opencode/agents/system-architect.md b/.opencode/agents/system-architect.md index 8f7ea556..b1bc5b0e 100644 --- a/.opencode/agents/system-architect.md +++ b/.opencode/agents/system-architect.md @@ -19,6 +19,8 @@ You are the System Architect. Your lens is the whole contract surface and the se You alone decide the system's decomposition into modules and layers when no specialist applies. +You record a decision as an ADR when it has genuine trade-offs between multiple viable alternatives **and** cross-cutting impact — reversing it would ripple across contracts — by running `record-decision`; decisions with one obvious choice or only local impact are BAU and are not recorded. + ## What you refuse - You refuse to prescribe layout the contracts have not earned ("we'll need a models/ folder") or to harden structure before the tests justify it. diff --git a/.opencode/knowledge/methodology/research-files.md b/.opencode/knowledge/methodology/research-files.md new file mode 100644 index 00000000..bfb7e298 --- /dev/null +++ b/.opencode/knowledge/methodology/research-files.md @@ -0,0 +1,75 @@ +--- +domain: methodology +tags: [research, citations, accuracy, grounding, reference-library] +last-updated: 2026-07-02 +--- + +# Research Files + +## Key Takeaways + +- A research card is the full citation and the source's load-bearing idea — the reference a knowledge author consults to confirm what an inline `(Author, Year)` citation refers to. +- Cards are human reference only; no flow step or skill loads them. They are consulted during knowledge authoring, and the knowledge files are what the flow loads. +- Verify every field against the source — authorship, year, ISBN, DOI, URL — never author from memory, and never fabricate; an unverified source carries an explicit note until researched. +- Capture the source's mechanism, not a paraphrase of it — the machinery a reader applies to decide whether the citation supports the claim. +- The `Key Insight` and `Relevance` fields are what make an inline citation auditable — the insight is the load-bearing idea, the relevance names the knowledge file the citation grounds. +- One card per source under `docs/research/`, grouped by source discipline; the skeleton is `.templates/docs/research/card.md.template`. + +## Concepts + +**A reference library, not a second knowledge layer.** A card holds the bibliographic fact and the source's central contribution at a glance — the thing a knowledge author needs when they meet `(Author, Year)` in a file and ask "which book, and what does it actually say?". It is not a second statement of the knowledge; the knowledge file carries the claim, the card carries the source. + +**Human reference only.** Cards sit under `docs/research/` outside the `.opencode/` graph; no flow state names them as an artifact, no skill loads them, no wikilink resolves to them. They are read by a human (or an authoring agent) during the grounding step of writing knowledge — the step [[methodology/knowledge-files#grounding-and-research]] already names — and never during the build lifecycle. + +**Verify, never recall.** Authorship, ISBNs, DOIs, and exact titles drift in recall; a card authored from memory is a plausible error waiting to mislead, and arc42 (Starke) states the stakes plainly — wrong reference material is often worse than none, because it misleads with confidence. Every field is checked against the source's publisher page, the canonical site, or a neutral reference (Wikipedia) before the card is committed. A source whose provenance cannot be confirmed carries an explicit "URL unverified" note rather than an invented detail; the note is debt to clear, not a licence to fabricate. + +**Mechanism over paraphrase.** A card that restates the source's title in different words teaches nothing; the `Mechanism` field carries how the idea actually works — the machinery a reader needs to recognise an instance and separate the citation from its neighbours. This is the same depth contract Knowledge Files sets between its Concepts and Content tiers: the deepest layer carries the source's actual mechanism, and a layer that only paraphrases has failed. + +**Auditable citations.** An inline `(Author, Year)` in a knowledge file is a promise that the source supports the claim. The card's `Key Insight` states the load-bearing idea in one sentence, and `Relevance` names the knowledge file(s) the citation grounds — together they let a reader trace a claim from knowledge to source without re-reading the source. A citation whose card's `Key Insight` does not support the claim is a defect to fix in the knowledge, not the card. + +**One card per source, by discipline.** A source appears once, under the sub-domain that matches its discipline (`psychology/`, `software-engineering/`, `information-science/`), and every knowledge file that cites it links to the same card by author-year. The card is the single home of the source's bibliographic fact; copying that fact into each citing knowledge file would build the drift the methodology already forbids. + +## Content + +### The card is a reference, not knowledge + +The `.opencode/knowledge/` graph carries the claims a build depends on; the `docs/research/` library carries the sources behind those claims. The split keeps the load surface (what an agent ingests mid-build) small while letting a human author dig deeper when grounding a claim. A card never restates the knowledge — it records the source so the knowledge's citation can be verified. This mirrors Diátaxis's separation of reference from explanation (Procida): the card is consulted, not read, and a reader lands on it to confirm a fact and leaves. + +### Why nothing in the flow loads a card + +A flow state's `input artifacts` and `output artifacts` point at the build's working files; a skill's `Load` step resolves wikilinks under `.opencode/knowledge/` only. Cards live outside both — under `docs/research/`, addressed by filesystem path, not wikilink — so the build lifecycle is indifferent to them. The README at `docs/research/README.md` says as much: the folder is for human reference, consulted during knowledge authoring for author-year lookups. Grounding is an authoring-time activity, not a build-time one. + +### Verify every field — the failure mode is recall, not malice + +The load-bearing lesson of this project's research folder: authorship and bibliographic data authored from memory were wrong in three of seven fresh-captured cards, even when the source itself was real and well-known. A card for *Extreme Programming Installed* named Kent Beck as an author — he wrote the foreword; the authors are Ron Jeffries, Ann Anderson, and Chet Hendrickson. A card for *User Story Mapping* carried a fabricated ISBN. A card for *Software and Systems Traceability* omitted a third editor. The ISBNs and the Beck authorship would have propagated into every knowledge file that cited them. The rule that follows is absolute: a card's authorship, year, title, ISBN, DOI, and URL are checked against the source's publisher page, its Wikipedia entry, or the canonical site before commit, every time, regardless of how well-known the source seems. A web article is fetched in full and its key claim quoted; a book's title, authors, ISBN, and page count are confirmed against the publisher or Wikipedia. + +### No fabrication — unverified is a note, not a guess + +When a source is cited in knowledge but its exact provenance cannot be confirmed at capture time, the card carries an explicit `URL: unverified` (or equivalent) note in its Citation section and a `Confidence: Low` line that says why. The note is tracked as debt to clear by a later research pass. What never happens is inventing an ISBN, a URL, a page count, or a co-author to make the card look complete. arc42's warning runs both ways: a missing field a reader knows to verify is honest debt; a confident wrong field is silent corruption. The two unverified-then-confirmed web articles in this folder (Moskvin 2025, Turmyshev 2026) passed through the note-carrying state before their URLs were researched and their cards rewritten from the actual articles. + +### Capture the mechanism + +The `Mechanism` field is where the card earns its depth. A paraphrase of the title — "this book is about refactoring" — leaves a reader unable to tell whether the citation supports a specific claim about extract method versus one about code smells. The field carries the source's actual machinery: for Moskvin 2025, that vcrpy records verbatim and does not scrub, that the generic Presidio-based scrubber is over-engineered at 670 MB, and that the author lands on JSON-Pointer field redaction via `before_record_response`; for Turmyshev 2026, that external is defined as "any dependency that introduces network latency, rate limits, or data you don't control" and that internal services and repositories are never stubbed. A reader of the card can then decide whether the citation supports the claim the knowledge makes. + +### Auditable inline citations + +An inline `(Author, Year)` in a knowledge file resolves to exactly one card. The card's `Key Insight` carries the one-sentence load-bearing idea, and `Relevance` names the knowledge file(s) — and, ideally, the claim — the citation grounds. A reader checking a claim follows the citation string to the card, reads the Key Insight, and either confirms the claim is supported or finds a defect. The defect is fixed where it lives: if the citation does not support the claim, the knowledge file's claim or citation changes, not the card. This is what keeps the knowledge graph honest as it grows — every `(Author, Year)` has a single auditable home. + +### Location, taxonomy, and the template + +Cards live under `docs/research/` in a taxonomy that mirrors source disciplines, with only the sub-domains that hold cited sources kept: + +``` +docs/research/ + psychology/{social,cognitive}/ + software-engineering/{quality,process,requirements}/ + information-science/{domain-modeling,documentation}/ + README.md +``` + +A new card is copied from `.templates/docs/research/card.md.template` (the `.templates/` → destination convention: strip the `.templates/` prefix and `.template` suffix), placed under the matching discipline, and named `_.md` (lowercase, underscore-separated, matching the folder's existing files). Multiple authors use the form `firstauthor_secondauthor_year`. The eight sections — Citation, Method, Confidence, Key Insight, Core Findings, Mechanism, Relevance, Related Research — are the card's fixed shape; the template carries the skeleton and the verify-never-recall reminder. + +## Related + +- [[methodology/knowledge-files]] +- [[methodology/separation-of-concerns]] diff --git a/.opencode/knowledge/methodology/separation-of-concerns.md b/.opencode/knowledge/methodology/separation-of-concerns.md index fdf45049..0c31c757 100644 --- a/.opencode/knowledge/methodology/separation-of-concerns.md +++ b/.opencode/knowledge/methodology/separation-of-concerns.md @@ -13,6 +13,7 @@ last-updated: 2026-07-01 - The flow YAML is the spine — it binds a state to its owner, procedure, artifacts, branch, gate, and exits; the other three files carry none of those. - The orchestrator routes; agents, skills, and knowledge are loaded on demand, never the whole layer at once. - A state's `description` orients — one or two lines on what the state is for; the step-by-step procedure, criteria lists, and technique live in the skill. When a `description` and a skill disagree on procedure, the skill wins. +- An escalation handoff rides a per-session journal: the discovering state appends its finding, the receiver reads it on re-entry, and the re-dispatch prompt carries it live. The tests and cassettes stay the spec; the journal is only the safety net against lost context mid-escalation. ## Concepts @@ -60,6 +61,10 @@ Do not duplicate any of these outside the flow YAML. A gate `conditions` key (e.g. `stubtest-clean=true`) is EVIDENCE the dispatched agent asserts; flowr does not execute the check. The enforcement backstop is CI, which runs `ruff` (with `PYI`), `pyright`, `mypy.stubtest`, and `pytest` on every push and fails the build on any drift or violation — verifying what the agent asserted. The flow's job is to name the gate and collect honest evidence; CI's job is to prove it. +### Escalation handoffs + +When a state exits on `reveals-gap` / `needs-capture` / `needs-elicitation`, its finding must reach the phase it re-enters. The finding rides two carriers: the discovering state **appends** it to `.cache//journal.md` (its `output artifacts`), and the re-dispatch prompt carries it verbatim. The receiving state **reads** `journal.md` on entry (its `input artifacts`) and re-derives the detail from the artifacts — the tests, source stubs, and cassettes that *are* the spec. The journal is a transient per-session safety net against context lost mid-escalation (e.g. a compress between the discovering state and re-entry); it is not a second spec and never duplicates what the tests express. One stable file absorbs every escalation — present and future — so new edges never spawn new artifact types. + ### Loading model The orchestrator reads the flow once per state and dispatches; it does not load the methodology layer up front. An agent loads when its role is dispatched; a skill loads when the state's `skills` names it; knowledge loads when a wikilink resolves. No session pays for the whole layer. diff --git a/.opencode/knowledge/software-craft/design-patterns.md b/.opencode/knowledge/software-craft/design-patterns.md index d1829026..29355366 100644 --- a/.opencode/knowledge/software-craft/design-patterns.md +++ b/.opencode/knowledge/software-craft/design-patterns.md @@ -1,7 +1,7 @@ --- domain: software-craft tags: [design-patterns, gof, oop, refactor, architecture] -last-updated: 2026-07-01 +last-updated: 2026-07-02 --- # Design Patterns @@ -9,50 +9,69 @@ last-updated: 2026-07-01 ## Key Takeaways - Patterns are applied **only when a smell triggers them**, never speculatively — the smell points at the gap, the pattern supplies the structure (Gamma et al., 1994; Shvets, 2014). -- The patterns this workflow's architecture actually hosts are few and recur: **Adapter** at each external boundary, **Repository** for persistence, **Facade** / application service at the entry point, **Strategy / State** for variant behaviour, **Factory** for construction that must not be scattered. -- **Creational** smells (the same object built in several places, telescoping setup) trigger Factory Method or Builder. -- **Structural** smells (branching on a type field, feature envy, parallel hierarchies) trigger Strategy, Adapter, Move Method, or Bridge. -- **Behavioural** smells (one class's state field sprouting conditionals, fan-out notification, two functions sharing a skeleton) trigger State, Observer, or Template Method. -- The core heuristic: if adding a variant means editing existing functions, that is the smell a pattern removes — the code should be open for extension and closed for modification (OCP). +- The GoF sort the patterns into three families by what they structure: **creational** (how objects are built), **structural** (how types are wired together), **behavioural** (how responsibility is distributed). +- The single thread through selection is the **Open-Closed Principle**: a place in the code edited every time the domain grows is the defect a pattern removes, turning modification into extension. +- **Prefer the simplest structure that removes the smell.** A pattern is one option alongside the smaller refactoring moves, not a default — reach for it when the simpler move (Extract Method, Move Field, a parameter object) cannot carry the weight (KISS, YAGNI). +- Patterns are **language-neutral structures**; the idiom that realises them is the host language's choice (a function reference, a generic, a trait). The pattern names the relationship; the language supplies the syntax. ## Concepts -**Applied when triggered, not collected.** A pattern is a structural fix for a recurring problem, and the problem announces itself as a smell (Gamma et al., 1994; Shvets, 2014). Applying a pattern without the smell is Speculative Generality — an abstraction bought against a future that never arrives — which the smell catalogue rejects on sight. The discipline is to let the smell name the gap and the pattern fill it, never to fit the code to a pattern because the pattern is familiar. +**Applied when triggered, not collected.** A pattern is a named structural fix for a recurring problem, and the problem announces itself as a smell (Gamma et al., 1994; Shvets, 2014). Applying a pattern without the smell is Speculative Generality — an abstraction bought against a future that never arrives, which the smell catalogue rejects on sight. The discipline is to let the smell name the gap and the pattern fill it, never to fit the code to a pattern because the pattern is familiar. -**A small, recurring set.** This workflow's outside-in layering produces a handful of patterns repeatedly. An external service attaches behind an **Adapter** that presents the boundary as a protocol the domain understands; persistence sits behind a **Repository** that loads and stores aggregates; the entry point (a CLI, a request handler) is a thin **Facade** or application service composing the pieces; variant behaviour is **Strategy** or **State**, not a type field with a switch; construction that several callers share is a **Factory**. Most contracts need none of these; when one does, the smell makes it obvious which. +**Three families.** Creational patterns address *how objects are built* — scattered construction, telescoping setup — and yield Factory, Builder, Prototype. Structural patterns address *how types are wired* — a switch on a kind, parallel hierarchies, an incompatible interface — and yield Strategy, Adapter, Bridge, Composite, Facade. Behavioural patterns address *how responsibility flows* — a state machine outgrowing its class, a change fanning out to listeners, two algorithms sharing a skeleton — and yield State, Observer, Template Method, Visitor. The family is read off the smell, not chosen in advance. -**Creational, structural, behavioural.** The GoF categories still sort the triggers. Creational smells cluster around *how objects are built* — scattered `__init__` calls, telescoping constructors — and yield Factory or Builder. Structural smells cluster around *how types are wired* — a switch on a kind, a method that envies its neighbour, two hierarchies growing in lockstep — and yield Strategy, Adapter, Move Method, or Bridge. Behavioural smells cluster around *how responsibility is distributed* — a state machine outgrowing its class, a change fanning out to many listeners, two algorithms sharing a skeleton — and yield State, Observer, or Template Method. +**Open for extension, closed for modification.** Procedural code is open to modification: every new variant edits an existing branch. The pattern closes that branch and opens it to extension instead — a new variant arrives as a new type fitting an existing interface. This is the OCP heartbeat: a site that must be re-edited on every domain change is the precise defect the pattern removes. -**Open for extension, closed for modification.** The single thread through pattern selection is the Open-Closed Principle: a place in the code that must be edited every time the domain grows is a defect, and the pattern that removes it is the one that lets a new variant arrive as a new type fitting an existing interface. Procedural code is open to modification; the pattern closes it and opens it to extension instead. +**Simplest structure that removes the smell.** A pattern is not the first move; it is the move that remains after Extract Method, Move Field, or a parameter object have proven insufficient. Reaching for Abstract Factory where a function would do, or Builder where two arguments would suffice, imports structure the smell did not justify. The rule is KISS and YAGNI applied to structure itself: the lightest fix that dissolves the smell is the right one, and a pattern earns its weight only when the lighter moves cannot carry it. -## Content +**Language-neutral; idiom is local.** A Strategy is a polymorphic family whether it is realised by a class hierarchy, a function reference, or a first-class callable; an Adapter is a translation layer whether it wraps by composition or by a language's trait. The pattern names the relationship; the host language supplies the idiomatic syntax. Modern languages fold several GoF patterns into single constructs (a callable replaces Command and Strategy; a generator replaces Iterator; a protocol/interface replaces Adapter scaffolding) — the pattern is still present where the relationship is, just without ceremony. -### Smell → pattern lookup +## Content -| Smell | Pattern | -|---|---| -| same object constructed in 3+ places | Factory Method | -| multi-step setup before an object is valid | Builder | -| `if/elif` branching on a type/kind/status field | Strategy (behaviour varies) or State (transitions) | -| a method uses another class's data more than its own | Move Method | -| two hierarchies growing in lockstep | Bridge | -| one state field sprouting conditionals across methods | State | -| a change fans out to many listeners directly | Observer | -| two functions share an algorithm skeleton, differ in a step | Template Method | -| an external service with the wrong interface | Adapter | -| a complex subsystem needs one simple entry point | Facade | -| primitive and composite objects must be treated the same | Composite | +### The catalog + +| Pattern | Intent | Triggers (smell) | +|---|---|---| +| **Creational** | | | +| Factory Method | one object creation, deferred to subclasses | same object constructed in 3+ places; construction scattered | +| Abstract Factory | a family of related objects, kept consistent | cross-family construction that must not mix | +| Builder | separate complex construction from its representation | telescoping constructor; multi-step setup before valid | +| Prototype | new objects by copying a prototype | expensive or duplicated construction; state-only differences | +| Singleton | one instance, global access | shared state accessed widely *(use with caution — often a coupling smell)* | +| **Structural** | | | +| Adapter | make an incompatible interface usable | an external service with the wrong interface | +| Bridge | split abstraction from implementation; vary both | parallel inheritance hierarchies | +| Composite | treat individuals and compositions uniformly | primitive and composite must be handled the same (trees) | +| Decorator | add behaviour without subclassing | combinatorial explosion of optional behaviours | +| Facade | one simplified entry to a subsystem | a complex subsystem needs one simple front | +| Flyweight | share fine-grained state | vast numbers of near-identical objects | +| Proxy | a placeholder controlling access | lazy load, access control, remote indirection | +| **Behavioural** | | | +| Chain of Responsibility | pass a request along handlers until one handles | a request with an unknown handler; sequential fallback | +| Command | encapsulate a request as an object | queueing, undo, parameterised callbacks | +| Iterator | sequential access without exposing structure | traversal coupled to the collection's representation | +| Mediator | centralise how peers interact | many-to-many coupling between colleagues | +| Memento | capture and restore internal state | rollback / undo of state | +| Observer | notify dependents of state change | a change fans out to many listeners | +| State | change behaviour as internal state changes | one state field sprouting conditionals across methods | +| Strategy | a family of interchangeable algorithms | variant behaviour selected by a flag or switch | +| Template Method | a skeleton with steps deferred to subclasses | two functions share a skeleton, differ in a step | +| Visitor | separate an operation from the structure it runs on | operations accumulating on a stable class set | + +### Patterns at the type surface + +A pattern becomes visible at the **type-definition layer** — the signatures, relationships, and compositions that the contract surface declares — before any behaviour is written. A signature that branches on a kind field (a `type: str` later switched on) is Strategy or State asking to be born; two hierarchies declared in lockstep are Bridge; construction repeated across several entry points is Factory; a type that exposes another's internals to its callers is a Facade waiting to hide the subsystem. The defining step is where these signals are read, because the relationship is the contract: the shape declared there is what every caller will depend on, and reshaping it later costs more than reading it now. A pattern chosen at the type surface is chosen from the smells the relationships themselves emit. ### The patterns this workflow hosts | Pattern | Where it appears in this flow | |---|---| -| Adapter | wraps an external service behind a protocol the domain speaks (the cassettes replay through it) | -| Repository | loads and stores aggregates; hides the persistence mechanism behind a collection-like interface | +| Adapter | wraps an external service behind an interface the domain speaks (cassettes replay through it) | +| Repository | loads and stores aggregates; hides persistence behind a collection-like interface | | Facade / application service | the entry point — a CLI command, a handler — that composes the pieces and owns no domain logic | -| Strategy / State | replaces a type-field switch with a polymorphic hierarchy | +| Strategy / State | replaces a type-field switch with a polymorphic family | | Factory | centralises construction shared by several callers | -| value object | a small, immutable, domain-typed wrapper (OC-3) — `Rate`, `Amount`, not bare `float` | +| value object | a small, immutable, domain-typed wrapper — the domain value, not a bare primitive | A contract that needs none of these is the common case; a contract that needs one announces it through a smell that the review and refactor steps surface. @@ -60,5 +79,5 @@ A contract that needs none of these is the common case; a contract that needs on - [[software-craft/smell-catalogue]] — the smells that trigger pattern selection - [[software-craft/solid]] — OCP, the principle behind "open for extension, closed for modification" -- [[software-craft/refactoring-techniques]] — the smaller moves applied before a pattern is warranted -- [[software-craft/source-stubs]] — the `.pyi` an adapter or repository is implemented to satisfy +- [[software-craft/refactoring-techniques]] — the smaller moves tried before a pattern is warranted +- [[software-craft/source-stubs]] — the type surface where pattern relationships are first declared diff --git a/.opencode/knowledge/software-craft/external-fixtures.md b/.opencode/knowledge/software-craft/external-fixtures.md index 93b6dfd1..23c1df16 100644 --- a/.opencode/knowledge/software-craft/external-fixtures.md +++ b/.opencode/knowledge/software-craft/external-fixtures.md @@ -13,6 +13,7 @@ last-updated: 2026-07-01 - The recorder varies by service kind — vcrpy records HTTP only; databases, queues, and object stores each need their own capture strategy. The kind-dispatch table is the one knob set that changes. - Scrub every cassette twice — for SAFETY (strip credentials, keys, PII) and for DETERMINISM (strip volatile values that churn run-to-run, so replay is stable). vcrpy will not scrub for you (Moskvin, 2025). - The capture is the truth: never hand-edit a cassette to make a test pass — fix the code, or re-record when reality has genuinely shifted. +- The recorded request binds the implementation: vcrpy matches `method/scheme/host/port/path/query` by default, so every query parameter the probe sent becomes contract — capture the exact request shape in external-contracts.md and reproduce it. ## Concepts @@ -34,7 +35,9 @@ The developer who writes a fixture from memory writes what they remember, and me ### Capture once, replay forever -The model is record-once-replay-forever. vcrpy's default `record_mode="once"` records when the cassette is absent and replays when it is present; CI overrides to `record_mode="none"` so the build fails on a missing or unmatched cassette rather than silently re-recording (vcrpy, 8.0). The cassette is committed at `tests/cassettes//` and is the authoritative external contract: the adapter test in build replays it, and the adapter implementation is what makes a real call matching the recorded request. The recording is done by a throwaway probe script under `.cache/explore//` (gitignored, never imported by the package or the tests) that runs once with real 12-factor credentials (an environment variable, sourced locally from a gitignored `.env`), and the cassette it leaves behind is what everyone after consumes. Credentials live in the environment and the probe, never in the cassette — the scrub step exists to guarantee that. +The model is record-once-replay-forever. vcrpy's default `record_mode="once"` records when the cassette is absent and replays when it is present; CI overrides to `record_mode="none"` so the build fails on a missing or unmatched cassette rather than silently re-recording (vcrpy, 8.0). The cassette is committed at `tests/cassettes//` and is the authoritative external contract: the adapter test in build replays it, and the adapter implementation is what makes a real call matching the recorded request. The recording is done by a throwaway probe script under `.cache/explore//` (gitignored, never imported by the package or the tests) that runs once with real credentials the user supplies in `~/.secrets/.env` per [[software-craft/secrets-and-config]] (loaded with `dotenv_values()`, never into `os.environ`), and the cassette it leaves behind is what everyone after consumes. Credentials live in the environment and the probe, never in the cassette — the scrub step exists to guarantee that. + +vcrpy matches a recorded request field-for-field on `method/scheme/host/port/path/query` by default (vcrpy, 8.0), and `query` is in that set — so an incidental parameter the probe sent (an API default like `format=json`, a locale like `language=en`) becomes contract the implementation must reproduce, or replay fails on a no-match. This is why the exact request shape is captured into `external-contracts.md` at record time, and why the build-time adapter conforms to the cassette rather than the reverse: the cassette is the authority both the adapter test and the e2e replay, so a request the implementation invents that the probe never sent will not match. A service with several endpoints records ONE cassette holding every interaction, not one cassette per endpoint, so an e2e that chains several calls (geocode then forecast; lookup then detail) replays from a single `vcr.use_cassette`. ### The recorder varies by kind @@ -64,3 +67,4 @@ A cassette records what the service actually did. If the adapter test fails agai - [[software-craft/test-design]] — the adapter test that replays a cassette and asserts against the captured shapes - [[software-craft/source-stubs]] — the adapter implementation, authored from its stub to match the recorded request and honour the captured response +- [[software-craft/secrets-and-config]] — the credentials the probe runs with live out-of-workspace; the scrub here is the commit guard, the lifecycle guard lives there diff --git a/.opencode/knowledge/software-craft/secrets-and-config.md b/.opencode/knowledge/software-craft/secrets-and-config.md new file mode 100644 index 00000000..4a5c81e0 --- /dev/null +++ b/.opencode/knowledge/software-craft/secrets-and-config.md @@ -0,0 +1,104 @@ +--- +domain: software-craft +tags: [secrets, config, 12-factor, dotenv, credentials, llm-agent-security] +last-updated: 2026-07-02 +--- + +# Secrets and Configuration + +## Key Takeaways + +- **Config is not secrets.** Twelve-factor env vars (Wiggins, 2011) are the right home for ordinary configuration — base URLs, feature flags, regions. Secrets (API keys, tokens, passwords) carry a different risk and need different handling: readable by any process under the user, leaked into `/proc//environ`, crash dumps, and child processes, leaving no audit trail and no rotation without a redeploy (Heigh, 2023; Niessen, 2026). +- **The LLM agent is the threat surface this workflow adds.** An agent with Bash and Read tools that authors the probe and the adapter can read a workspace file, run `env` / `printenv`, introspect `os.environ`, read `/proc//environ`, or `print()` a credential in code it writes — and anything it reads lands in the session transcript. Instruction alone does not bind it (a fetched page can prompt-inject past it). The defense is layered attack-surface reduction, not a guarantee. +- **Secrets live outside the workspace** at `~/.secrets/.env`, never in the repo tree. opencode's `external_directory` permission set to `ask` on `~/.secrets/**` turns a silent read into a user prompt; the in-process `dotenv_values()` load the agent's own code performs does not trigger it (subprocess file I/O is not intercepted), so the legitimate path runs clean and only direct snooping is gated. +- **Read secrets with `dotenv_values()`, never `load_dotenv()`.** `load_dotenv()` mutates `os.environ` — the surface `env`, `printenv`, and `/proc` expose; `dotenv_values()` returns a dict and leaves the process environment untouched, feeding a frozen typed Settings directly and keeping secrets scoped to one object, never the global env (python-dotenv, theskumar). +- **The agent never creates, reads, or debugs a secret.** It instructs the user how to obtain and place each credential (provider, scope, the exact `~/.secrets/.env` line), and on an auth failure it stops and asks with concrete suggestions instead of investigating the value. This applies to secrets only; ordinary debugging is unchanged. +- **A committed `.env.example` is the env contract.** It lists every variable name, fills non-secret defaults, and leaves secret lines empty with a pointer to `~/.secrets/`. The cassette scrub ([[software-craft/external-fixtures]]) is the explore-time guard; a gitleaks CI step is the push-time guard. + +## Concepts + +**Config is not secrets.** Twelve-factor (Wiggins, 2011) codified "store config in the environment" — everything that varies between deploys. That holds for ordinary configuration, but the industry has stepped back from treating secrets as just more env vars: a secret in `os.environ` is unencrypted, readable by every process under the same user, visible in `/proc//environ`, captured by crash dumps and error trackers, inherited by every child process, and impossible to audit or rotate without a redeploy (Heigh, 2023; env.dev, 2026; Niessen, 2026). The fix is not to abandon twelve-factor but to split it: non-secret config stays in the workspace `.env`; secrets take a harder path. + +**The LLM agent is the threat surface this workflow adds.** A human developer who mishandles a secret is a known problem with known defenses. This workflow adds a new actor: an LLM agent with Bash and Read tools that authors the probe script and the adapter implementation. Such an agent can `Read` a workspace file, `cat` a path, run `env` or `printenv`, execute `python -c "import os; print(os.environ)"`, read `/proc/self/environ`, or `print()` a credential in code it writes — and anything it reads lands in the transcript. Instruction ("do not print secrets") is a soft guard. The defense is layered surface reduction, and the honest caveat is that it is not a guarantee. + +**Secrets live outside the workspace.** Placing the secrets file at `~/.secrets/.env` — outside the repo tree — does three things at once: it cannot be committed accidentally (a path outside the repo is never staged); it sits outside the directory the agent normally enumerates; and it falls under opencode's `external_directory` permission, which an instance configures to `ask` on `~/.secrets/**`. The mechanical gate is the point: a direct `Read` or `bash: cat` of that path triggers a user prompt, while the legitimate `dotenv_values()` call inside the probe subprocess does not, so the probe runs clean and only direct snooping is gated. + +**Read secrets with `dotenv_values()`, never `load_dotenv()`.** python-dotenv exposes two loaders (python-dotenv, theskumar). `load_dotenv()` parses the file and sets each value into `os.environ` — the exact surface that `env`, `printenv`, and `/proc//environ` expose. `dotenv_values()` parses the same file and returns a dict without touching the environment. The two-file pattern composes them: `load_dotenv()` for the workspace `.env` (non-secret; `os.environ` exposure is acceptable) and `dotenv_values("~/.secrets/.env")` for secrets, the result handed straight to a frozen Settings and never to `os.environ`. This is the single most effective mechanical change: even an agent that runs `env` sees nothing. + +**The agent never creates, reads, or debugs a secret.** Because the agent cannot be fully bound by instruction, the procedural rule removes both the temptation and the need: the agent names each secret variable and tells the user how to obtain and place it (which provider, what scope, the exact line in `~/.secrets/.env`); it never generates a credential, never writes a secrets file, never reads one to "check." When a probe or an auth-dependent test fails on credentials, the agent does not investigate the secret — it stops and asks, with concrete suggestions (the key may be wrong, expired, scoped too narrowly, or the variable may be unset). This applies to secrets only; ordinary connectivity or shape debugging is unchanged. + +**Defense in depth, not a guarantee.** No single layer suffices. The layered set — out-of-workspace location, permission gate, `dotenv_values()` over `load_dotenv()`, frozen typed Settings, reference-by-name in code, cassette scrub at explore ([[software-craft/external-fixtures]]), and a gitleaks scanner at push — shrinks the surface at every stage. Process introspection (`env`, `/proc`) is the residual vector if a secret ever does reach `os.environ`; `dotenv_values()` is what keeps it from reaching there. + +## Content + +### Config is not secrets: the split and the maturity ladder + +Non-secret configuration belongs in the workspace `.env`, gitignored, loaded with `load_dotenv()` so ordinary code can read it through `os.environ` or a typed Settings. The maturity ladder for the harder case — secrets — runs from a local `.env` (acceptable for local development only), through encrypted files (SOPS, git-crypt, dotenvx) for version-controlled team sharing, to a dedicated secrets manager (Vault, AWS/GCP/Azure Secrets Manager, Doppler, Infisical) for production (env.dev, 2026; young_gao, 2026). This workflow's concern is the local-development tier the explore and build phases run in: real credentials hit real services once, locally, and the rest is replay. Production secret provisioning is the platform's job, not the pipeline's. + +### Why environment variables leak + +The mechanics are concrete. On Linux every process's environment is exposed at `/proc//environ`, readable by the same user; child processes inherit the full set by default; crash dumps, APM agents, and error trackers routinely capture it; and any command the agent runs (`env`, `printenv`, `python -c "import os; ..."`) reads it (Heigh, 2023; Niessen, 2026). The twelve-factor prescription predates these concerns and was always about separation of config from code, not about secrecy (Niessen, 2026). For sensitive values, a file mounted outside the process environment — or a secrets manager — is the recommended shape, because it does not share these exposure paths (Niessen, 2026). + +### The LLM-agent threat model + +| # | Vector | Example | Primary defense | +|---|---|---|---| +| V1 | Direct file read | `Read .env`, `cat ~/.secrets/x.env` | out-of-workspace location + `external_directory` ask | +| V2 | Code exfil | `print(os.environ["KEY"])` in probe/adapter | `dotenv_values()` (secret never in `os.environ`); reference-by-name; cassette scrub | +| V3 | Process introspection | `env`, `printenv`, `/proc//environ` | `dotenv_values()` (secret never in `os.environ`) | +| V4 | Commit leak | secret in `.env`, cassette, or source → pushed | `.gitignore`; cassette scrub (explore); gitleaks (CI) | +| V5 | Log / error leak | secret in a stack trace or fail message | fail-fast validation; no secret in the message | + +V3 is the residual risk if a secret ever reaches `os.environ`; `dotenv_values()` is the layer that keeps it from reaching there. + +### The layered defense + +| Layer | Closes | How | +|---|---|---| +| Out-of-workspace `~/.secrets/.env` | V1, V4 (file) | outside the repo tree; never staged | +| opencode `external_directory: {"~/.secrets/**": "ask"}` | V1 | direct Read / bash-cat triggers a user prompt | +| `dotenv_values()` for secrets | V2, V3 | secret stays in a scoped dict, never `os.environ` | +| Frozen typed Settings, loaded once, passed explicitly | V2, V5 | one immutable object; no scattered `os.environ` access (young_gao, 2026) | +| Reference-by-name in code | V2 | the agent's code names the variable, never the value | +| Cassette scrub ([[software-craft/external-fixtures]]) | V4 (cassette) | secrets stripped before commit at explore | +| gitleaks in CI | V4 (push) | last-line scan on every push | +| Agent rule: instruct / ask, never create or debug | V2 (debug path) | the agent never needs the value to troubleshoot | + +### The dotenv mechanics: two files, two loaders + +```python +from dataclasses import dataclass +from dotenv import dotenv_values, load_dotenv +import os + +@dataclass(frozen=True) +class Settings: + api_base: str + api_key: str + + @classmethod + def from_env(cls) -> "Settings": + load_dotenv() # workspace .env: non-secret config into os.environ + secrets = dotenv_values(os.path.expanduser("~/.secrets/.env")) + api_base = os.environ.get("API_BASE", "https://default.example.com") + api_key = secrets["API_KEY"] # straight from the dict, never os.environ + if not api_key: + raise RuntimeError("API_KEY unset in ~/.secrets/.env") + return cls(api_base=api_base, api_key=api_key) +``` + +`load_dotenv()` is acceptable for the non-secret workspace file because exposure through `os.environ` is harmless for a base URL. `dotenv_values()` is mandatory for secrets: the value moves file → dict → frozen field, never through the process environment. The fail-fast check produces a message that names the variable and its location, never the value. + +### The agent–secrets protocol + +The rule is procedural and applies to secrets only. **Creating:** when a probe or adapter needs a credential, the agent states what to obtain (provider, scope), the exact line to add to `~/.secrets/.env` (`VAR_NAME=`), and stops — it does not generate a key, does not write the file, does not read it to verify. **Failing:** when a probe run or an auth-dependent test fails on credentials, the agent does not read the secret, does not echo it, does not try alternate values — it stops and asks, with concrete suggestions (the key may be wrong, expired, scoped too narrowly, or the variable unset). The protocol exists because the agent cannot be fully bound by "do not look," so the workflow removes both the need and the opportunity. + +### The committed `.env.example` + +The discoverable contract for "what environment does this project need" is `.env.example`, committed: every variable NAME listed, non-secret defaults filled (`API_BASE=https://default.example.com`), secret lines empty with a pointer (`API_KEY= # obtain from ; place in ~/.secrets/.env`). It carries no value that unlocks anything, so it is safe in version control, and a new contributor reads it once to know the full env shape. + +## Related + +- [[software-craft/external-fixtures]] — the cassette scrub is the explore-time commit guard; this knowledge is the lifecycle guard around it +- [[software-craft/source-stubs]] — the typed Settings is a normal source stub; its `from_env()` is where the two-file load lives +- [[software-craft/test-design]] — auth-dependent tests replay cassettes offline; they never need the live secret at test time diff --git a/.opencode/knowledge/software-craft/smell-catalogue.md b/.opencode/knowledge/software-craft/smell-catalogue.md index 45e42fa7..443c994e 100644 --- a/.opencode/knowledge/software-craft/smell-catalogue.md +++ b/.opencode/knowledge/software-craft/smell-catalogue.md @@ -12,7 +12,7 @@ last-updated: 2026-07-01 - **Object-Oriented Abusers** (Switch Statements, Temporary Field, Refused Bequest, Alternative Classes with Different Interfaces) misapply OOP; reach for polymorphism, Extract Class, or delegation (Fowler, 1999). - **Change Preventers** (Divergent Change, Shotgun Surgery, Parallel Inheritance Hierarchies) make change ripple; restructure along the axis of change or move the data (Fowler, 1999; Shvets, 2014). - **Dispensables** (Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality) are dead weight to delete, inline, or merge — and a Comment is the symptom of code that should have been extracted or renamed instead. -- **Couplers** (Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man) over-couple objects; move the method, hide the delegate, or collapse the middle man (Fowler, 1999; Shvets, 2014). +- **Couplers** (Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man, Incomplete Library Class) over-couple objects; move the method, hide the delegate, collapse the middle man, or extend a class you cannot modify via a foreign method (Fowler, 1999; Shvets, 2014). ## Concepts @@ -73,6 +73,7 @@ last-updated: 2026-07-01 | Inappropriate Intimacy | reaching into another's privates | Move Method/Field; Extract Class; delegation | | Message Chains | `a.b().c().d()` | Hide Delegate; Extract Method | | Middle Man | most methods are one-line forwards | Inline Class; Remove Middle Man | +| Incomplete Library Class | a library class you need to extend but cannot modify | Introduce Foreign Method; Introduce Local Extension | ## Related diff --git a/.opencode/knowledge/software-craft/source-stubs.md b/.opencode/knowledge/software-craft/source-stubs.md index ccf9fc5f..698d7cab 100644 --- a/.opencode/knowledge/software-craft/source-stubs.md +++ b/.opencode/knowledge/software-craft/source-stubs.md @@ -11,7 +11,7 @@ last-updated: 2026-07-01 - A source stub is a PEP 484 `.pyi` **derived from the test bodies** — the inverse of conventional stub authoring. Every type the tests construct, every method they call, every relationship they assert is the specification of the source surface; the stub records exactly that and nothing speculative. - `...` bodies only (PEP 484); never `raise NotImplementedError`. The stub is signature-only and compiles for the type checker with no runtime behaviour — behaviour lands in build's green. - The source `.pyi` is a **fixed contract during build**: green implements the `.py` to satisfy it; refactor cannot edit it; if the body cannot satisfy the `.pyi` without changing it, that is a contract gap escalated at review — never an in-place stub edit. -- **No prescribed layout**, and config is twelve-factor: environment variables plus a gitignored `.env`; a typed Settings model is optional and, if warranted, a normal source stub. External adapters and connectors sit under the package alongside everything else, not as a separate category. +- **No prescribed layout**, and config is twelve-factor with the secrets/config split of [[software-craft/secrets-and-config]] (non-secret workspace `.env`; secrets out-of-workspace via `dotenv_values()`); a typed Settings model is optional and, if warranted, a normal source stub. External adapters and connectors sit under the package alongside everything else, not as a separate category. - Structural artifacts are **keyed on what a module is**: an ORM model carries an Alembic migration (the migration IS the schema spec); an external adapter replays the cassettes captured in explore. - stubtest gates the source pair at green/review/merge — it imports the runtime module (transitive deps must be installed), runs scoped per cycle (the whole-suite run waits until every `.py` exists), and type-only imports go under `TYPE_CHECKING`. The drift mechanics are those of the test pair ([[software-craft/test-stubs]]). @@ -23,7 +23,7 @@ last-updated: 2026-07-01 **Fixed during build.** Once derived, the source `.pyi` is frozen for the whole build cycle: green writes the `.py` to satisfy it, refactor restructures the `.py` while the `.pyi` stays put, and the tests (already written) stay put too. If implementation discovers the `.pyi` is wrong — a missing parameter, a wrong return type, an impossible signature — the response is never to edit the stub in place; it is to escalate a contract gap at review, which routes back to plan for a proper re-derivation. The frozen stub is what keeps the contract the single source of truth. -**No layout, no config artifact.** The tests say where the source lives and what it is called; the stub does not prescribe a package structure on top. Adapters, connectors, and domain types live under the package alongside one another. Configuration is twelve-factor: environment variables are the default, loaded locally from a gitignored `.env`, and a typed Settings model is optional — if it earns its place, it is a normal source stub alongside the rest. +**No layout, no config artifact.** The tests say where the source lives and what it is called; the stub does not prescribe a package structure on top. Adapters, connectors, and domain types live under the package alongside one another. Configuration follows the secrets/config split of [[software-craft/secrets-and-config]] — non-secret config in a workspace `.env`, secrets loaded from out-of-workspace with `dotenv_values()` into a frozen Settings; a Settings model is optional and, if it earns its place, a normal source stub alongside the rest. **Structural artifacts keyed to the module.** Some modules carry an artifact beyond the `.py` pair. An ORM model owns an Alembic migration — the migration is the schema spec, born in green, committed in ship, never edited only appended. An external adapter replays the cassettes captured during explore (`VCR_RECORD_MODE=none`). The stub itself does not generate these; it declares the module's surface, and green emits whatever that surface implies. @@ -65,7 +65,7 @@ The asymmetry is deliberate: the `.pyi` and the tests are the contract, and cont ### No layout, no config artifact -The package takes whatever shape the tests import from. Configuration is twelve-factor — environment variables are the source, a gitignored `.env` carries local secrets, `python-dotenv` loads it. A `Settings` model is optional; if it is worth the code, it is one normal source stub among the rest, reading `os.environ` in its `from_env()`. +The package takes whatever shape the tests import from. Configuration is twelve-factor with the secrets/config split of [[software-craft/secrets-and-config]]: non-secret config in the workspace `.env` loaded with `load_dotenv()`; secrets in `~/.secrets/.env` loaded with `dotenv_values()` — never into `os.environ`. A `Settings` model is optional; if it is worth the code, it is one normal source stub among the rest. ### Structural artifacts keyed to the module @@ -78,7 +78,7 @@ The stub declares the module's surface; green emits whatever that surface implie ### stubtest, scoped -stubtest gates the source pair the same way it gates the test pair; the mechanics — `.pyi`-preferred hides drift from pyright, stubtest imports at runtime via `inspect`, it checks structure not return-type accuracy — are in [[software-craft/test-stubs]]. The source-specific discipline is scoping: `stubtest . tests.` at green/review covers only the modules touched this cycle, because sibling source `.pyi` whose `.py` are not yet built would all false-fail a whole-suite run. The whole-suite `stubtest tests` runs once, at merge, when every `.py` exists. +stubtest gates the source pair the same way it gates the test pair; the mechanics — `.pyi`-preferred hides drift from pyright, stubtest imports at runtime via `inspect`, it checks structure not return-type accuracy — are in [[software-craft/test-stubs]]. The source-specific discipline is scoping: `stubtest . tests.` at green/review covers only the modules touched this cycle, because sibling source `.pyi` whose `.py` are not yet built would all false-fail a whole-suite run. The whole-suite `stubtest tests` runs once, at merge, when every `.py` exists. stubtest checks the public surface declared in the `.pyi`; runtime imports the `.py` uses internally (`os`, `httpx`, sibling modules) need not be mirrored in the stub (validated empirically — a source module importing `httpx` internally, with no `httpx` in its `.pyi`, passed stubtest) — do not over-mirror implementation imports. ## Related diff --git a/.opencode/knowledge/software-craft/tdd.md b/.opencode/knowledge/software-craft/tdd.md index cbfde074..41e541f5 100644 --- a/.opencode/knowledge/software-craft/tdd.md +++ b/.opencode/knowledge/software-craft/tdd.md @@ -46,6 +46,8 @@ The discipline test-first is preserved — the tests still precede the implement | assertion failure against changed tests | rework (source stale) | right reason — re-implement | | `NameError`, fixture resolution, test contradicts its `.pyi` | test or stub defect | reject — escalate, do not patch | +Removing the `@pytest.mark.pending` decorator can orphan its `import pytest` when the test used pytest for nothing else (no `raises`, no `approx`, no parametrize); dropping that now-unused import is part of red — a lint side-effect of un-marking, not a behaviour edit, so it stays within the no-test-editing discipline. + ### Minimum code, YAGNI first - if the test needs only `42`, return `42` — do not invent a configurable constant; diff --git a/.opencode/skills/author-test-stubs/SKILL.md b/.opencode/skills/author-test-stubs/SKILL.md index 83827a6c..b6824a1c 100644 --- a/.opencode/skills/author-test-stubs/SKILL.md +++ b/.opencode/skills/author-test-stubs/SKILL.md @@ -6,9 +6,11 @@ description: "Author test stub files (.pyi) whose signatures express the domain, # Author Test Stubs 1. Load [[software-craft/test-stubs]], [[software-craft/test-design]] — stub conventions and what-to-test patterns. -2. Author integration and E2E test stubs only — no unit-test stubs. Author in build layer order so external-boundary contracts precede adapter, then internal-data, then internal contracts. -3. Express the requirement in class and method signatures with type annotations: entity relationships, compositions, and the behaviour each test asserts. External-layer stubs assert against the captured cassettes — real shapes, not guesses. -4. Make each stub a COMPLETE module surface: declare every module-level name the .py will expose (constants, fixtures, helper functions) plus the test class and its method signatures. The test .pyi must mirror the .py's full module surface per [[software-craft/test-stubs]]. -5. Import stdlib typing only. IF a third-party library is referenced THEN do not import it in the stub — third-party imports trip mypy import-untyped, and stubtest does not require them. -6. IF authoring surfaces an important new domain concept THEN add it to the glossary. -7. IF reworking an existing contract THEN change signatures here first; the body is re-marked at write-test-py. +2. Read `.cache//journal.md` IF present — it carries escalation findings from build (contract gaps). Rework the contracts it names first; skip if absent (first pass). +3. Author integration and E2E test stubs only — no unit-test stubs. Author in build layer order so external-boundary contracts precede adapter, then internal-data, then internal contracts. +4. Express the requirement in class and method signatures with type annotations: entity relationships, compositions, and the behaviour each test asserts. External-layer stubs assert against the captured cassettes — real shapes, not guesses. +5. Make each stub a COMPLETE module surface: declare every module-level name the .py will expose (constants, fixtures, helper functions) plus the test class and its method signatures. The test .pyi must mirror the .py's full module surface per [[software-craft/test-stubs]]. +6. Import stdlib typing only. IF a third-party library is referenced THEN do not import it in the stub — third-party imports trip mypy import-untyped, and stubtest does not require them. +7. Run ruff on the authored .pyi (`ruff check`); the PYI rules lint stubs. Fix every violation. +8. IF authoring surfaces an important new domain concept THEN add it to the glossary. +9. IF reworking an existing contract THEN change signatures here first; the body is re-marked at write-test-py. diff --git a/.opencode/skills/confirm-red-failure/SKILL.md b/.opencode/skills/confirm-red-failure/SKILL.md index 0f5cab01..dc582d3d 100644 --- a/.opencode/skills/confirm-red-failure/SKILL.md +++ b/.opencode/skills/confirm-red-failure/SKILL.md @@ -6,7 +6,8 @@ description: "Confirm the target contract's tests fail for the right reason befo # Confirm Red Failure 1. Load [[software-craft/tdd]] — red/green discipline and the right-reason rule. -2. Remove the pending marker from all the target contract's tests for this cycle — the only test edit allowed in build. Do not author tests; they already exist with full bodies. +2. Remove the pending marker from all the target contract's tests for this cycle. Removing the decorator may orphan `import pytest` when the test used it for nothing else — run ruff and drop the unused import; that is a lint side-effect of un-marking, not a behaviour edit. Do not author tests; they already exist with full bodies. 3. Run the tests. Confirm the failure is ours: IF the source .py is absent and the deferred in-body import raises `ImportError` THEN new work; IF the source .py exists but is stale against the changed contract and an assertion fails THEN rework. Either is the right reason per [[software-craft/tdd]]. 4. IF the red fails for the wrong reason (a typo, a bad fixture, a contract the tests themselves violate) THEN reject it — do not patch the test. -5. Read the target contract's .pyi first, not the whole tree. +5. IF investigation reveals the contract itself is the problem — a referenced cassette is missing, an assertion no correct implementation could satisfy, the spec contradicts itself — THEN append the finding to `.cache//journal.md` (contract, the gap, the evidence) and fire `reveals-gap`. This routes back to plan, not green. +6. Read the target contract's .pyi first, not the whole tree. diff --git a/.opencode/skills/derive-source-stubs/SKILL.md b/.opencode/skills/derive-source-stubs/SKILL.md index 9454198a..b8cb6f16 100644 --- a/.opencode/skills/derive-source-stubs/SKILL.md +++ b/.opencode/skills/derive-source-stubs/SKILL.md @@ -5,8 +5,10 @@ description: "Derive the source stub files (.pyi) from the reviewed tests — ev # Derive Source Stubs -1. Load [[software-craft/source-stubs]] — source stub conventions and the canonical data-shape rule. -2. Read the test .py imports and bodies — every type constructed, method called, and relationship asserted in a body is the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. -3. Do not prescribe layout — no hardcoded module structure. External connector and adapter stubs are not a separate category; they live under the package alongside everything else. -4. Handle config by 12-factor: environment variables are the default, with dotenv loading a gitignored `.env` for local secrets. A typed Settings model is optional and, if warranted, is a normal source stub. -5. IF a value's representation is ambiguous (e.g. a database URL passed as bare string) THEN pin one canonical form once (the `sqlite:///path` URL form) and state it in the stub so every consumer agrees per [[software-craft/source-stubs]]. +1. Load [[software-craft/source-stubs]], [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/design-patterns]] — source stub conventions, the quality principles, and the pattern catalog. +2. Read `.cache//journal.md` IF present — it carries escalation findings from build. Adjust the source stubs of the contracts it names; skip if absent (first pass). +3. Read the test .py imports and bodies — every type constructed, method called, and relationship asserted in a body is the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. +4. Define types, relationships, and compositions to satisfy SOLID and Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a relationship emits a smell at the type surface (a kind-field that will switch, parallel hierarchies, construction scattered across callers, refused bequest) THEN reach for the matching pattern per [[software-craft/design-patterns]] — but KISS/YAGNI first: prefer the simplest structure that removes the smell, and prefer Python idioms (a Protocol, a dataclass, a first-class callable, a generator, a decorator) over GoF ceremony. Do not apply a pattern speculatively; Speculative Generality is the smell that rejects it. +5. Do not prescribe layout — no hardcoded module structure. External connector and adapter stubs are not a separate category; they live under the package alongside everything else. +6. Handle config per [[software-craft/secrets-and-config]]: non-secret config in the workspace `.env`; secrets in `~/.secrets/.env` (out-of-workspace), loaded with `dotenv_values()` into a frozen typed Settings, never into `os.environ`. A Settings model is optional and, if warranted, is a normal source stub. +7. IF a value's representation is ambiguous (e.g. a database URL passed as bare string) THEN pin one canonical form once (the `sqlite:///path` URL form) and state it in the stub so every consumer agrees per [[software-craft/source-stubs]]. diff --git a/.opencode/skills/implement-from-stub/SKILL.md b/.opencode/skills/implement-from-stub/SKILL.md index 79696125..a2930905 100644 --- a/.opencode/skills/implement-from-stub/SKILL.md +++ b/.opencode/skills/implement-from-stub/SKILL.md @@ -7,7 +7,7 @@ description: "Write the minimum production code to turn the target's tests green 1. Load [[software-craft/source-stubs]], [[software-craft/tdd]], [[software-craft/design-patterns]] — stub sync, the cycle, and implementation patterns. 2. Implement — or, for rework, re-implement — the .py from its .pyi. The .pyi signature is the spec; fill or correct the body to satisfy it and pass the tests. Keep the .py consistent with its sibling .pyi. -3. Emit the structural artifacts the module requires, keyed on what it is: IF an ORM model THEN emit an Alembic migration (the migration is the schema spec); IF an external adapter THEN replay the cassettes captured in explore. Config follows 12-factor — a Settings module, if implemented, reads environment variables via dotenv; it is a normal source module, not a special artifact. +3. Emit the structural artifacts the module requires, keyed on what it is: IF an ORM model THEN emit an Alembic migration (the migration is the schema spec); IF an external adapter THEN reproduce the recorded request shape exactly (method, path, query parameters, headers from external-contracts.md) — vcr matches the request strictly, so the implementation conforms to the cassette, not the other way around. Config follows 12-factor per [[software-craft/secrets-and-config]]: non-secret config via `load_dotenv()` from the workspace `.env`; secrets via `dotenv_values()` from `~/.secrets/.env` — read once into a frozen typed Settings, never into `os.environ`. IF an auth-dependent test fails on credentials THEN stop and ask the user with suggestions — do not investigate the secret. 4. IF the body cannot satisfy the .pyi without changing it THEN that is a contract gap — do not edit the stub; escalate at review. 5. Run stubtest scoped to the modules built this cycle — the source module(s) and the test module(s) whose pending marks were removed. The whole-suite stubtest waits until every source .py exists, because unbuilt sibling stubs would false-fail per [[software-craft/source-stubs]], [[software-craft/tdd]]. 6. Stubtest imports the runtime module, so every transitive runtime dependency must be installed in the project venv. IF an import is used only for types THEN prefer `if typing.TYPE_CHECKING:` so stubtest does not pull heavy runtime deps for type-only references. diff --git a/.opencode/skills/merge-to-dev/SKILL.md b/.opencode/skills/merge-to-dev/SKILL.md index 12633ef3..4b4036f4 100644 --- a/.opencode/skills/merge-to-dev/SKILL.md +++ b/.opencode/skills/merge-to-dev/SKILL.md @@ -6,6 +6,6 @@ description: "Squash-merge the feature commits into dev and verify the whole sui # Merge To Dev 1. Load [[software-craft/git-conventions]] — squash-merge form. -2. Squash-merge the feature commits into dev per [[software-craft/git-conventions]]. +2. Switch to dev and squash-merge the feature commits per [[software-craft/git-conventions]]; the green-suite and whole-suite stubtest gate is verified on dev after the merge. 3. Verify the full suite is green on dev after the merge: no pending markers remain (every source .pyi has its sibling .py, so every test runs) and every test passes. 4. Verify whole-suite stubtest is clean across both source and tests: every source .pyi and every test .pyi agrees with its sibling .py — no drift smuggled in by the batch. diff --git a/.opencode/skills/record-cassette/SKILL.md b/.opencode/skills/record-cassette/SKILL.md index 43edbeb0..9405c660 100644 --- a/.opencode/skills/record-cassette/SKILL.md +++ b/.opencode/skills/record-cassette/SKILL.md @@ -10,5 +10,5 @@ description: "Execute the probe against the real service and record the exchange 3. IF HTTP THEN record with vcrpy and `decode_compressed_response=True` so gzip/br bodies are stored decoded, not opaque blobs per [[software-craft/external-fixtures]]. Dispatch the recorder on the service kind (HTTP API, external database, message queue, object storage, other) — the recorder is the one knob that varies per kind. 4. Scrub the cassette to deterministic and safe-to-commit. IF HTTP THEN `filter_headers` strips `Authorization` and `before_record_response` strips volatile headers — `date`, `age`, `server`, `last-modified`, `content-encoding`, `transfer-encoding`, `vary`, `cf-ray`, `report-to`, `nel`. Dispatch the scrub-field list on the service kind. 5. IF a cassette has an opaque/churning body or a leaked secret THEN it fails the external contract — re-scrub before commit. -6. Append the confirmed endpoint base, auth scheme, and gotchas to the shared external-contracts notes. +6. Append to the shared external-contracts notes the confirmed endpoint base, auth scheme, gotchas, AND the exact request shape captured per interaction (method, path, query parameters, required headers). The cassette is the contract and vcr matches on the request, so the implementer must reproduce this exact shape — record it explicitly, do not leave it implicit in the cassette. 7. IF the live exchange contradicts the research or the interview THEN signal a mismatch. diff --git a/.opencode/skills/record-decision/SKILL.md b/.opencode/skills/record-decision/SKILL.md new file mode 100644 index 00000000..bd77935a --- /dev/null +++ b/.opencode/skills/record-decision/SKILL.md @@ -0,0 +1,14 @@ +--- +name: record-decision +description: "Author (or amend) an Architecture Decision Record for a load-bearing architectural decision, in place, with a change log." +--- + +# Record Decision + +1. Confirm the decision is ADR-worthy before authoring: it has genuine trade-offs between multiple viable alternatives **and** cross-cutting impact (reversing it would ripple across contracts). IF it has one obvious choice or only local impact THEN it is BAU — do not record it; stop here. +2. Copy `.templates/docs/decisions/YYYY-MM-DD-.md.template` to `docs/decisions/-.md`, replacing the date placeholder with today's ISO date and the slug with a short kebab title for the decision. +3. Fill the sections from the decision itself, not from memory of the alternatives: `Context` (the forces — link the interview, glossary, existing ADRs, cassettes, and the contract set; do not restate them), `Decision` (one imperative sentence), `Alternatives considered` (each alternative + why it was rejected), `Consequences` (+ / − / neutral, with mitigations for the negatives). +4. In `Traceability`, link the artefacts the decision touches — tests, source `.pyi`, migrations, cassettes, glossary terms, related ADRs — by path. Points only; never restate the artefact's content (tests are the source of truth). +5. Seed the `Change log` with one row: ` | Created | `. +6. IF the decision supersedes an existing ADR THEN edit that ADR in place — amend its `Status`, `Decision`, `Alternatives considered`, and `Consequences` to the current decision — and append a `Change log` row (` | Amended | `). Do not create a new file; the body always reflects the current decision and the log carries the history. +7. Verify every path in `Traceability` resolves to a real artefact before finishing. diff --git a/.opencode/skills/refactor-green/SKILL.md b/.opencode/skills/refactor-green/SKILL.md index d414f37f..b1b9ac91 100644 --- a/.opencode/skills/refactor-green/SKILL.md +++ b/.opencode/skills/refactor-green/SKILL.md @@ -5,7 +5,7 @@ description: "Improve the source structure under green tests, with the .pyi fixe # Refactor Green -1. Load [[software-craft/refactoring-techniques]], [[software-craft/smell-catalogue]], [[software-craft/object-calisthenics]], [[software-craft/solid]] — the refactoring moves, smell taxonomy, and quality criteria. +1. Load [[software-craft/refactoring-techniques]], [[software-craft/smell-catalogue]], [[software-craft/object-calisthenics]], [[software-craft/solid]], [[software-craft/design-patterns]] — the refactoring moves, smell taxonomy, quality criteria, and pattern catalog. 2. Improve the source structure while tests stay green. The source .py is fluid; the .pyi is fixed; tests are fixed contracts — do not edit them. 3. IF a smell is present THEN remove it using the catalogue and a matching technique per [[software-craft/smell-catalogue]], [[software-craft/refactoring-techniques]]. Apply SOLID, DRY, KISS, YAGNI, Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. 4. Keep the .py consistent with its sibling .pyi so stubtest stays clean. IF a change requires editing the .pyi THEN stop — a contract change is escalated at review. diff --git a/.opencode/skills/research-provider/SKILL.md b/.opencode/skills/research-provider/SKILL.md index 099c17d6..17be7bb5 100644 --- a/.opencode/skills/research-provider/SKILL.md +++ b/.opencode/skills/research-provider/SKILL.md @@ -8,7 +8,7 @@ description: "Ground one external service in its real behaviour by reading the p 1. Load [[software-craft/external-fixtures]] — the kind-dispatch table (docs-focus, recorder, scrub-fields, default specialist). 2. Identify the exact provider — the specific service and version, not just its kind. 3. Research online: websearch the provider and webfetch its official docs. Read for reference, authentication/credentials scheme, client/SDK, error catalog, rate limits, pagination, idempotency, known gotchas. Do not write probe code until the docs are read. -4. Determine the access shape: endpoint base/URI, protocol, credentials source (a 12-factor environment variable), request/response shape, and both success and failure modes. +4. Determine the access shape: endpoint base/URI, protocol, credentials source (a named variable the user must supply in `~/.secrets/.env`), request/response shape, and both success and failure modes. Per [[software-craft/secrets-and-config]] the agent names the variable and instructs the user where to set it; it never holds or prints the value. 5. Recommend at most one advisory specialist for this provider. IF the provider raises auth/secrets/PII concerns THEN recommend security; IF schema/message-shape THEN data; IF user-facing flows THEN ux; IF project-specific semantics THEN domain. 6. Dispatch on the service kind (HTTP API, external database, message queue/event stream, object storage, other) for the docs-focus and default-specialist per [[software-craft/external-fixtures]] — the kind table is the one knob that varies. 7. IF the docs reveal the service behaves differently than the interview assumed THEN signal a mismatch. diff --git a/.opencode/skills/review-implementation/SKILL.md b/.opencode/skills/review-implementation/SKILL.md index e534138f..4ac4d609 100644 --- a/.opencode/skills/review-implementation/SKILL.md +++ b/.opencode/skills/review-implementation/SKILL.md @@ -5,10 +5,11 @@ description: "Gate the implementation against its contract for correctness, qual # Review Implementation -1. Load [[software-craft/code-review]], [[software-craft/solid]], [[software-craft/smell-catalogue]] — review method and quality criteria. +1. Load [[software-craft/code-review]], [[software-craft/solid]], [[software-craft/smell-catalogue]], [[software-craft/design-patterns]] — review method, quality criteria, smell taxonomy, and the pattern catalog. 2. Review the implemented source against its contract per [[software-craft/code-review]]. 3. Check impl-matches-contract: the .py satisfies its .pyi and the requirement, without excess. 4. Check source-quality-clean: IF SOLID, DRY, KISS, YAGNI, Object Calisthenics are violated OR a smell is present THEN reject per [[software-craft/solid]], [[software-craft/smell-catalogue]]. 5. Check stubtest-clean: the source .py and its sibling .pyi agree, AND the target's test .py and its sibling .pyi agree — no drift on either pair. 6. Check tests-green: the target's tests pass and no previously-green test regressed. 7. Read the target's .pyi first; open the .py only for the spots under review. +8. IF review reveals the contract itself is the problem — not the implementation — THEN append the finding to `.cache//journal.md` (contract, the gap, the evidence) and fire `reveals-gap`. This routes back to plan, not changes-needed. diff --git a/.opencode/skills/ship-unit/SKILL.md b/.opencode/skills/ship-unit/SKILL.md index 277bc74d..a53b62c0 100644 --- a/.opencode/skills/ship-unit/SKILL.md +++ b/.opencode/skills/ship-unit/SKILL.md @@ -6,6 +6,6 @@ description: "Commit the built unit as one logical change with a descriptive imp # Ship Unit 1. Load [[software-craft/git-conventions]] — imperative message form and the one-logical-change rule. -2. Commit the unit as one logical change: the implemented source .py plus any structural artifacts (migrations, fixtures, cassettes) it required. +2. Commit the unit as one logical change on the feature branch per [[software-craft/git-conventions]]: the implemented source .py plus any structural artifacts (migrations, fixtures) it required. 3. Write a descriptive imperative message per [[software-craft/git-conventions]]. 4. Keep the .pyi unchanged from plan — contracts are fixed during build. diff --git a/.opencode/skills/simulate-contracts/SKILL.md b/.opencode/skills/simulate-contracts/SKILL.md index a05c4d63..1cc53680 100644 --- a/.opencode/skills/simulate-contracts/SKILL.md +++ b/.opencode/skills/simulate-contracts/SKILL.md @@ -12,3 +12,5 @@ description: "Answer whether a correct implementation passing every test would y 5. Check traceability: every consolidated interview finding maps to at least one test or an explicit deferral, and every external service has a captured cassette its tests replay. 6. Check layer order: external-boundary stubs complete before adapter stubs, and so on. 7. Run stubtest on the tests to confirm zero drift between every test .pyi and its sibling .py per [[software-craft/test-stubs]]. Source stubtest waits for build — no source .py exists yet. +8. Run ruff on the whole project (`ruff check .` and `ruff format . --check`); the gate is zero violations. Plan-authored tests and source stubs must be lint-clean before build — a lint defect caught here is a defect build never has to edit around. +9. IF a test references an external exchange no captured cassette covers THEN append the finding to `.cache//journal.md` (service, the missing case) and fire `needs-capture`. This routes back to explore to record the missing reality, not forward to build. diff --git a/.opencode/skills/write-probe/SKILL.md b/.opencode/skills/write-probe/SKILL.md index 5028e544..0a4261e7 100644 --- a/.opencode/skills/write-probe/SKILL.md +++ b/.opencode/skills/write-probe/SKILL.md @@ -7,6 +7,6 @@ description: "Author the minimal authenticated probe script that exercises one s 1. Load [[software-craft/external-fixtures]] — probe patterns and the kind-dispatch table. 2. Translate the researched access shape into the real working call sequence. Cover one success path and at least one representative error path. -3. Pull credentials from the 12-factor environment (a dotenv `.env` locally); never hardcode them. +3. Pull secrets from `~/.secrets/.env` via `dotenv_values()` — never `load_dotenv()` into `os.environ` (secrets stay scoped to the probe, off the process env); non-secret config (base URLs) comes from the workspace `.env`. Reference every secret by name; never print or log it. IF a secret the probe needs is not yet set up THEN instruct the user how to obtain and place it — do not create it. Per [[software-craft/secrets-and-config]]. 4. Keep the script throwaway — reference for the capture step and the later implementer. IF the package or tests could import it THEN move it out — it is never imported. 5. Do not execute the script here; capturing the exchange is the next step's job. diff --git a/.opencode/skills/write-test-py/SKILL.md b/.opencode/skills/write-test-py/SKILL.md index 4e5e3e9c..be629d6b 100644 --- a/.opencode/skills/write-test-py/SKILL.md +++ b/.opencode/skills/write-test-py/SKILL.md @@ -6,9 +6,11 @@ description: "Transform the reviewed test stubs into executable test bodies, wit # Write Test Py 1. Load [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/smell-catalogue]], [[software-craft/test-design]] — the quality criteria and body patterns. -2. Write the test bodies — no docstrings, no comments; the body is the spec. Bodies define how entities relate, compose, and collaborate: wire classes, data, and objects following best practices. -3. Apply the code-quality gate here: SOLID, DRY, KISS, YAGNI, Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a smell is present THEN reject it per [[software-craft/smell-catalogue]]. -4. Mark each test with the pending marker; the conftest hook skips pending tests so the suite stays green-with-skips until source is built. -5. Defer the system-under-test import into each test body so an unbuilt module collects cleanly and its pending tests skip rather than error at collection. Keep third-party and test-only imports at module top. -6. Keep the .py's module-level names and method signatures in exact agreement with its .pyi — stubtest checks the pair strictly. -7. IF reworking an existing contract THEN edit the body to match the changed .pyi and re-apply the pending marker to the affected tests so they skip until build re-selects them. +2. Read `.cache//journal.md` IF present — it carries escalation findings from build. Edit the bodies of the contracts it names to match the reworked stubs; skip if absent (first pass). +3. Write the test bodies — no docstrings, no comments; the body is the spec. Bodies define how entities relate, compose, and collaborate: wire classes, data, and objects following best practices. +4. Apply the code-quality gate here: SOLID, DRY, KISS, YAGNI, Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a smell is present THEN reject it per [[software-craft/smell-catalogue]]. +5. Mark each test with the pending marker; the conftest hook skips pending tests so the suite stays green-with-skips until source is built. +6. Defer the system-under-test import into each test body so an unbuilt module collects cleanly and its pending tests skip rather than error at collection. Keep third-party and test-only imports at module top. +7. Keep the .py's module-level names and method signatures in exact agreement with its .pyi — stubtest checks the pair strictly. +8. Run ruff on the authored test files (`ruff check` and `ruff format`); fix every violation so build receives lint-clean tests. +9. IF reworking an existing contract THEN edit the body to match the changed .pyi and re-apply the pending marker to the affected tests so they skip until build re-selects them. diff --git a/.templates/.env.example.template b/.templates/.env.example.template new file mode 100644 index 00000000..3139d444 --- /dev/null +++ b/.templates/.env.example.template @@ -0,0 +1,20 @@ +# environment +# +# Committed, non-secret configuration. Copy to `.env` (gitignored) and edit. +# NEVER place secrets here — this file is version-controlled. Secrets live in +# `~/.secrets/.env` (out-of-workspace), loaded at runtime with +# `dotenv_values()` into a frozen typed Settings, never into `os.environ`. +# See the `secrets-and-config` knowledge for the full model. + +# --- non-secret configuration (defaults shown) --- +# Loaded with `load_dotenv()`; safe in `os.environ`. +API_BASE=https://default.example.com +DATABASE_URL=sqlite:///project.db +LOG_LEVEL=INFO + +# --- secrets: DO NOT set values here --- +# Place each in `~/.secrets/.env` as `VAR_NAME=`. +# Loaded with `dotenv_values()`; the agent will instruct you how to obtain each +# and will never read or debug the value itself. +API_KEY= +DATABASE_PASSWORD= diff --git a/.templates/README.md.template b/.templates/README.md.template new file mode 100644 index 00000000..65012985 --- /dev/null +++ b/.templates/README.md.template @@ -0,0 +1,45 @@ +# + +> changes. For the current build state see `docs/state.md` (regenerated each +> cycle). Tests are the source of truth for behaviour; this README is +> orientation.> + +## Purpose + +<2–4 sentences: the problem, who has it, and what this project does about it.> + +## Scope + + + +## How to run + +**Entry point:** + +**Environment (12-factor):** configure via environment variables, kept in a +gitignored `.env`. Required vars: + +- `` — + + + +## Where things live + +| Path | Holds | +|---|---| +| `/` | source — `.pyi` stubs + `.py` bodies | +| `tests/integration/`, `tests/e2e/` | integration + e2e tests (no unit) | +| `tests/cassettes/` | recorded external contracts (vcrpy) — the wire truth | +| `tests/fixtures/` | test fixtures | +| `migrations/` | Alembic migrations — the schema spec | +| `docs/glossary.md` | ubiquitous language — the names | +| `docs/state.md` | living current-state specification (regenerated each cycle) | +| `docs/research/` | human-reference sources behind knowledge citations | + +## Workflow + +This project follows the staged-contract pipeline: discover → explore → plan → +build → deliver. Drive it one state at a time with flowr — see `AGENTS.md` for +the lifecycle and commands. diff --git a/.templates/docs/decisions/YYYY-MM-DD-.md.template b/.templates/docs/decisions/YYYY-MM-DD-.md.template new file mode 100644 index 00000000..d7745616 --- /dev/null +++ b/.templates/docs/decisions/YYYY-MM-DD-.md.template @@ -0,0 +1,60 @@ +# + +> A record of a load-bearing architectural decision — the *why* behind a choice +> that multiple viable alternatives competed for. Authored only by the +> system-architect, only when a decision has genuine trade-offs **and** +> cross-cutting impact (reversing it would ripple across contracts); BAU +> decisions are not recorded. Supersession is edit-in-place: amend the body to +> the current decision and append a Change log row — do **not** create a new +> file. Tests are the source of truth for behaviour; the Traceability section +> points at affected artefacts and never restates them. + +## Status + +Proposed | Accepted | Deprecated + +## Decider + Date + +- **Decider:** +- **Date:** + +## Context + + + +## Decision + + + +## Alternatives considered + +- **:** +- **:** + +## Consequences + +- **(+)** +- **(−)** +- **(neutral)** + +## Traceability + +Points at the artefacts this decision touches; never restates their content. + +- **Tests:** `` +- **Source `.pyi`:** `` +- **Migrations:** `` +- **Cassettes:** `` +- **Glossary:** `` +- **Related ADRs:** `` + +## Change log + +Appended on any amendment; the body above always reflects the current decision. + +| Date | Change | Reason | +|---|---|---| +| | Created | | diff --git a/.templates/docs/research/card.md.template b/.templates/docs/research/card.md.template new file mode 100644 index 00000000..d6025a78 --- /dev/null +++ b/.templates/docs/research/card.md.template @@ -0,0 +1,41 @@ +# (<Author>, <Year>) + +> A research card — the full citation and the source's load-bearing idea, kept +> so a knowledge author can confirm what an `(Author, Year)` citation refers to. +> Verify every field against the source before committing; never author a card +> from memory, and never fabricate one (see [[methodology/research-files]]). +> One card per source, filed under `docs/research/<discipline>/`. + +## Citation + +<Author(s)>. (<Year>). *<Title>.* <Publisher / Journal / Venue>, <edition or date>. <ISBN / DOI> +URL: <canonical URL — verified> + +## Method + +<source type and research method: Practitioner book / Academic paper / Web article / Edited reference; plus the method where it bears on the claim> + +## Confidence + +<High | Medium | Low — one line on why; lower when the URL or authorship is unverified> + +## Key Insight + +<one sentence: the single load-bearing idea the source contributes> + +## Core Findings + +1. <finding> +2. <finding> + +## Mechanism + +<paragraph: how the idea actually works — the machinery, not a paraphrase of it> + +## Relevance + +<paragraph: which knowledge file(s) cite this source, and what claim the citation grounds> + +## Related Research + +- <Author Year> — <shared topic or relationship> diff --git a/.templates/docs/state.md.template b/.templates/docs/state.md.template new file mode 100644 index 00000000..0b78376d --- /dev/null +++ b/.templates/docs/state.md.template @@ -0,0 +1,65 @@ +# Specification (current state) + +> The living specification of this project's current state — what it is and +> where it is in its build. Regenerated each pipeline cycle by the refresh step +> from the truth: test `.pyi`, pending marks, cassettes, migrations, and the +> glossary. Never hand-edited; hand-authoring creates a second source of truth +> that drifts. Tests are the source of truth for behaviour — this file is a +> derived view. When prose and a test disagree, the test wins. + +## Snapshot + +- **Project:** <name> +- **Version:** <version from `pyproject.toml`> +- **Generated:** <YYYY-MM-DD> by flowr session `<session_id>` +- **Suite:** <green | red> · **Contracts:** <built>/<built+pending> built (<N> pending) +- **Purpose:** → see `README.md` + +## Entry points & boundaries + +**Entry points:** <how execution enters — CLI command / API routes / scheduled jobs> + +**Boundary:** +- *Internal (ours):* <module list — the contracts this project owns> +- *External (depends on):* <service list — see Dependencies> + +## Contract index + +The derived map of what this system does. Each row points at the test (the +behavioural truth) and the source `.pyi` (the type surface). Intent is +regenerator-authored from the test body and self-corrects each cycle. + +| Contract | Module | Test | Intent (one line) | Status | +|---|---|---|---|---| +| <Name> | `<package>.<mod>` | `<test_file>` | <one line, read from the test body> | <built \| pending> | + +## Composition & data flow + +How the contracts assemble into the e2e path, and the data that flows through +it. Entity names follow `docs/glossary.md`. + +<e2e call chain as an arrow sequence: `Entry.main → ContractA.method(...) → ContractB.method(...) → ...`> + +**Data flow:** <entity → entity → entity → store; where the data persists> + +## Dependencies + +**External services** — wire shapes live in the cassettes (the authoritative +external contract); this table points at them and never restates the shape. + +| Service | Purpose | Protocol | Cassette | Env vars | +|---|---|---|---|---| +| <name> | <what for> | <HTTPS / ...> | `tests/cassettes/<svc>/...` | <VAR names> | + +**Persistence** — schema lives in the migrations (the migration IS the schema +spec); this table points at them and never restates the DDL. + +| Entity | Store | Migration | +|---|---|---| +| <name> | <db / file / ...> | `migrations/<NNN>_<name>.py` | + +## Status & last cycle + +- **Built:** <N> · **Pending:** <N> — backlog: <contract names, or "none"> +- **Last cycle:** <what the last pipeline pass delivered> +- **Next:** <next target, or "none — shipped"> diff --git a/AGENTS.md b/AGENTS.md index a759baac..ae136b55 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,8 @@ Gitignored (local working state, regenerated on demand): | `.cache/explore/` | throwaway probe scripts (run once to record cassettes; never imported) | | `.cache/sessions/` | flowr session state | | `.backup/` | previous system (recoverable from `origin/main`) | -| `.env` | local config (12-factor) | +| `.env` | non-secret local config (12-factor) | +| `~/.secrets/<project>.env` | secrets (out-of-workspace; `dotenv_values()` into a frozen Settings, gated by opencode `external_directory`) | ## Agents, skills & knowledge diff --git a/README.md b/README.md new file mode 100644 index 00000000..687d0e0f --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# temple8 + +> A Python project **methodology template** — a ready-to-clone foundation that +> wires the staged-contract development workflow into a new project, with the +> flow set, the agents/skills/knowledge methodology layer, CI, and tooling +> pre-configured. temple8 itself is not an application; an instance built from +> it holds the package, tests, and instance docs. + +## Purpose + +temple8 exists to make one workflow reproducible across Python projects: tests +are authored up front as a staged contract surface (test `.pyi` → test `.py` +marked pending → source `.pyi` → simulate), then built out one contract per +cycle under flowr orchestration, with the methodology layer (agents, skills, +knowledge), the drift gates (pyright, `mypy.stubtest`, ruff, pytest), and CI +already in place. Cloning the template removes the bootstrap cost of +re-establishing that workflow each project. + +## Scope + +**In** — the methodology only: flow definitions, the agent/skill/knowledge +layer, document templates, CI, the conftest pending-marker hook, and the +pyproject tooling. + +**Out** — everything an instance owns: an application package, tests, +migrations, cassettes, `docs/glossary.md`, `docs/state.md`. These live in a +project instantiated from this template, not in temple8 itself. The `app` +references in `pyproject.toml` (`[tool.setuptools] packages`, task targets) are +placeholders for whatever package name the instance chooses. + +## How to run + +temple8 is not run as an application — it is used as a template for one. + +1. Clone or copy this tree into a new project directory. +2. Create the package (replacing the `app` placeholder) and the test layout + (`tests/integration/`, `tests/e2e/`, `tests/cassettes/`, `tests/fixtures/`); + there is no `tests/unit/` by policy. +3. Drive the staged-contract pipeline one state at a time with flowr: + + ``` + uv run python -m flowr session init pipeline-flow --name default + uv run python -m flowr check --session default + uv run python -m flowr next --session default + uv run python -m flowr transition <trigger> --session default + ``` + +A reference usage — a weather-lookup CLI driven through the full pipeline — +lives outside the template tree; see the clean-slate rebuild notes. + +## Secrets + +Secrets (API keys, tokens, passwords) never live in the repo. The split: + +- **Non-secret config** — base URLs, regions, feature flags — in the workspace + `.env` (gitignored), loaded with `load_dotenv()` into `os.environ`. +- **Secrets** — in `~/.secrets/<project>.env`, *outside* the repo tree, loaded + with `dotenv_values()` straight into a frozen typed `Settings` and **never** + into `os.environ` (so `env`, `printenv`, and `/proc` cannot see them). +- **`.env.example`** is committed: every variable name, non-secret defaults + filled, secret lines empty with a pointer to `~/.secrets/`. + +Instance authors add one opencode permission rule so a direct read of the +secrets path prompts the user instead of passing silently: + +```json +{ "permission": { "external_directory": { "~/.secrets/**": "ask", "*": "allow" } } } +``` + +Agents in this workflow never create or debug a secret: they instruct the user +how to obtain and place each credential, and on an auth failure they ask with +suggestions instead of investigating the value. The full threat model and +layered defense are in the `secrets-and-config` knowledge. + +## Where things live + +| Path | Holds | +|---|---| +| `.flowr/flows/` | the six flow definitions — `pipeline-flow` plus the five subflows | +| `.opencode/agents/` | role identities (who owns what decision) | +| `.opencode/skills/` | per-state procedures (one per state) | +| `.opencode/knowledge/` | reference and explanation — `methodology/`, `requirements/`, `software-craft/` | +| `.templates/` | document templates — glossary, state (living spec), README, research card | +| `.github/workflows/` | CI — ruff + flowr validate always on; pyright/stubtest/pytest guarded on package+tests | +| `conftest.py` | the `@pytest.mark.pending` skip hook (the backlog signal) | +| `pyproject.toml` | tooling — ruff (bug-catcher select, no docstrings), pytest markers, taskipy, stubtest | +| `docs/research/` | human-reference sources behind the knowledge citations | +| `AGENTS.md` | the methodology brief, routing, and flowr commands | +| `TODO.md` | what is owed and forward-planned | + +## Workflow + +The staged-contract pipeline runs discover → explore → plan → build → deliver +→ shipped, driven one state at a time through flowr: + +- **discover** — interview funnel elicits requirements and authors the glossary; +- **explore** — every external service is grounded by recording real exchanges + as vcrpy cassettes (the authoritative external contract); +- **plan** — tests are authored up front (`.pyi` → `.py` marked pending → source + `.pyi` derived) and simulated before any source is built; +- **build** — each source contract is implemented one cycle at a time + (red → green → refactor → review → ship) from its fixed `.pyi`; +- **deliver** — feature commits squash-merge into dev under the whole-suite + gates, then publish. + +Tests are the source of truth for behaviour. See `AGENTS.md` for the full +lifecycle, the gate evidence keys, and the flowr commands. diff --git a/TODO.md b/TODO.md index db4e8927..1867c7c9 100644 --- a/TODO.md +++ b/TODO.md @@ -98,9 +98,11 @@ Sequence (the authoritative development order): `@pytest.mark.pending` so it skips until build re-selects it. 9. **derive-source-stubs** *(plan)* — derive `<package>/**/*.pyi` from the reviewed test `.py`: every type a test references gets a definition. No - hardcoded layout (no `models/`, no `config.pyi`); config follows 12-factor - (env vars; python-dotenv + gitignored `.env` for local secrets; a typed - Settings model is optional, a normal source `.pyi` if warranted). + hardcoded layout (no `models/`, no `config.pyi`); config follows the + secrets/config split per the `secrets-and-config` knowledge (non-secret config + in workspace `.env`; secrets in `~/.secrets/<project>.env` via + `dotenv_values()`, never `os.environ`; a typed Settings model is optional, a + normal source `.pyi` if warranted). 10. **simulate-contracts** *(plan)* — gate: would passing these tests yield a complete, working system? pyright (combined set consistent; every import resolves), no-orphans, traceability (every external service has a captured @@ -143,8 +145,10 @@ Design decisions: (`tests/cassettes/**` — the authoritative external contract, replayed by tests/CI offline) and gitignored throwaway probe scripts (`.cache/explore/` — reference for the green implementer, never imported by `<package>` or tests). - Capture needs real 12-factor credentials; CI never runs explore, it replays - the cassettes. + Capture needs real credentials the user supplies in + `~/.secrets/<project>.env` (see the `secrets-and-config` knowledge — agent + instructs, never creates or debugs a secret); CI never runs explore, it + replays the cassettes. - Every state has its OWN skill — no skill is reused across states (the four interview states each have a distinct skill that loads the shared technique from knowledge). @@ -230,10 +234,11 @@ Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - [x] `requirements/interview-techniques.md` — Elicitation methods (CIT, Laddering/Means-End, CI Perspective Change, Funnel, Active Listening L1-L3) applied at each funnel depth. *(interview-general, interview-cross-cutting)*. AUTHORED. - [x] `requirements/domain-decomposition.md` — Decomposing each bounded context into DDD building blocks (aggregate-first); gap analysis as a coverage matrix (every context → ≥1 block; every quality attribute → ≥1 block). *(interview-building-blocks, review-test-stubs)*. AUTHORED. - [x] `requirements/aggregate-boundaries.md` — Sizing and splitting aggregates: single-entity default, reference-by-identity, split on invariant seams (Evans ch 4; Vernon ch 10). *(interview-building-blocks)*. AUTHORED. -- [ ] `requirements/ubiquitous-language.md` — Curating the glossary: term extraction, genus-differentia definitions, bounded-context grouping (Evans DDD). *(consolidate-interview)* +- [x] `requirements/ubiquitous-language.md` — Curating the glossary: term extraction, genus-differentia definitions, bounded-context grouping (Evans DDD). *(consolidate-interview)*. AUTHORED. **Explore (ground externals):** - [x] `software-craft/external-fixtures.md` — Capturing external reality: record-once-replay-forever (vcrpy HTTP cassettes; CI under `VCR_RECORD_MODE=none`), the kind-dispatch table (recorder/docs-focus/scrub-fields/specialist per kind — vcrpy is HTTP-only), two scrubs (safety + determinism), 12-factor creds, capture-is-truth. *(research-provider, write-probe, record-cassette)*. AUTHORED. +- [x] `software-craft/secrets-and-config.md` — The secrets/config split: non-secret config in workspace `.env`; secrets in `~/.secrets/<project>.env` (out-of-workspace) read with `dotenv_values()` into a frozen typed Settings, never `os.environ`; the LLM-agent threat model (5 vectors) + layered defense; agent never creates/reads/debugs a secret (instructs the user; asks with suggestions on auth failure); `.env.example` as the committed env contract. *(write-probe, research-provider, derive-source-stubs, implement-from-stub)*. AUTHORED. **Plan (author contracts):** - [x] `software-craft/test-stubs.md` — PEP 484 `.pyi` signature files for tests (disambiguated from the Meszaros test double); `.pyi`-preferred hides drift from pyright, stubtest is the sole detector; mirror the complete module surface; stdlib-typing-only with types under `TYPE_CHECKING`. *(author-test-stubs, simulate-contracts)*. AUTHORED. diff --git a/app/__init__.pyi b/app/__init__.pyi deleted file mode 100644 index e69de29b..00000000 diff --git a/app/cli.py b/app/cli.py deleted file mode 100644 index 45fa7160..00000000 --- a/app/cli.py +++ /dev/null @@ -1,22 +0,0 @@ -from collections.abc import Sequence - -from app.history import History, LookupRecord -from app.settings import Settings -from app.weather import WeatherAdapter - - -def main(argv: Sequence[str]) -> None: - settings = Settings.from_env() - adapter = WeatherAdapter(settings.geocoding_base, settings.forecast_base) - history = History(settings.database_url) - city = argv[0] - conditions = adapter.forecast(adapter.geocode(city)) - history.record( - LookupRecord( - city=city, - temperature=conditions.temperature, - wind_speed=conditions.wind_speed, - weather_code=conditions.weather_code, - ) - ) - print(f"{city} {conditions.temperature}") diff --git a/app/cli.pyi b/app/cli.pyi deleted file mode 100644 index 7ee2ea60..00000000 --- a/app/cli.pyi +++ /dev/null @@ -1,4 +0,0 @@ -from collections.abc import Sequence - - -def main(argv: Sequence[str]) -> None: ... diff --git a/app/history.py b/app/history.py deleted file mode 100644 index 545b1e7a..00000000 --- a/app/history.py +++ /dev/null @@ -1,45 +0,0 @@ -import sqlite3 -from dataclasses import dataclass - - -@dataclass(frozen=True) -class LookupRecord: - city: str - temperature: float - wind_speed: float - weather_code: int - - -class History: - def __init__(self, database_url: str) -> None: - path = database_url.removeprefix("sqlite:///") - self._connection = sqlite3.connect(path) - self._connection.execute( - "CREATE TABLE IF NOT EXISTS lookups" - " (id INTEGER PRIMARY KEY AUTOINCREMENT," - " city TEXT, temperature REAL, wind_speed REAL, weather_code INTEGER)" - ) - self._connection.commit() - - def record(self, lookup: LookupRecord) -> None: - self._connection.execute( - "INSERT INTO lookups (city, temperature, wind_speed, weather_code)" - " VALUES (?, ?, ?, ?)", - (lookup.city, lookup.temperature, lookup.wind_speed, lookup.weather_code), - ) - self._connection.commit() - - def recent(self) -> list[LookupRecord]: - rows = self._connection.execute( - "SELECT city, temperature, wind_speed, weather_code" - " FROM lookups ORDER BY id DESC" - ).fetchall() - return [ - LookupRecord( - city=row[0], - temperature=row[1], - wind_speed=row[2], - weather_code=row[3], - ) - for row in rows - ] diff --git a/app/history.pyi b/app/history.pyi deleted file mode 100644 index 931cd0da..00000000 --- a/app/history.pyi +++ /dev/null @@ -1,15 +0,0 @@ -from dataclasses import dataclass - - -@dataclass(frozen=True) -class LookupRecord: - city: str - temperature: float - wind_speed: float - weather_code: int - - -class History: - def __init__(self, database_url: str) -> None: ... - def record(self, lookup: LookupRecord) -> None: ... - def recent(self) -> list[LookupRecord]: ... diff --git a/app/settings.py b/app/settings.py deleted file mode 100644 index 104b68e4..00000000 --- a/app/settings.py +++ /dev/null @@ -1,22 +0,0 @@ -import os -from dataclasses import dataclass -from typing import Self - - -@dataclass(frozen=True) -class Settings: - geocoding_base: str - forecast_base: str - database_url: str - - @classmethod - def from_env(cls) -> Self: - return cls( - geocoding_base=os.environ.get( - "WEATHER_GEOCODING_BASE", "https://geocoding-api.open-meteo.com" - ), - forecast_base=os.environ.get( - "WEATHER_FORECAST_BASE", "https://api.open-meteo.com" - ), - database_url=os.environ.get("DATABASE_URL", "sqlite:///weather.db"), - ) diff --git a/app/settings.pyi b/app/settings.pyi deleted file mode 100644 index 1abce396..00000000 --- a/app/settings.pyi +++ /dev/null @@ -1,12 +0,0 @@ -from dataclasses import dataclass -from typing import Self - - -@dataclass(frozen=True) -class Settings: - geocoding_base: str - forecast_base: str - database_url: str - - @classmethod - def from_env(cls) -> Self: ... diff --git a/app/weather.py b/app/weather.py deleted file mode 100644 index a28b1b9f..00000000 --- a/app/weather.py +++ /dev/null @@ -1,51 +0,0 @@ -import httpx -from dataclasses import dataclass - - -@dataclass(frozen=True) -class Coordinates: - latitude: float - longitude: float - - -@dataclass(frozen=True) -class Conditions: - temperature: float - wind_speed: float - weather_code: int - - -class WeatherAdapter: - def __init__(self, geocoding_base: str, forecast_base: str) -> None: - self._geocoding_base = geocoding_base - self._forecast_base = forecast_base - self._client = httpx.Client() - - def geocode(self, city: str) -> Coordinates: - response = self._client.get( - f"{self._geocoding_base}/v1/search", - params={"name": city, "count": 1, "language": "en", "format": "json"}, - ) - response.raise_for_status() - results = response.json().get("results") - if not results: - raise LookupError(city) - hit = results[0] - return Coordinates(latitude=hit["latitude"], longitude=hit["longitude"]) - - def forecast(self, coordinates: Coordinates) -> Conditions: - response = self._client.get( - f"{self._forecast_base}/v1/forecast", - params={ - "latitude": coordinates.latitude, - "longitude": coordinates.longitude, - "current": "temperature_2m,wind_speed_10m,weather_code", - }, - ) - response.raise_for_status() - current = response.json()["current"] - return Conditions( - temperature=current["temperature_2m"], - wind_speed=current["wind_speed_10m"], - weather_code=current["weather_code"], - ) diff --git a/app/weather.pyi b/app/weather.pyi deleted file mode 100644 index 97a81af0..00000000 --- a/app/weather.pyi +++ /dev/null @@ -1,20 +0,0 @@ -from dataclasses import dataclass - - -@dataclass(frozen=True) -class Coordinates: - latitude: float - longitude: float - - -@dataclass(frozen=True) -class Conditions: - temperature: float - wind_speed: float - weather_code: int - - -class WeatherAdapter: - def __init__(self, geocoding_base: str, forecast_base: str) -> None: ... - def geocode(self, city: str) -> Coordinates: ... - def forecast(self, coordinates: Coordinates) -> Conditions: ... diff --git a/docs/decisions/2026-07-02-use-pyi-first-contracts.md b/docs/decisions/2026-07-02-use-pyi-first-contracts.md new file mode 100644 index 00000000..fdd907b9 --- /dev/null +++ b/docs/decisions/2026-07-02-use-pyi-first-contracts.md @@ -0,0 +1,99 @@ +# Use `.pyi`-first staged contracts as the development chain + +> A record of a load-bearing architectural decision — the *why* behind a choice +> that multiple viable alternatives competed for. Authored only by the +> system-architect, only when a decision has genuine trade-offs **and** +> cross-cutting impact (reversing it would ripple across contracts); BAU +> decisions are not recorded. Supersession is edit-in-place: amend the body to +> the current decision and append a Change log row — do **not** create a new +> file. Tests are the source of truth for behaviour; the Traceability section +> points at affected artefacts and never restates them. + +## Status + +Accepted + +## Decider + Date + +- **Decider:** system-architect (clean-slate rebuild) +- **Date:** 2026-07-02 + +## Context + +The clean-slate rebuild removed the previous spec-driven orchestration layer (the +`beehave`/BDD layer, `.feature` files, generated stubs). The workflow retains its +core principle — tests are the source of truth for behaviour — but needs a +contract chain that lets the surface be authored and simulated *before any source +is implemented*, and a way to detect drift between a signature view and the body +that pyright structurally cannot see (pyright prefers the `.pyi` and hides +`.py`/`.pyi` disagreement at runtime). The chain also has to be cheap to read +mid-build, so an agent re-entering a contract does not ingest every full body to +understand the surface. + +## Decision + +Adopt a staged `.pyi`-first contract chain as the sole development path: plan +authors test `.pyi` (signatures expressing the domain), then test `.py` bodies +marked `@pytest.mark.pending` (the body is the spec), then derives source `.pyi` +from what the tests reference, then simulates the set before build; build +implements each source `.py` from its fixed `.pyi` one contract per cycle. +`mypy.stubtest` is the drift detector for both source and test `.pyi`, gated at +simulate (tests), green/review (scoped source + test pair), and merge +(whole-suite). + +## Alternatives considered + +- **Beehave/BDD with `.feature` files and generated stubs:** rejected — the + dropped layer. Generation drifts from the source of truth, the Gherkin + ceremony is heavy for a Python workflow, and the `.feature` file becomes a + second spec that disagrees with the tests. +- **Inline annotations only (signatures-with-`...` in the `.py`, no `.pyi`):** + rejected — there is no drift detector. pyright reads the `.py` directly and + cannot flag a body that has drifted from its declared surface, so the "cheap + signature view" goal dissolves into reading full bodies; the staged-authoring + goal (simulate the *surface* before implementation) has no separate artefact + to simulate. +- **No upfront contracts (write tests at build time, classical TDD):** rejected — + loses the staged contract surface and the pre-build simulation. Build would + author tests + implementation together, collapsing the plan/build separation + and removing the moment where the whole set is checked for coherence before any + code is written. + +## Consequences + +- **(+)** Contracts are authored and simulated as a complete set before any + source is implemented; coherence gaps surface at plan, not at build. +- **(+)** `mypy.stubtest` catches `.pyi`/`.py` drift at every gate; pyright's + blind spot is covered. +- **(+)** Reads mid-build are cheap — the `.pyi` is the signature view; a full + `.py` body is opened only for the detail the stub omits. +- **(−)** A test `.pyi` carries no domain types (its parameters are fixtures and + `self`), so its domain value is near-zero and it is maintained solely so + stubtest can check the test pair — a recurring lint-and-sync cost. +- **(−)** The chain adds a `derive-source-stubs` step and a scoped-stubtest + discipline that inline annotations would not need; `mypy` is required + alongside `pyright`. +- **(neutral)** Source `.pyi` are fixed during build; a contract gap escalates + back to plan rather than being edited in place — this is the intended + discipline, not a cost. + +## Traceability + +Points at the artefacts this decision touches; never restates their content. + +- **Tests:** `tests/integration/**/*_test.pyi`, `tests/e2e/**/*_test.pyi` (the + staged test surface). +- **Source `.pyi`:** `<package>/**/*.pyi` (the derived source surface). +- **Migrations:** unaffected. +- **Cassettes:** unaffected (the external contract is orthogonal). +- **Glossary:** `docs/glossary.md` — "staged contract surface", "pending mark", + "stubtest". +- **Related ADRs:** none yet. + +## Change log + +Appended on any amendment; the body above always reflects the current decision. + +| Date | Change | Reason | +|---|---|---| +| 2026-07-02 | Created | Initial clean-slate decision. | diff --git a/docs/glossary.md b/docs/glossary.md deleted file mode 100644 index 6dd31e97..00000000 --- a/docs/glossary.md +++ /dev/null @@ -1,42 +0,0 @@ -# Glossary: temple8 - -> The ubiquitous language for this project — terms shared across conversation, -> code, and documentation (Evans, 2003). Curated from the interview for the -> IMPORTANT domain concepts, not every code symbol. Grouped by bounded context, -> where each term has one meaning. The tests are the source of truth for -> behaviour; this glossary is the source of truth for names. Extend or revise -> entries as understanding shifts. - -## Context: weather-lookup - -### City -A place name that the user supplies as the lookup target, resolved to -coordinates through the geocoding service. -*Aliases: none · Source: weather lookup* - -### Coordinates -A geographic position that the geocoding service returns for a city, carrying -the latitude and longitude the forecast service needs. -*Aliases: lat/lon · Source: weather lookup* - -### Conditions -A snapshot of the current weather at a coordinate — temperature, wind speed, -and weather code — produced by the forecast service. -*Aliases: current weather · Source: weather lookup* - -### WeatherAdapter -An anti-corruption layer that translates the open-meteo geocoding and forecast -endpoints into the domain's `Coordinates` and `Conditions` types. -*Aliases: none · Source: weather lookup* - -## Context: history - -### Lookup -A single completed weather check — the city asked, the conditions returned, and -the time it was recorded — stored as one entry in the history. -*Aliases: LookupRecord · Source: weather lookup* - -### History -An ordered, latest-first log of past lookups that the system appends to on each -check and recalls on demand. -*Aliases: lookup log · Source: weather lookup* diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 00000000..d8d31542 --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,36 @@ +# Research + +A human-reference library of the sources cited (author, year) across the +`.opencode/knowledge/` files. Each entry is a short card with the full +citation, a URL where one exists, and a summary of the source's contribution. + +## Purpose + +This folder is for **human reference only**. No flow step and no skill loads +it. It is consulted during knowledge authoring, when an author writing or +revising a knowledge file needs to confirm what a `Author, Year` citation +refers to, or to recover the source's mechanism before deepening Content. + +## Taxonomy + +Mirrors the source disciplines, with only the sub-domains that hold cited +sources kept: + +- `psychology/{social,cognitive}/` — the interview and review techniques. +- `software-engineering/{quality,process,requirements}/` — the craft sources. +- `information-science/{domain-modeling,documentation}/` — the modelling and + documentation sources. + +## Card template + +- Skeleton: `.templates/docs/research/card.md.template` (copy, name `<author>_<year>.md`, file under the matching discipline). +- Authoring standard: `.opencode/knowledge/methodology/research-files.md` — the card's purpose, the verify-never-recall rule, and the no-fabrication rule. + +Each file follows: + +`# Title (Author, Year)` / `## Citation` (full bibliographic + `URL:`) / +`## Method` / `## Confidence` / `## Key Insight` / `## Core Findings` / +`## Mechanism` / `## Relevance` / `## Related Research`. + +A source without an offline copy carries a stub card with whatever is known +and an explicit "unverified" note; it is never fabricated. diff --git a/docs/research/information-science/documentation/procida_2021.md b/docs/research/information-science/documentation/procida_2021.md new file mode 100644 index 00000000..248d558d --- /dev/null +++ b/docs/research/information-science/documentation/procida_2021.md @@ -0,0 +1,38 @@ +# Diátaxis Documentation Framework (Procida, 2021) + +## Citation + +Procida, D. (2021). *Diátaxis: A systematic approach to technical documentation authoring*. https://diataxis.fr/ +URL: https://diataxis.fr/ + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +Technical documentation has four distinct modes organized along two axes (action vs cognition, acquisition vs application) - mixing modes in single document produces confusion. + +## Core Findings + +1. **Four Documentation Types**: Tutorial (learning-oriented), How-to guide (task-oriented), Reference (information-oriented), Explanation (understanding-oriented) +2. **Two-Axis Framework**: Action vs Cognition crossed with Acquisition vs Application creates systematic quadrant organization +3. **Mode Separation**: Each quadrant demands distinct writing approach - combining forces mental state switching in readers +4. **Practical Application**: Framework adopted successfully in hundreds of documentation projects including Gatsby, Cloudflare, Vonage +5. **Quality Principle**: Provides active principle for maintainers to think effectively about documentation work + +## Mechanism + +Two axes create systematic quadrant: Tutorials (learning-oriented, action + acquisition), How-to guides (task-oriented, action + application), Reference (information-oriented, cognition + application), Explanation (understanding-oriented, cognition + acquisition). Each quadrant requires different content approach, style, and architecture. + +## Relevance + +Essential for technical writing, documentation architecture, developer experience. Applied in software documentation, API guides, educational content. Foundational for organizing complex technical information systems and improving user documentation experience. + +## Related Research + +Created by Daniele Procida. Name from Ancient Greek διάταξις (diataxis): "dia" (across) + "taxis" (arrangement). Adopted by major tech companies and open-source projects. Addresses content (what to write), style (how to write), architecture (how to organize) problems in technical documentation. diff --git a/docs/research/information-science/domain-modeling/brandolini_2012.md b/docs/research/information-science/domain-modeling/brandolini_2012.md new file mode 100644 index 00000000..c9fc2aca --- /dev/null +++ b/docs/research/information-science/domain-modeling/brandolini_2012.md @@ -0,0 +1,38 @@ +# Event Storming (Brandolini, 2012) + +## Citation + +Brandolini, A. (2012–present). *Event Storming*. eventstorming.com. Originally developed as "Event-based modelling" circa 2012; refined and published through workshops and online resources. +URL: https://ziobrando.blogspot.com/2013/11/introducing-event-storming.html + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Start with what the business cares about (events that happened) rather than data structures or process flows to discover domain boundaries collaboratively. + +## Core Findings + +1. **Event-First Approach**: Begin with domain events (past-tense, business-relevant verbs) placed on timeline +2. **Collaborative Discovery**: Visual, tactile format (sticky notes) lowers barrier for non-technical stakeholder participation +3. **Natural Boundary Detection**: Grouping events and commands surfaces bounded context boundaries where terms change meaning +4. **Multiple Flavors**: Improve existing business, envision startup ecosystem, explore new services, design critical software +5. **Temporal Dependencies**: Placing events on timeline reveals causal chains and business flow patterns + +## Mechanism + +EventStorming works by starting with business-relevant events rather than technical structures. Participants naturally discover temporal dependencies and causal chains by placing events chronologically. Commands reveal intent; aggregates reveal consistency boundaries. The visual format enables cross-discipline conversation between stakeholders with different backgrounds, delivering collaboration beyond silo boundaries. + +## Relevance + +Essential for Domain-Driven Design, collaborative domain modeling, microservices architecture design. Applied in startup ecosystem exploration, business process improvement, software design workshops. Fundamental for breaking down silos between business and technical teams in complex domain discovery. + +## Related Research + +Connects to (Evans, 2003) on Domain-Driven Design principles, (Vernon, 2013) on implementing DDD. Part of broader collaborative modeling approaches alongside Design Thinking and Lean Startup methodologies. Related to workshop facilitation techniques and business process modeling frameworks. \ No newline at end of file diff --git a/docs/research/information-science/domain-modeling/evans_2003.md b/docs/research/information-science/domain-modeling/evans_2003.md new file mode 100644 index 00000000..5d415bd5 --- /dev/null +++ b/docs/research/information-science/domain-modeling/evans_2003.md @@ -0,0 +1,38 @@ +# Domain-Driven Design (Evans, 2003) + +## Citation + +Evans, E. (2003). *Domain-Driven Design: Tackling Complexity in the Heart of Software*. Addison-Wesley. +URL: https://www.domainlanguage.com/ddd/ + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +Complex software must be built around shared domain model - a ubiquitous language used by both domain experts and developers in conversation, code, and documentation. + +## Core Findings + +1. **Ubiquitous Language**: Single terminology shared between domain experts and developers eliminates translation costs and catches misunderstandings early +2. **Bounded Contexts**: Define where terms have single meaning, preventing incoherent unified models when terms mean different things in different subdomains +3. **Aggregates**: Define transactional consistency boundaries - all invariants within aggregate must hold after each operation +4. **Context Mapping Patterns**: Upstream/Downstream, Anti-corruption Layer, Conformist, Open-host Service define how separate bounded contexts interact +5. **Strategic vs. Tactical Design**: Strategic focuses on bounded contexts and context mapping; tactical focuses on entities, value objects, services + +## Mechanism + +Ubiquitous language eliminates translation costs between domain experts and developers. When "Order" means same thing in conversation and code, misunderstandings are caught early. Bounded contexts prevent alternative unified model becoming incoherent. Aggregates enforce transactional consistency boundaries with operations spanning aggregates accepting eventual consistency. + +## Relevance + +Essential for complex software architecture, microservices design, team organization, domain modeling. Applied in enterprise software development, distributed systems architecture. Foundational for strategic system design aligning technical implementation with business domains and expert knowledge. + +## Related Research + +Connects to (Brandolini, 2012) on Event Storming for domain discovery, (Vernon, 2013) on DDD implementation. Part of broader software architecture approaches alongside microservices, CQRS, event sourcing. Related to Conway's Law and team topologies for organizational design. \ No newline at end of file diff --git a/docs/research/information-science/domain-modeling/vernon_2013.md b/docs/research/information-science/domain-modeling/vernon_2013.md new file mode 100644 index 00000000..4f37bab9 --- /dev/null +++ b/docs/research/information-science/domain-modeling/vernon_2013.md @@ -0,0 +1,38 @@ +# Implementing Domain-Driven Design (Vernon, 2013) + +## Citation + +Vernon, V. (2013). *Implementing Domain-Driven Design*. Addison-Wesley. +URL: https://www.informit.com/store/implementing-domain-driven-design-9780321834577 + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Context mapping provides nine inter-context relationship patterns describing how bounded contexts relate to each other, preventing model pollution and reducing integration friction. + +## Core Findings + +1. **Nine Context Mapping Patterns**: Shared Kernel, Customer-Supplier, Conformist, Anticorruption Layer, Separate Ways, Open Host Service, Published Language, Big Ball of Mud, Partnership +2. **Relationship Trade-offs**: Each pattern carries specific coordination costs and risk implications requiring careful selection +3. **Pattern Selection Guidance**: Use ACL when downstream has limited influence; Customer-Supplier when teams can negotiate; Open Host Service for many standardized consumers +4. **Social Contract Explicit**: Context maps make team relationships, obligations, and constraints transparent +5. **Practical DDD Implementation**: Extends Evans' foundational work with concrete implementation patterns and guidance + +## Mechanism + +Context mapping makes social and technical contracts between teams explicit. Customer-Supplier demands upstream awareness; Conformist accepts upstream dominance; Anticorruption Layer isolates from model drift. Named relationships clarify obligations and constraints, preventing accidental coupling and model contamination. + +## Relevance + +Essential for microservices architecture, distributed systems design, team organization. Applied in bounded context definition, API design, organizational patterns. Critical for implementing DDD at scale in complex enterprise environments with multiple development teams. + +## Related Research + +Vaughn Vernon builds on (Evans, 2003) foundational DDD work. Author of "Reactive Messaging Patterns with the Actor Model" (2015), "Domain-Driven Design Distilled" (2016). Leading DDD practitioner and educator providing concrete implementation guidance for Evans' theoretical framework. diff --git a/docs/research/psychology/cognitive/fisher_geiselman_1987.md b/docs/research/psychology/cognitive/fisher_geiselman_1987.md new file mode 100644 index 00000000..8e6a333f --- /dev/null +++ b/docs/research/psychology/cognitive/fisher_geiselman_1987.md @@ -0,0 +1,40 @@ +# The Enhanced Cognitive Interview (Fisher & Geiselman, 1987) + +## Citation + +Fisher, R. P., & Geiselman, R. E. (1987). "Enhancing enhanced eyewitness memory: Refining the cognitive interview." *Journal of Police Science and Administration*, 15, 291-297. (Enhanced version of original 1984 cognitive interview) +URL: https://en.wikipedia.org/wiki/Cognitive_interview + +## Method + +Experiment + +## Confidence + +High + +## Key Insight + +The enhanced Cognitive Interview elicits approximately 35% more correct information than standard interviews with equal accuracy rates. + +## Core Findings + +1. **Four retrieval mnemonics**: (1) Mental reinstatement of context, (2) Report everything, (3) Temporal reversal, (4) Perspective change - each opens different memory access routes. +2. **Enhanced version improvements**: 45% increase in correct information over original CI through better interview structure and social dynamics. +3. **Equal accuracy rates**: 85% accuracy for CI vs 82% for standard interviews - more information without sacrificing reliability. +4. **Encoding specificity leverage**: Context reinstatement increases memory availability by overlapping retrieval cues with original encoding conditions. +5. **Multi-component memory access**: Different retrieval routes surface information that direct questions cannot access. +6. **Field effectiveness**: Real police officers trained in CI gather significantly more accurate information from actual crime witnesses. + +## Mechanism + +Four retrieval mnemonics open different memory access routes, collectively surfacing what direct questions cannot reach. Mental reinstatement leverages encoding specificity principle - memories encoded with environmental/emotional context become accessible when similar context is recreated. "Report everything" and perspective changes tap the multi-component view of memory, accessing different aspects of the complex memory trace through alternative retrieval pathways. + +## Relevance + +Foundational technique for investigative interviewing, user research, and requirements gathering. Widely adopted by police departments, private investigators, and attorneys. The principles apply to any situation requiring complete information extraction: incident analysis, post-mortem reviews, and stakeholder interviews where comprehensive recall is essential. + +## Related Research + +- (Tulving & Thomson, 1973): Encoding specificity principle underlying context reinstatement +- (Flanagan, 1954): Critical incident technique as complementary approach to incident-based recall diff --git a/docs/research/psychology/cognitive/flanagan_1954.md b/docs/research/psychology/cognitive/flanagan_1954.md new file mode 100644 index 00000000..b48df92f --- /dev/null +++ b/docs/research/psychology/cognitive/flanagan_1954.md @@ -0,0 +1,40 @@ +# The Critical Incident Technique (Flanagan, 1954) + +## Citation + +Flanagan, J. C. (1954). "The critical incident technique." *Psychological Bulletin*, 51(4), 327–357. https://doi.org/10.1037/h0061470 +URL: https://doi.org/10.1037/h0046049 + +## Method + +Observational + +## Confidence + +High + +## Key Insight + +Anchoring an interview on a specific past incident breaks schema-based recall, revealing real workarounds, edge cases, and failure modes that never surface when asked "how does this usually work?" + +## Core Findings + +1. **Direct observations of critical behavior**: CIT focuses on specific incidents where the purpose and consequences are clear, avoiding generalized schema-based responses. +2. **Schema bypass mechanism**: Direct questions elicit sanitized mental models of "how things should work," while incidents access episodic memory anchored to specific sensory and emotional details. +3. **Flexible data collection**: Method allows participants to describe experiences in their own words without forcing them into predetermined frameworks. +4. **Rare event identification**: CIT captures uncommon but significant events that routine methods miss by focusing only on everyday patterns. +5. **Practical problem solving**: Originally developed for Aviation Psychology Program during WWII to identify pilot errors and improve training/systems design. +6. **Wide applicability**: Successfully used in healthcare, organizational development, market research, and information-seeking behavior studies. + +## Mechanism + +Direct questions elicit the stakeholder's mental schema: a sanitized, gap-free description of how things should work. Critical incidents bypass the schema because episodic memory is anchored to specific sensory and emotional detail. The technique requires incidents to be "sufficiently complete" and "critical" (making positive or negative contribution) where purpose and consequences are clear to the observer. + +## Relevance + +Foundational technique for requirements gathering, user research, and system design. Essential for uncovering actual user behaviors, workarounds, and failure modes that structured interviews miss. Widely adopted in UX research, safety analysis, and organizational problem-solving where understanding real-world behavior patterns is crucial. + +## Related Research + +- (Bitner, Booms & Tetreault, 1990): Service encounter satisfaction research using CIT +- (Klein, 1998): Recognition-primed decision making and naturalistic observation methods diff --git a/docs/research/psychology/cognitive/hattie_timperley_2007.md b/docs/research/psychology/cognitive/hattie_timperley_2007.md new file mode 100644 index 00000000..7050dd79 --- /dev/null +++ b/docs/research/psychology/cognitive/hattie_timperley_2007.md @@ -0,0 +1,41 @@ +# The Power of Feedback (Hattie & Timperley, 2007) + +## Citation + +Hattie, J., & Timperley, H. (2007). "The power of feedback." *Review of Educational Research*, 77(1), 81–112. https://doi.org/10.3102/003465430298487 +URL: https://doi.org/10.3102/003465430298487 + +## Method + +Meta-analysis + +## Confidence + +High + +## Key Insight + +Feedback is most effective when it tells the agent exactly what went wrong and what the correct action is. "FAIL: function > 20 lines at file:47" is actionable; "Apply function length rules" is not. + +## Core Findings + +1. **Feedback power**: Among the most powerful influences on learning and achievement, but impact can be positive or negative depending on type and delivery. +2. **Specific feedback superiority**: Task-specific feedback that identifies exact errors and correct actions is significantly more effective than general comments. +3. **Four feedback levels**: Task level (correctness), process level (strategies), self-regulation level (monitoring), and self level (personal praise), with task and process being most effective. +4. **Three key questions framework**: "Where am I going?" (goals), "How am I going?" (progress), "Where to next?" (improvement strategies). +5. **Timing effects**: Immediate feedback works best for procedural tasks, delayed feedback for complex learning requiring reflection. +6. **Cognitive load management**: Effective feedback reduces rather than increases cognitive burden by providing clear direction. + +## Mechanism + +Specific feedback creates a direct mapping between error and correction, reducing cognitive load by eliminating interpretation steps. Vague feedback requires the recipient to infer what went wrong, which introduces interpretation errors and reduces action likelihood. The model emphasizes reducing gaps between current performance and goals through precise, actionable information. + +## Relevance + +Foundational for automated feedback systems, code review processes, and instructional design. Critical for any system providing performance feedback, from linting tools to learning management systems. The specificity principle directly applies to error messaging, validation feedback, and progress indicators in software interfaces. + +## Related Research + +- (Black & Wiliam, 1998): Formative assessment and feedback loops in learning +- (Kulhavy & Stock, 1989): Feedback timing and learning effectiveness +- (Kluger & DeNisi, 1996): Feedback intervention theory diff --git a/docs/research/psychology/cognitive/reynolds_gutman_1988.md b/docs/research/psychology/cognitive/reynolds_gutman_1988.md new file mode 100644 index 00000000..8f3383ed --- /dev/null +++ b/docs/research/psychology/cognitive/reynolds_gutman_1988.md @@ -0,0 +1,40 @@ +# Laddering Theory / Means-End Chain (Reynolds & Gutman, 1988) + +## Citation + +Reynolds, T. J., & Gutman, J. (1988). "Laddering theory, method, analysis, and interpretation." *Journal of Advertising Research*, 28(1), 11–31. DOI: 10.1080/00218499.1988.12467766. [Highly cited: 3,779+ citations] +URL: https://doi.org/10.4324/9781410600844-9 + + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +The laddering technique reveals that the stakeholder's first answer about what they want is rarely the real constraint. Repeatedly asking "Why is that important to you?" climbs from surface attributes to deeper motivational values. + +## Core Findings + +1. **Means-end chain structure**: Concrete attribute → functional consequence → psychosocial consequence → terminal value represents four levels of consumer motivation. +2. **Progressive revelation**: Stakeholders typically start with concrete attributes but the real decision drivers lie at the consequence and value levels. +3. **Value conflict identification**: Stakeholders whose surface requirements look identical often have ladders that diverge at the consequence level, revealing hidden conflicts. +4. **Interview methodology**: Systematic probing with "Why is that important?" uncovers deeper motivational structures that traditional surveys miss. +5. **Advertising applications**: Understanding means-end chains enables more effective positioning by connecting product features to personal values. + +## Mechanism + +The laddering interview technique systematically probes upward through levels of abstraction using "Why is that important to you?" prompts. Each level reveals different types of motivation: attributes (what the product has), functional consequences (what it does), psychosocial consequences (how it makes you feel/appear), and values (what life goals it serves). This climbing process reveals the complete motivational pathway. + +## Relevance + +Essential technique for requirements gathering, user research, and stakeholder analysis. Helps product managers, UX researchers, and business analysts uncover the true drivers behind stated requirements. Critical for avoiding surface-level solutions that miss deeper user needs and organizational goals. + +## Related Research + +- (Rokeach, 1973): Values theory underlying the terminal value concept +- (Gutman, 1982): Original means-end chain model foundation diff --git a/docs/research/psychology/cognitive/tversky_kahneman_1974.md b/docs/research/psychology/cognitive/tversky_kahneman_1974.md new file mode 100644 index 00000000..d5960a9f --- /dev/null +++ b/docs/research/psychology/cognitive/tversky_kahneman_1974.md @@ -0,0 +1,39 @@ +# Judgment Under Uncertainty: Heuristics and Biases (Tversky & Kahneman, 1974) + +## Citation + +Tversky, A., & Kahneman, D. (1974). Judgment under uncertainty: Heuristics and biases. *Science*, 185(4157), 1124-1131. https://doi.org/10.1126/science.185.4157.1124 +URL: https://doi.org/10.1126/science.185.4157.1124 + +## Method + +Experiment + +## Confidence + +High + +## Key Insight + +People use mental shortcuts (heuristics) that systematically bias judgment under uncertainty. + +## Core Findings + +1. People rely on three main heuristics when making judgments under uncertainty: representativeness, availability, and anchoring and adjustment. +2. Representativeness heuristic: People judge probability by similarity to mental prototypes, ignoring base rates and sample size. +3. Availability heuristic: People assess probability by how easily examples come to mind, biasing toward memorable or recent events. +4. Anchoring and adjustment: People adjust insufficiently from initial values, even when the anchor is irrelevant. +5. These heuristics are useful but lead to severe and systematic errors in prediction and judgment. + +## Mechanism + +Heuristics serve as cognitive shortcuts that reduce complex probability assessments to simpler judgmental operations. However, they rely on selective accessibility of information rather than comprehensive analysis. Anchoring activates associative networks around initial values, making adjustment insufficient. Availability conflates memorability with frequency. Representativeness ignores statistical principles in favor of similarity matching. + +## Relevance + +Foundational for understanding cognitive biases in decision-making processes. Critical for designing systems that account for human judgment limitations. Directly applicable to forecast accuracy, risk assessment, and quality control processes where human judgment is involved. + +## Related Research + +- (Kahneman, 2011): System 1 vs System 2 thinking framework +- (Gilovich, Griffin & Kahneman, 2002): Heuristics and biases comprehensive review diff --git a/docs/research/psychology/social/rogers_farson_1957.md b/docs/research/psychology/social/rogers_farson_1957.md new file mode 100644 index 00000000..2624fa78 --- /dev/null +++ b/docs/research/psychology/social/rogers_farson_1957.md @@ -0,0 +1,40 @@ +# Active Listening (Rogers & Farson, 1957) + +## Citation + +Rogers, C. R., & Farson, R. E. (1957). "Active Listening." Industrial Relations Center, University of Chicago. Reprinted in Newman, R. G., Danziger, M. A., & Cohen, M. (1987). *Communicating in Business Today*. D.C. Heath & Company. +URL: http://www.ask-force.org/web/Discourse/Rogers-Farson-ActiveListening-1957.pdf + + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +Active listening is a transformative communication technique that creates non-threatening, empathic environments where people feel heard and understood, promoting personal and relational growth. + +## Core Findings + +1. **Three-step process**: Paraphrasing what was heard, asking clarifying questions, then summarizing main points and intent reduces misunderstandings and builds trust. +2. **Therapeutic foundation**: Rooted in Rogers' three facilitative conditions for effective counseling: empathy, genuineness, and unconditional positive regard. +3. **Transformative power**: "Sensitive listening is a most effective agent for individual personality change and group development." +4. **Behavioral outcomes**: People who have been listened to become "more emotionally mature, more open to their experiences, less defensive, more democratic, and less authoritarian." +5. **Active vs. passive**: Despite popular notion that listening is passive, clinical and research evidence shows it actively brings about changes in people's attitudes and values. + +## Mechanism + +Paraphrasing forces the listener to reconstruct the speaker's meaning, immediately surfacing gaps in understanding. Clarifying questions address residual ambiguity. Summarizing creates a shared record that both parties can confirm or correct. This process establishes empathic connection and creates psychological safety for the speaker to be vulnerable and authentic. + +## Relevance + +Foundational communication technique applicable across therapeutic, business, educational, and interpersonal contexts. Essential skill for leaders, counselors, managers, and anyone seeking to build trust and understanding in human relationships. Forms the basis for modern conflict resolution and negotiation strategies. + +## Related Research + +- (Gottman, 1999): Critique of active listening effectiveness in marriage therapy +- (McNaughton et al., 2008): LAFF strategy development for educational contexts diff --git a/docs/research/psychology/social/tetlock_1985.md b/docs/research/psychology/social/tetlock_1985.md new file mode 100644 index 00000000..7df473c2 --- /dev/null +++ b/docs/research/psychology/social/tetlock_1985.md @@ -0,0 +1,38 @@ +# Accountability: A Social Check on the Fundamental Attribution Error (Tetlock, 1985) + +## Citation + +Tetlock, P. E. (1985). Accountability: A social check on the fundamental attribution error. *Social Psychology Quarterly*, 48(3), 227-236. +URL: https://doi.org/10.1037/0003-066X.40.12.1370 + +## Method + +Experiment + +## Confidence + +High + +## Key Insight + +Anticipating accountability to an unknown audience improves reasoning quality and reduces attribution errors. + +## Core Findings + +1. Accountability to an unknown audience with unknown views improves reasoning quality compared to no accountability conditions. +2. People anticipating being audited adjust their reasoning to be more careful and systematic. +3. Accountability reduces the fundamental attribution error - the tendency to overemphasize personality-based explanations while underemphasizing situational factors. +4. The effect is stronger when people don't know what position they'll be expected to defend. + +## Mechanism + +When people expect to justify their judgments to others, they engage in more effortful, systematic processing. The anticipation of having to explain one's reasoning to an unknown audience motivates more careful consideration of multiple perspectives and evidence, leading to less biased judgments. + +## Relevance + +Critical for review processes and agent design. Creating accountability structures (like APPROVED/REJECTED with evidence requirements) prompts more careful analysis. Unknown audience accountability is particularly powerful because reviewers can't game their response to please a specific viewpoint. + +## Related Research + +- (Kahneman, 2011): System 1 vs System 2 thinking and cognitive biases +- (Lerner & Tetlock, 1999): Comprehensive review of accountability effects on judgment diff --git a/docs/research/software-engineering/process/fagan_1976.md b/docs/research/software-engineering/process/fagan_1976.md new file mode 100644 index 00000000..382d5c6c --- /dev/null +++ b/docs/research/software-engineering/process/fagan_1976.md @@ -0,0 +1,38 @@ +# Design and Code Inspections (Fagan, 1976) + +## Citation + +Fagan, M. E. (1976). "Design and Code Inspections to Reduce Errors in Program Development." *IBM Systems Journal*, 15(3), 182–211. +URL: https://en.wikipedia.org/wiki/Fagan_inspection + +## Method + +Experiment + +## Confidence + +High + +## Key Insight + +Structured inspections using checklists detect 60-90% of defects before testing, far more than unstructured walkthroughs by forcing reviewers to articulate specific failures. + +## Core Findings + +1. **Defect Detection Rate**: Structured inspections detect 60-90% of defects before testing phase +2. **Cost Effectiveness**: Fixing defects in early phases costs 10-100x less than fixing in maintenance phase +3. **Six-Phase Process**: Planning, Overview, Preparation, Inspection meeting, Rework, Follow-up +4. **Role-Based Review**: Author, Reader, Reviewers, Moderator, Recorder each have specific responsibilities +5. **Checklist-Driven**: Systematic checking against specific quality attributes prevents confirmation bias + +## Mechanism + +Fagan inspections constrain reviewer attention to overcome confirmation bias. Unstructured reviews allow skimming and overlooking defects through expectation confirmation. Structured inspection requires checking each quality attribute individually, forcing System 2 thinking. Self-declaration checklists (AGREE/DISAGREE criteria) prevent vague "looks good" approvals that hide defects. + +## Relevance + +Essential for code quality assurance, defect prevention, software inspection processes. Applied in formal review procedures, quality gates, peer review systems. Foundational for static analysis, code review practices, and quality assurance in software development lifecycle. + +## Related Research + +Connects to (Tversky & Kahneman, 1974) on confirmation bias, (Kahneman, 2011) on System 1/2 thinking. Part of broader software quality methodologies alongside testing, static analysis. Related to inspection techniques, peer review processes, and formal verification approaches. \ No newline at end of file diff --git a/docs/research/software-engineering/process/gotel_cleland_huang_2012.md b/docs/research/software-engineering/process/gotel_cleland_huang_2012.md new file mode 100644 index 00000000..0907763e --- /dev/null +++ b/docs/research/software-engineering/process/gotel_cleland_huang_2012.md @@ -0,0 +1,37 @@ +# Software and Systems Traceability (Cleland-Huang, Gotel & Zisman, 2012) + +## Citation + +Cleland-Huang, J., Gotel, O. & Zisman, A. (eds.) (2012). *Software and Systems Traceability.* Springer. ISBN 978-1-4471-2238-8 (print) / 978-1-4471-2239-5 (ebook). 494 pages. DOI 10.1007/978-1-4471-2239-5. +URL: https://link.springer.com/book/10.1007/978-1-4471-2239-5 + +## Method + +Edited academic reference volume. + +## Confidence + +High — the canonical reference on software traceability. + +## Key Insight + +A traceability matrix correlates two baselined artifacts many-to-many by marking intersecting cells; an empty row or column is a gap (no relationship), and a densely filled cell is over-complexity to simplify — and it must be built as the work proceeds, not reconstructed at the end. + +## Core Findings + +1. A trace is a relationship between two artifacts (a requirement and its test, a design and its code). +2. The matrix maps requirements forward to design, code, and test; coverage is read off the marked cells. +3. An empty row (a requirement with no test) is a gap; an empty column (a test with no requirement) is an orphan; a dense cell signals over-complexity. +4. Traceability captured during the work survives; traceability reconstructed afterward does not. + +## Mechanism + +The matrix is a grid whose rows and columns are two artifact sets and whose cells record the existence of a relationship; reading the grid's empties surfaces what was forgotten, and reading its density surfaces what was over-built. Because the traces degrade the moment they are divorced from the act of building, the matrix is maintained as a by-product of the work rather than as a separate documentation task. + +## Relevance + +Grounds gap analysis as a coverage matrix at the building-blocks funnel level: every bounded context maps to at least one building block, every quality attribute to at least one — the empties are elicited into rather than silently filled. + +## Related Research + +- Wiegers (Software Requirements — the RTM as a requirements-management tool) diff --git a/docs/research/software-engineering/process/jeffries_anderson_hendrickson_2000.md b/docs/research/software-engineering/process/jeffries_anderson_hendrickson_2000.md new file mode 100644 index 00000000..cfca64f5 --- /dev/null +++ b/docs/research/software-engineering/process/jeffries_anderson_hendrickson_2000.md @@ -0,0 +1,42 @@ +# Extreme Programming Installed (Jeffries, Anderson & Hendrickson, 2000) + +## Citation + +Jeffries, R., Anderson, A. & Hendrickson, C. (2000). *Extreme Programming Installed.* Addison-Wesley Professional (XP Series), published 16 Oct 2000 (copyright 2001). ISBN 0-201-70842-6 (ISBN-13 978-0-201-70842-4). 288 pages. Foreword by Kent Beck. +URL: https://www.informit.com/store/extreme-programming-installed-9780201708424 + +## Method + +Practitioner book; connected collection of essays by three participants in the DaimlerChrysler (C3) XP project. + +## Confidence + +High — a primary XP source. + +## Key Insight + +XP's practices — test-first, simple design, continuous refactoring, small releases, pair programming — co-evolve; the simplest design that could possibly work, built test-first and refactored as understanding grows, beats speculative generality bought against an uncertain future. + +## Core Findings + +1. Write the test first, by intention; it drives both the interface and the confidence to change the code later. +2. Implement the simplest thing that could possibly pass the test. +3. Refactor continuously — improve structure under green tests, every cycle. +4. You Aren't Gonna Need It: do not build for a future the present test does not justify. + +## Mechanism + +Test-first forces a statement of intent before the implementation, which produces interfaces a caller actually wants; simple design keeps the code legible so the next change is cheap; continuous refactoring pays down the design debt that simple-design-for-today accrues; YAGNI blocks the speculative structure that would otherwise accumulate. The practices reinforce one another, so dropping one weakens the rest. + +## Relevance + +Grounds the YAGNI and simple-design discipline cited in the workflow's design decisions: KISS/YAGNI first, the simplest structure that removes the smell, no speculative patterns. + +## Note on the citation + +Earlier knowledge citations read "Beck & Jeffries 1999", which is inaccurate: Kent Beck is not an author of this book (he wrote the foreword). Beck's own XP work is *Extreme Programming Explained: Embrace Change* (Addison-Wesley, 1999, ISBN 0-201-61641-6) — a different book. Citations in the knowledge files should read "Jeffries, Anderson & Hendrickson 2000" for this work, or "Beck 1999" if *XP Explained* was the intended source. + +## Related Research + +- Beck 2002 (test-driven development) +- Fowler 1999 (refactoring) diff --git a/docs/research/software-engineering/process/niessen_2026.md b/docs/research/software-engineering/process/niessen_2026.md new file mode 100644 index 00000000..c30c5926 --- /dev/null +++ b/docs/research/software-engineering/process/niessen_2026.md @@ -0,0 +1,30 @@ +# The 12-Factor App, 15 Years Later (Niessen, 2026) + +## Citation +Niessen, L. (2026). "The 12-Factor App — 15 Years Later. Does it Still Hold Up in 2026?" *ITNEXT*, 12 February 2026. +URL: https://itnext.io/the-12-factor-app-15-years-later-does-it-still-hold-up-in-2026-c8af494e8465 + +## Method +Practitioner reassessment (independent retrospective on the twelve-factor methodology). + +## Confidence +Medium-High — the author's claims corroborate Heigh (2023) and the Kubernetes SIG guidance. + +## Key Insight +The core principle — separate configuration from code, with the same artifact plus config equalling a deployment — remains sound; the literal prescription to use environment variables exclusively shows its age, because env vars leak into logs, crash dumps, child processes, and `/proc`. + +## Core Findings +1. The config factor is overly specific about environment variables as the mechanism. +2. For sensitive configuration, files mounted outside the process environment are preferable to env vars. +3. Kubernetes models this as ConfigMaps and Secrets, mountable as either env vars or files. +4. GitOps keeps the configuration-of-record in a separate Git repository; injection still happens at deploy time. +5. The underlying idea (separate config from code) is as solid as ever; only the "env vars only" literalism dates it. + +## Mechanism +Env vars share exposure paths the original twelve-factor author did not weigh: process-tree inheritance, `/proc/<pid>/environ`, and capture by observability tooling. A file mounted into the container/filesystem without being placed in the process environment — or a secrets manager returning a value on demand — removes those paths while preserving the config/code separation that is the actual point of the factor. + +## Relevance +Grounds the "files over env vars" insight and the "twelve-factor predates the critique" framing in `secrets-and-config`. It legitimizes the out-of-workspace `~/.secrets/<project>.env` file (a config file mounted outside the process environment, read with `dotenv_values`) as the modern reading of the config factor for the secret case. + +## Related Research +Wiggins, 2011; Heigh, 2023; env.dev, 2026. diff --git a/docs/research/software-engineering/process/wiggins_2011.md b/docs/research/software-engineering/process/wiggins_2011.md new file mode 100644 index 00000000..bdea3035 --- /dev/null +++ b/docs/research/software-engineering/process/wiggins_2011.md @@ -0,0 +1,29 @@ +# The Twelve-Factor App — Config (Wiggins, 2011) + +## Citation +Wiggins, A. (2011). "The Twelve-Factor App — III. Config." 12factor.net. +URL: https://12factor.net/config + +## Method +Methodology / practitioner guideline (the Heroku-era twelve-factor codification). + +## Confidence +High — foundational and widely cited across languages and platforms. + +## Key Insight +Configuration that varies between deploys belongs in environment variables, kept strictly separate from code; the same code artifact runs across every deploy, with config injected at run time. + +## Core Findings +1. An app factors as code (the same across deploys) plus config (what varies). +2. Environment variables are the universal, language- and OS-agnostic config interface. +3. Config must never be checked into version control alongside code. +4. The separation preserves deploy portability and lets the same artifact run dev/staging/prod. + +## Mechanism +The config factor draws the boundary at the process environment: the deploy platform (or the developer's shell) injects variables, and the application reads them through the standard library (`os.environ`, `process.env`). Code stays deploy-agnostic; deploy-specifics live entirely in the surrounding environment. This predates and enables the entire modern config-injection surface (Docker `-e`, Kubernetes ConfigMaps/Secrets, serverless env). + +## Relevance +Grounds the twelve-factor baseline in `secrets-and-config`: the principle that non-secret configuration belongs in environment variables. The knowledge splits this from secrets because the original prescription predates the modern critique of `os.environ` as a secret store (see Heigh, 2023; Niessen, 2026) — the principle (separate config from code) holds; the literal mechanism (everything in env vars) does not, for secrets. + +## Related Research +Heigh, 2023; Niessen, 2026; env.dev, 2026. diff --git a/docs/research/software-engineering/quality/bay_2008.md b/docs/research/software-engineering/quality/bay_2008.md new file mode 100644 index 00000000..b6091d4a --- /dev/null +++ b/docs/research/software-engineering/quality/bay_2008.md @@ -0,0 +1,39 @@ +# Object Calisthenics (Bay, 2008) + +## Citation + +Bay, J. (2008). "Object Calisthenics." In *The ThoughtWorks Anthology*, pp. 65–78. Pragmatic Bookshelf. +URL: https://www.thoughtworks.com/books/thoughtworks-anthology + +## Method + +Theoretical + +## Confidence + +Moderate + +## Key Insight + +Nine syntactic constraints force developers to distribute behavior rather than centralize data, producing significantly better object-oriented designs through structural pressure. + +## Core Findings + +1. **Extreme constraints methodology**: Nine rules including "no more than two instance variables per class" and "no getters/setters/properties" create structural pressure toward better designs. +2. **Anti-pattern prevention**: "No more than two instance variables" prevents god-object anti-pattern by making it impossible to hold all related data in one class, forcing decomposition into collaborating objects. +3. **Training wheels philosophy**: Constraints are intentionally extreme - they are temporary training tools, not permanent rules - but design habits they produce persist after constraints are relaxed. +4. **Behavior distribution**: Forces small, focused classes with clear responsibilities and behavior-rich objects rather than data containers. +5. **ThoughtWorks methodology**: Published as part of ThoughtWorks Anthology, reflecting company's agile software development practices and expertise. + +## Mechanism + +Constraints create structural pressure toward small, focused classes with clear responsibilities. Extreme limitations make poor design choices impossible, forcing developers to find alternative approaches that result in better object-oriented structure. Design habits developed under constraints (small classes, behavior-rich objects, encapsulated data) persist after constraints are relaxed. + +## Relevance + +Valuable training methodology for developing better object-oriented design skills. Useful for teams struggling with large classes, anemic domain models, or excessive coupling. Educational tool for understanding principles behind good OOP design through extreme application. + +## Related Research + +- (Martin, 2000): SOLID principles providing theoretical foundation for good OOP design +- (Fowler, 1999): Refactoring techniques for improving object-oriented design incrementally \ No newline at end of file diff --git a/docs/research/software-engineering/quality/beck_2002.md b/docs/research/software-engineering/quality/beck_2002.md new file mode 100644 index 00000000..0955d0a8 --- /dev/null +++ b/docs/research/software-engineering/quality/beck_2002.md @@ -0,0 +1,41 @@ +# Test-Driven Development (Beck, 2002) + +## Citation + +Beck, K. (2002). *Test-Driven Development: By Example*. Addison-Wesley. +URL: https://en.wikipedia.org/wiki/Test-driven_development + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +The RED-GREEN-REFACTOR cycle (write a failing test, write the minimum code to pass it, then improve the structure while keeping all tests green) drives better design by forcing each unit of behaviour to be specified before it is implemented. + +## Core Findings + +1. Tests written first act as specifications, not verification, preventing over-engineering and ensuring every piece of code has a reason to exist +2. The RED phase forces developers to articulate what they want before building it +3. The GREEN phase constrains implementation to the minimum that satisfies the specification, preventing speculative generalisation +4. The REFACTOR phase is safe because all existing tests remain green, providing a regression net +5. The cycle produces small, focused, well-tested units of code because each unit must be both specifiable (testable) and minimal (just enough to pass) +6. Two basic rules: (1) Never write a single line of code unless you have a failing automated test, (2) Eliminate duplication + +## Mechanism + +TDD works by inverting the traditional development flow. Instead of writing code then testing it, developers first write failing tests that specify desired behavior. This forces clear thinking about requirements and interfaces before implementation. The requirement to make tests pass with minimal code prevents over-engineering, while the refactoring phase improves design quality under the safety net of comprehensive test coverage. + +## Relevance + +Foundational methodology for software quality assurance and design. TDD has become a cornerstone practice in agile development, influencing modern software engineering through improved code quality, better design, and increased developer confidence in changes. Essential for understanding test-first approaches and the relationship between testing and design. + +## Related Research + +- (Beck, 1999) - Extreme Programming Explained, which introduced TDD as part of XP practices +- (Fowler et al., 1999) - Refactoring book co-authored by Beck, providing systematic approach to code improvement +- (Beck & Gamma, 2004) - JUnit framework implementation demonstrating TDD principles in practice \ No newline at end of file diff --git a/docs/research/software-engineering/quality/env_dev_2026.md b/docs/research/software-engineering/quality/env_dev_2026.md new file mode 100644 index 00000000..6641a9ec --- /dev/null +++ b/docs/research/software-engineering/quality/env_dev_2026.md @@ -0,0 +1,33 @@ +# Environment Variable Best Practices & Security (env.dev, 2026) + +## Citation +env.dev (2026). "Environment Variable Best Practices" (29 April 2026) and "Env Variables Security: Secrets, Leaks & Best Practices" (12 April 2026). +URL: https://env.dev/guides/env-vars-best-practices · https://env.dev/guides/env-vars-security + +## Method +Editorial / practitioner reference (site), grounded in cited incidents (Toyota 2017–2022, Uber 2022) and the GitGuardian 2024 State of Secrets Sprawl report. + +## Confidence +High — concrete, incident-referenced; the hygiene rules recur across independent sources. + +## Key Insight +Environment variables are the universal configuration interface and one of the largest single sources of production secret leaks; a small set of unglamorous, well-documented hygiene rules prevents most incidents. + +## Core Findings +1. `.gitignore` `.env`, `.env.local`, `*.pem`, `*.key` from the first commit, not after. +2. Run a pre-commit secret scanner (gitleaks, detect-secrets, git-secrets) as a mandatory hook. +3. Validate every required variable at startup (fail-fast with a clear error). +4. Wrap env access in a typed configuration object; do not scatter raw `os.environ` reads. +4. `.env` is for local development only — no encryption at rest, no ACL, no audit, no rotation. +5. `chmod 600 .env`; never `COPY .env .` into a build artifact. +6. If a secret was committed, rotate immediately — history scrubbing cannot un-leak. +7. The maturity ladder: plain `.env` → encrypted files (SOPS, git-crypt) → dedicated secrets manager. + +## Mechanism +Each rule maps to a real failure mode: the gitignore rule to the committed-key incident; the scanner to the same; fail-fast to the cryptic late-stage crash; the typed wrapper to un-auditable scattered access; the no-production rule to the plaintext-on-disk liability. Together they shrink the surface at every stage from authoring to deployment. + +## Relevance +Grounds the hygiene layer (fail-fast validation, typed Settings, `.env.example` as the committed contract, the gitleaks CI step) and the maturity ladder in `secrets-and-config`. + +## Related Research +Heigh, 2023; Wiggins, 2011; young_gao, 2026; Niessen, 2026. diff --git a/docs/research/software-engineering/quality/fowler_1999.md b/docs/research/software-engineering/quality/fowler_1999.md new file mode 100644 index 00000000..996172dc --- /dev/null +++ b/docs/research/software-engineering/quality/fowler_1999.md @@ -0,0 +1,39 @@ +# Refactoring: Improving the Design of Existing Code (Fowler, 1999) + +## Citation + +Fowler, M. (1999). *Refactoring: Improving the Design of Existing Code*. Addison-Wesley. Second edition 2018 with K. Beck, J. Brant, W. Opdyke, D. Roberts. +URL: https://martinfowler.com/books/refactoring.html + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Refactoring is disciplined technique for restructuring existing code without changing external behavior, done in small steps each verified by tests. + +## Core Findings + +1. **Catalog methodology**: 66 named transformations (Extract Method, Move Field, Replace Conditional with Polymorphism, etc.) each with known pre-condition, mechanic, and effect on code structure. +2. **Code smell diagnostics**: Diagnostic indicators (Long Method, Feature Envy, Switch Statements, etc.) signal when refactoring is needed and point to specific techniques. +3. **Test-driven safety**: Small, test-verified steps ensure restructuring doesn't introduce bugs while improving design quality. +4. **Behavior preservation**: External functionality remains unchanged while internal structure improves through systematic transformations. +5. **Design emergence**: Better design emerges through incremental improvements rather than upfront architectural decisions. + +## Mechanism + +Each refactoring has known pre-condition (when safe to apply), step-by-step mechanic (the transformation), and guaranteed post-condition (what improves). By applying refactorings in small, test-verified steps, developer can restructure code safely without introducing bugs. Code smells serve as diagnostic indicators pointing to specific refactoring technique most likely to improve structure. The smell identifies problem; refactoring provides solution. + +## Relevance + +Foundational methodology for systematic code improvement and design evolution. Essential practice for maintaining code quality, reducing technical debt, and enabling sustainable software development. Widely adopted as core agile development practice. + +## Related Research + +- (Beck, 2002): Test-driven development methodology supporting refactoring safety +- (Shvets, 2014): Comprehensive online refactoring catalog building on Fowler's work \ No newline at end of file diff --git a/docs/research/software-engineering/quality/fowler_2006.md b/docs/research/software-engineering/quality/fowler_2006.md new file mode 100644 index 00000000..6b6b2f65 --- /dev/null +++ b/docs/research/software-engineering/quality/fowler_2006.md @@ -0,0 +1,37 @@ +# Ubiquitous Language (Fowler, 2006) + +## Citation + +Fowler, M. (2006). "Ubiquitous Language." *martinfowler.com*, bliki entry. +URL: https://martinfowler.com/bliki/UbiquitousLanguage.html + +## Method + +Practitioner essay; definitional, co-developed with Evans' domain-driven design work. + +## Confidence + +High — Fowler is a canonical source for the term as used in practice. + +## Key Insight + +A single rigorous vocabulary shared across conversation, code, and documentation dissolves the translation cost between domain experts and the software. + +## Core Findings + +1. Build a common language with domain experts rather than translating between a domain vocabulary and a technical one. +2. The language must live in the code — class, method, and variable names carry it. +3. When experts and code disagree, the discrepancy is a signal to change one or the other. + +## Mechanism + +The cost of a separate "technical" vocabulary is the constant translation between how experts describe the domain and how the code describes it; every conversation pays this tax, and every translation is a chance to lose meaning. A ubiquitous language removes the tax by making the two vocabularies one, so a term uttered in a conversation maps without remainder onto the construct that implements it. + +## Relevance + +Grounds the glossary artifact: it is the conquered form of this ubiquitous language, where business language is sharpened into definitions the code can carry. The interview exists to discover the terms; the glossary conquers them into precision. + +## Related Research + +- Evans 2003 (domain-driven design) +- Vernon 2013 (implementing DDD) diff --git a/docs/research/software-engineering/quality/fowler_2014.md b/docs/research/software-engineering/quality/fowler_2014.md new file mode 100644 index 00000000..7b9a2c90 --- /dev/null +++ b/docs/research/software-engineering/quality/fowler_2014.md @@ -0,0 +1,38 @@ +# UnitTest (Fowler, 2014) + +## Citation + +Fowler, M. (2014). "UnitTest." *martinfowler.com*, bliki entry, 5 May 2014 (revised 24 Oct 2014, 9 Mar 2017). +URL: https://martinfowler.com/bliki/UnitTest.html + +## Method + +Definitional practitioner essay; distinguishes two schools of unit testing. + +## Confidence + +High — the canonical statement of the solitary/sociable distinction. + +## Key Insight + +Unit tests divide on the axis of collaborator treatment (solitary replaces them with test doubles, sociable lets the real ones run), not on test size; the "solitary"/"sociable" terms were coined by Jay Fields, and the choice between them is the real divide between the classicist and mockist schools. + +## Core Findings + +1. The "a unit test is small" definition is the wrong axis; "unit" is situational (a class, a cluster, a function). +2. The real axis is solitary (collaborators replaced with doubles) versus sociable (real collaborators exercised) — terms due to Jay Fields. +3. The classicist school (Fowler's) prefers sociable tests, reaching for doubles only at awkward or non-deterministic collaborations; the mockist school insists on solitary. +4. Doubles for external resources (databases, remote services) are a useful guideline for non-determinism and speed, not an absolute rule. + +## Mechanism + +A sociable unit test lets the real object graph run within the test, so a failure traces a real interaction; a solitary test severs that graph so each unit is blamed in isolation. The mockist school argues isolation localises fault and drives design through role interfaces; the classicist school argues real interactions are where defects live and that excessive mocking couples tests to implementation. Fowler's contribution is to name the axis (crediting Fields) rather than legislate the size, so a team chooses on design grounds. + +## Relevance + +Grounds the workflow's two-grain sociable-only policy: integration tests (one boundary/adapter with real internal wiring + replayed cassette) and e2e tests (the full system through the entry point), with no solitary unit tests — the policy follows Fowler's classicist/sociable default. + +## Related Research + +- Meszaros 2007 (xUnit test patterns) +- Fields (Working Effectively with Unit Tests) — origin of the solitary/sociable terms diff --git a/docs/research/software-engineering/quality/gamma_et_al_1994.md b/docs/research/software-engineering/quality/gamma_et_al_1994.md new file mode 100644 index 00000000..4e00bec9 --- /dev/null +++ b/docs/research/software-engineering/quality/gamma_et_al_1994.md @@ -0,0 +1,39 @@ +# Design Patterns: Elements of Reusable Object-Oriented Software (Gamma, Helm, Johnson, Vlissides, 1994) + +## Citation + +Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley. +URL: https://en.wikipedia.org/wiki/Design_Patterns + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Design patterns provide reusable solutions to recurring design problems by naming proven structural approaches that teams can communicate at higher abstraction level. + +## Core Findings + +1. **Pattern catalog**: 23 design patterns divided into three categories by intent: Creational (abstracting object creation), Structural (composing classes/objects into larger structures), Behavioral (allocating responsibility between objects). +2. **Communication abstraction**: Patterns name recurring design structures enabling teams to communicate at higher level - saying "Strategy pattern" conveys entire structural solution. +3. **Problem-solution mapping**: Each pattern captures proven solution to specific class of design problem - Strategy eliminates type-switching, Observer decouples event sources from handlers, State replaces conditional state machines. +4. **Foundational principles**: "Program to interface, not implementation" and "Favor object composition over class inheritance" guide pattern application. +5. **Massive influence**: Over 500,000 copies sold in 14 languages, ACM SIGPLAN Programming Languages Achievement Award 2005, foundational for object-oriented design. + +## Mechanism + +Patterns work by naming recurring design structures so teams can communicate at higher level of abstraction. Each pattern captures proven solution to specific class of design problem. Patterns should be applied only when code smell triggers them, never speculatively. The smell identifies the gap; the pattern provides structural solution. + +## Relevance + +Foundational reference for object-oriented design and software architecture. Essential vocabulary for software development teams and architectural decision-making. Widely adopted across programming languages and frameworks for systematic design improvement. + +## Related Research + +- (Fowler, 1999): Refactoring methodology that prepares code for pattern application +- (Shvets, 2014): Modern catalog connecting code smells to appropriate patterns \ No newline at end of file diff --git a/docs/research/software-engineering/quality/heigh_2023.md b/docs/research/software-engineering/quality/heigh_2023.md new file mode 100644 index 00000000..b23a5437 --- /dev/null +++ b/docs/research/software-engineering/quality/heigh_2023.md @@ -0,0 +1,30 @@ +# Environment Variables Don't Keep Secrets (Heigh, 2023) + +## Citation +Heigh, S. (2023). "Environment Variables Don't Keep Secrets: Best Practices for Plugging Application Credential Leaks." *CyberArk Developer Blog*, 25 January 2023. +URL: https://developer.cyberark.com/blog/environment-variables-dont-keep-secrets-best-practices-for-plugging-application-credential-leaks/ + +## Method +Practitioner article (security-vendor engineering blog). + +## Confidence +High — the leak vectors it names are mechanically verifiable on any Linux host. + +## Key Insight +Environment variables are a convenient but structurally leaky secret store; a credential reachable as an env var is exposed through several well-known, unavoidable vectors, so env vars should not be treated as a secrets-management solution. + +## Core Findings +1. Every process running under the same user can read another's environment. +2. `/proc/<pid>/environ` exposes a process's full environment to the same-user reader. +3. Child processes inherit the entire environment by default. +4. Crash dumps, APM agents, and error trackers routinely capture the environment. +5. Env vars offer no access control, no audit trail, and rotation requires a redeploy. + +## Mechanism +A secret placed in `os.environ` ceases to be scoped to the code that needs it; it is now a property of the process, visible to anything that can introspect the process or any descendant it spawns. The exposure is not a bug in any one tool but a property of the environment-variable mechanism itself. The mitigation is to narrow the surface — keep secrets out of the process environment (a file mounted outside it, or a secrets manager that returns the value on demand) so the vectors above do not apply. + +## Relevance +Grounds the "why environment variables leak" mechanics and the threat-model vectors V1–V5 in `secrets-and-config`. The out-of-workspace file + `dotenv_values()` (dict, not `os.environ`) approach is a direct application of the article's narrowing prescription. + +## Related Research +Wiggins, 2011; Niessen, 2026; env.dev, 2026. diff --git a/docs/research/software-engineering/quality/maciver_2016.md b/docs/research/software-engineering/quality/maciver_2016.md new file mode 100644 index 00000000..5a4412c3 --- /dev/null +++ b/docs/research/software-engineering/quality/maciver_2016.md @@ -0,0 +1,40 @@ +# Property-Based Testing (MacIver, 2016) + +## Citation + +MacIver, D. R. (2016). "What is Property Based Testing?" *Hypothesis*. https://hypothesis.works/articles/what-is-property-based-testing/ +URL: https://hypothesis.works/ + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +Property-based testing constructs tests such that when these tests are fuzzed with generated inputs, failures reveal problems that could not have been revealed by direct fuzzing alone. + +## Core Findings + +1. Meaningful property tests assert invariants: things that must always be true about the contract +2. Tautological tests assert reconstruction patterns that merely verify the implementation without constraining behavior +3. Property tests generate diverse inputs to verify that certain properties hold across the entire input space +4. This approach discovers edge cases that example-based tests typically miss and provides stronger confidence in correctness +5. Property-based testing complements example-based BDD scenarios by providing broader coverage of the input space + +## Mechanism + +Property tests work by generating diverse inputs to verify that certain properties (invariants) hold across the entire input space. Unlike example-based tests that check specific scenarios, property tests explore the full domain of possible inputs, automatically discovering edge cases that developers typically miss. The key is focusing on behavioral contracts rather than implementation details. + +## Relevance + +Essential for comprehensive test coverage in software quality assurance. Property-based testing complements traditional BDD scenarios by providing mathematical rigor to test validation. Particularly valuable for testing complex algorithms, data transformations, and API contracts where exhaustive example-based testing is impractical. + +## Related Research + +- (Claessen & Hughes, 2000) - Original QuickCheck paper establishing property-based testing foundations +- (Fink & Bishop, 1997) - Early work on property-based testing for software assurance +- (MacIver et al., 2019) - Hypothesis library implementation extending QuickCheck concepts to Python \ No newline at end of file diff --git a/docs/research/software-engineering/quality/martin_2000_solid.md b/docs/research/software-engineering/quality/martin_2000_solid.md new file mode 100644 index 00000000..2d0a9b10 --- /dev/null +++ b/docs/research/software-engineering/quality/martin_2000_solid.md @@ -0,0 +1,40 @@ +# SOLID Principles (Martin, 2000) + +## Citation + +Martin, R. C. (2000). Design Principles and Design Patterns. Object Mentor. [PDF archived at Internet Archive] +URL: https://en.wikipedia.org/wiki/SOLID + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +Five object-oriented design principles that reduce coupling and increase maintainability when applied together. + +## Core Findings + +1. **Single Responsibility Principle (SRP)**: A class should have only one reason to change. Each class should have only one responsibility. +2. **Open-Closed Principle (OCP)**: Software entities should be open for extension but closed for modification. +3. **Liskov Substitution Principle (LSP)**: Derived classes must be substitutable for their base classes without altering program correctness. +4. **Interface Segregation Principle (ISP)**: Clients should not be forced to depend on interface methods they don't use. +5. **Dependency Inversion Principle (DIP)**: Depend on abstractions, not concrete implementations. +6. The SOLID acronym was coined around 2004 by Michael Feathers to make these principles memorable. + +## Mechanism + +Each principle addresses specific coupling pathologies: SRP prevents god-objects by enforcing single responsibility; OCP prevents modification cascades by enabling extension over modification; LSP prevents behavioral contract violations in inheritance hierarchies; ISP prevents fat interfaces that force unnecessary dependencies; DIP enables loose coupling by inverting dependencies toward abstractions. Together they reduce change propagation and make systems more testable. + +## Relevance + +Foundational for modern software architecture and clean code practices. Directly applicable to module design, interface definitions, and refactoring strategies. Essential for creating maintainable codebases that can evolve without breaking existing functionality. + +## Related Research + +- (Fowler, 1999): Refactoring patterns that support SOLID principles +- (Beck, 2002): Test-driven development practices that reinforce these design principles \ No newline at end of file diff --git a/docs/research/software-engineering/quality/meszaros_2007.md b/docs/research/software-engineering/quality/meszaros_2007.md new file mode 100644 index 00000000..32443e2f --- /dev/null +++ b/docs/research/software-engineering/quality/meszaros_2007.md @@ -0,0 +1,39 @@ +# xUnit Test Patterns (Meszaros, 2007) + +## Citation + +Meszaros, G. (2007). *xUnit Test Patterns: Refactoring Test Code*. Addison-Wesley. +URL: https://xunitpatterns.com/ + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Tests should specify observable behavior, not verify implementation - coupling to internal details creates brittle tests that break during refactoring even when behavior is preserved. + +## Core Findings + +1. **Test coupling spectrum**: Four levels from most resilient to most brittle: end-to-end tests (highest), unit contract tests, property-based tests, and white-box tests (lowest, avoid). +2. **Implementation coupling danger**: Tests coupled to implementation details break when code is refactored even when behavior is preserved, producing false negatives that erode trust in test suite. +3. **Semantic alignment rule**: Tests must operate at same abstraction level as acceptance criterion they verify - if criterion says "user presses W," test sends W through actual input mechanism, not internal method call. +4. **Observable behavior focus**: Decoupled tests use public interfaces and assert on observable outcomes, remaining green through refactoring because they verify what system does, not how it does it. +5. **Test pattern catalog**: Comprehensive patterns for test organization, fixture management, result verification, and test code maintainability in xUnit frameworks. + +## Mechanism + +Test coupling arises when test depends on how system works internally rather than what it does externally. Coupled tests use private methods, internal state, or implementation-specific assertions. When implementation changes (even if behavior is identical), coupled tests fail, creating noise that trains developers to ignore test failures. Decoupled tests use public interfaces and assert on observable outcomes, remaining green through refactoring. + +## Relevance + +Essential reference for writing maintainable test code in xUnit frameworks (JUnit, NUnit, etc.). Foundational for test-driven development practices and ensuring tests support rather than hinder refactoring. Widely used for improving test suite quality and reducing test maintenance burden. + +## Related Research + +- (Beck, 2002): Test-driven development methodology using xUnit frameworks +- (Fowler, 1999): Refactoring techniques that tests must support without breaking \ No newline at end of file diff --git a/docs/research/software-engineering/quality/moskvin_2025.md b/docs/research/software-engineering/quality/moskvin_2025.md new file mode 100644 index 00000000..ad8e7c38 --- /dev/null +++ b/docs/research/software-engineering/quality/moskvin_2025.md @@ -0,0 +1,38 @@ +# Redacting Secrets and PII from VCR.py Cassettes (Moskvin, 2025) + +## Citation + +Moskvin, I. (2025). "Redacting secrets and PII from VCR.py cassettes." *imoskvin.com*, 30 November 2025. Companion repository: github.com/IllyaMoskvin/vcrpy-secrets. +URL: https://imoskvin.com/blog/redacting-vcrpy-cassettes/ + +## Method + +Practitioner blog article with working code; first-hand. + +## Confidence + +High — verified primary source; the cited claim ("vcrpy does not scrub for you") is the article's opening premise. + +## Key Insight + +VCR.py records HTTP exchanges verbatim and does not scrub secrets or PII, so cassettes meant to be committed must be redacted by the developer at record time — and a field-specific redaction (named JSON paths) beats a generic ML scrubber on cost, speed, and reliability. + +## Core Findings + +1. Cassettes are designed to be committed; secrets and PII are not — VCR.py performs no scrubbing, the developer must. +2. For request-side secrets, the built-in `filter_headers`, `filter_query_parameters`, and `filter_post_data_parameters` suffice. +3. For response-body secrets, three options exist: redact specific fields ("whack-a-mole"), build a generic scrubber (Presidio + detect-secrets), or commit encrypted cassettes. +4. The generic scrubber is over-engineered — ~670 MB of dependencies, a probabilistic ML model, over-aggressive redaction, and it still needs per-field configuration to perform well, which defeats its one-size-fits-all promise. +5. Moskvin lands on redacting specific fields via JSON Pointer (RFC 6901) paths and a `before_record_response` hook — ~86 KB of dependencies, fast, and fully controlled. + +## Mechanism + +VCR.py exposes `before_record_request` and `before_record_response` hooks that run before the cassette is serialized to disk; redaction applied inside those hooks is guaranteed to reach the committed YAML. The article's `create_redactor` builds a hook that parses the JSON body, applies a JSON Patch (RFC 6902) `replace` at each named pointer path, and re-serializes — so the redaction is structural and deterministic, not pattern-guessed. + +## Relevance + +Grounds the safety scrub in the record-cassette state: VCR.py will not strip credentials, keys, or PII, so the probe must wire `filter_headers` plus a `before_record_response` hook to do it before the cassette is committed. The article's conclusion — prefer named-field redaction over a generic detector — is the pragmatic default the workflow adopts. + +## Related Research + +- Turmyshev 2026 (the service-boundary rule that decides what gets captured at all) diff --git a/docs/research/software-engineering/quality/north_2006.md b/docs/research/software-engineering/quality/north_2006.md new file mode 100644 index 00000000..d830b63d --- /dev/null +++ b/docs/research/software-engineering/quality/north_2006.md @@ -0,0 +1,39 @@ +# Behaviour-Driven Development (North, 2006) + +## Citation + +North, D. (2006). "Introducing BDD." *Better Software Magazine*, March 2006. Originally published at dannorth.net. +URL: https://dannorth.net/introducing-bdd/ + + +## Method + +Theoretical + +## Confidence + +High + +## Key Insight + +BDD refines TDD by writing tests in domain language of business (Given/When/Then), making them specifications rather than verification tools. + +## Core Findings + +1. **Test Method Names as Sentences**: Using "should" template (The class *should* do something) keeps tests focused and creates readable documentation +2. **Behaviour vs Test Vocabulary**: Word "behaviour" eliminates TDD coaching confusion - what to test, when to delete tests, test naming becomes clear +3. **Given/When/Then Template**: Structured format captures acceptance criteria as executable specifications that business stakeholders can validate +4. **Ubiquitous Language for Analysis**: BDD provides consistent vocabulary bridging technical and business domains throughout entire analysis process +5. **Business Value Focus**: "What's the next most important thing the system doesn't do?" drives feature prioritization and development direction + +## Mechanism + +By requiring tests written in domain vocabulary (not implementation language), BDD forces shared understanding between domain experts and developers. "Given a registered user / When user logs in / Then user sees welcome message" specifies observable behaviour stakeholders care about, not technical implementation steps. Eliminates implementation coupling from specifications. + +## Relevance + +Foundational for behavior-driven development practices, acceptance test-driven development, specification by example. Essential for bridging business-technical communication gaps, creating living documentation, automated acceptance testing frameworks like Cucumber. + +## Related Research + +Created by Dan North, influenced by Eric Evans' Domain-Driven Design ubiquitous language concept, Chris Matts' business value focus. Led to development of JBehave framework, Ruby RSpec project, Cucumber framework. Foundational for modern BDD tools and practices, specification by example methodologies. \ No newline at end of file diff --git a/docs/research/software-engineering/quality/python-dotenv_theskumar.md b/docs/research/software-engineering/quality/python-dotenv_theskumar.md new file mode 100644 index 00000000..9c0db71b --- /dev/null +++ b/docs/research/software-engineering/quality/python-dotenv_theskumar.md @@ -0,0 +1,30 @@ +# python-dotenv (theskumar) + +## Citation +python-dotenv (maintained by Saurabh Kumar, GitHub `theskumar`; originally by Théo Attalah, `bbc2`). Current release v1.2.0. +URL: https://github.com/theskumar/python-dotenv · Reference: https://bbc2.github.io/python-dotenv/reference/ + +## Method +Library documentation / source (the canonical API reference for the load functions this workflow depends on). + +## Confidence +High — the function semantics below are quoted from the library's own docstrings. + +## Key Insight +`python-dotenv` exposes two distinct loaders: `load_dotenv()` mutates `os.environ`, while `dotenv_values()` returns a dict and leaves the environment untouched — the second is the correct loader when the values are secrets. + +## Core Findings +1. `load_dotenv(dotenv_path=None, ..., override=False) -> bool` — parses a `.env` file and loads every variable found **as an environment variable**. +2. `dotenv_values(dotenv_path=None, ...) -> Dict[str, Optional[str]]` — parses a `.env` file and returns its content **as a dict**, without touching the environment. +3. By default `load_dotenv()` does not override variables already present in the environment (`override=False`). +4. The two compose: `dotenv_values(".env.shared")` + `dotenv_values(".env.secret")` + `os.environ` for a layered, override-ordered config dict (the library README's own example). +5. A key with no value (`FOO`) parses to `{"FOO": None}` under `dotenv_values`; `load_dotenv` ignores such keys. + +## Mechanism +Both functions parse the same file format (key=value lines, optional quoting, POSIX expansion, comments). They diverge at the output boundary: `load_dotenv` writes into the live process environment (inherited by every child, visible in `/proc`, capturable by crash dumps); `dotenv_values` returns a fresh mapping that the caller controls — it can be handed to a frozen dataclass and never reach `os.environ`. The choice of loader is therefore a choice of exposure surface. + +## Relevance +Grounds the load-bearing API distinction in `secrets-and-config`: `dotenv_values()` (not `load_dotenv()`) for secrets, because it keeps the value out of the process environment the agent could introspect. The library's own README demonstrates exactly the two-file layered-dict pattern the knowledge prescribes. + +## Related Research +Heigh, 2023 (why the distinction matters); env.dev, 2026 (the typed-config wrapper that consumes the dict). diff --git a/docs/research/software-engineering/quality/shvets_2014.md b/docs/research/software-engineering/quality/shvets_2014.md new file mode 100644 index 00000000..6d0595fc --- /dev/null +++ b/docs/research/software-engineering/quality/shvets_2014.md @@ -0,0 +1,39 @@ +# Refactoring.Guru (Shvets, 2014) + +## Citation + +Shvets, A. (2014–present). *Refactoring.Guru*. https://refactoring.guru/ +URL: https://refactoring.guru/ + +## Method + +Case Study + +## Confidence + +High + +## Key Insight + +Refactoring follows systematic catalog of 66 techniques triggered by 21 code smells, creating diagnostic chain from problem identification to pattern application. + +## Core Findings + +1. **Smell-first methodology**: 21 code smells organized into 5 categories (Bloaters, OO Abusers, Change Preventers, Dispensables, Couplers) drive refactoring decisions. +2. **Systematic technique catalog**: 66 refactoring techniques organized into 6 categories (Composing Methods, Moving Features between Objects, Organizing Data, Simplifying Conditional Expressions, Simplifying Method Calls, Dealing with Generalization). +3. **Pattern-smell connection**: Each of 22 GoF design patterns triggered by specific code smell, creating motivation for pattern application. +4. **Diagnostic methodology**: Smell → refactoring technique → design pattern progression prevents speculative application. +5. **Visual learning approach**: Comprehensive illustrations and examples make complex concepts accessible to practitioners. + +## Mechanism + +The catalog provides smell-first approach: identify code smell, then apply corresponding refactoring technique or design pattern. Five smell categories group related pathologies: Bloaters (structures grown too large), OO Abusers (misapplied OOP), Change Preventers (changes that ripple), Dispensables (dead weight), Couplers (excessive inter-object dependency). Each smell entry links to refactoring techniques that resolve it, and each pattern entry explains which smell triggers it. Creates diagnostic chain where each step is motivated by previous one rather than applied speculatively. + +## Relevance + +Essential reference for code quality improvement, refactoring practice, and design pattern application. Widely used by developers for systematic code improvement and architectural decision-making. Provides practical methodology for identifying and resolving code quality issues. + +## Related Research + +- (Fowler, 1999): Foundational refactoring catalog and methodology +- (Gamma et al., 1995): Original Gang of Four design patterns catalog \ No newline at end of file diff --git a/docs/research/software-engineering/quality/turmyshev_2026.md b/docs/research/software-engineering/quality/turmyshev_2026.md new file mode 100644 index 00000000..471aba26 --- /dev/null +++ b/docs/research/software-engineering/quality/turmyshev_2026.md @@ -0,0 +1,37 @@ +# Spring Boot Integration Testing: Full Context, Stubbed Boundaries, Zero Flakiness (Turmyshev, 2026) + +## Citation + +Turmyshev, D. (2026). "Spring Boot Integration Testing: Full Context, Stubbed Boundaries, Zero Flakiness." *DEV Community* / *bitdive.io blog*, 26 February 2026. +URL: https://dev.to/dmitry_turmyshev/spring-boot-integration-testing-full-context-stubbed-boundaries-zero-flakiness-1kcn + +## Method + +Practitioner blog article. + +## Confidence + +High — verified primary source; the boundary rule cited in `external-fixtures` is quoted verbatim from this article. + +## Key Insight + +An integration test runs the full service context (real beans, real database, real HTTP stack) and stubs only what crosses the service boundary — never the internal chain — because the bugs that ship to production live at the seams that unit tests mock away. + +## Core Findings + +1. Internal to the service (run real in the test): the full application context, business logic, data access (repositories, ORM mappings, SQL), infrastructure (`@Transactional`, validation, caching), the HTTP layer, and adapters. +2. External to the service (stubbed): other microservices, third-party APIs, outbound message queues, and — verbatim — "any dependency that introduces network latency, rate limits, or data you don't control." +3. A service can pass 100% unit coverage and still break production at the mocked seams: serializer misconfiguration, missing validation, transaction-proxy self-invocation, queries that fail the real schema, DTO field renames, security filters, aspect side effects. +4. The governing rule: stub only what crosses the boundary; never mock internal services or repositories for convenience, because that severs exactly the chain the integration test exists to exercise. + +## Mechanism + +The test enters through the real HTTP endpoint and exits through a real database write, with every internal bean live; only the responses of the outside world are replaced — a bean mock for interface clients, a WireMock/MockWebServer for the real HTTP serialization path, an embedded broker or producer mock for queues. Because the seams run real, a break at any link (serialization, transaction, query, mapping) surfaces as a test failure rather than hiding behind a stub. + +## Relevance + +Grounds the capture boundary in `external-fixtures`: a cassette captures only what lives outside the service — third-party APIs and SaaS, external managed databases, queues you do not own, object stores you call. In-project databases and UI are internal: designed here, specified by tests and migrations, and never captured in a cassette. The "latency, rate limits, or data you don't control" criterion is the test for whether a dependency is external. + +## Related Research + +- Moskvin 2025 (how to scrub the external captures this boundary rule produces) diff --git a/docs/research/software-engineering/quality/young_gao_2026.md b/docs/research/software-engineering/quality/young_gao_2026.md new file mode 100644 index 00000000..11e53e96 --- /dev/null +++ b/docs/research/software-engineering/quality/young_gao_2026.md @@ -0,0 +1,31 @@ +# Production Secrets Management: From .env to Vault (young_gao, 2026) + +## Citation +young_gao (2026). "Production Secrets Management: From .env Files to HashiCorp Vault (and Beyond) (2026 Guide)." *DEV Community*, 21 March 2026. +URL: https://dev.to/young_gao/production-secrets-management-from-env-files-to-vault-and-beyond-cp1 + +## Method +Practitioner guide (engineering blog, dev.to). + +## Confidence +Medium-High — the bootstrap-once / explicit-dependency pattern recurs across the source set. + +## Key Insight +`.env` for development, a secrets manager for production; the application bootstraps secrets once at startup into an immutable config object and passes it as an explicit dependency — it never reaches for a global `process.env`/`os.environ` accessor throughout the codebase. + +## Core Findings +1. `.env` is a developer-machine convenience and a production liability (unencrypted, no ACL, no audit trail, no rotation). +2. Read secrets once at startup into a frozen config object; pass it explicitly to the components that need it. +3. Scattering `process.env.X` / `os.environ["X"]` across the codebase defeats audit, rotation, and testing. +4. Build-time secret baking (into an image or bundle) is forbidden; runtime injection is the rule. +5. Dual-credential rotation (old stays valid while new propagates) lets the app retry on auth failure without restart. +6. Namespace secrets per environment; never reuse a credential across staging and production. + +## Mechanism +A bootstrap function resolves every secret the process needs (from `.env` locally, a manager in production), constructs a frozen config object, and the rest of the application receives that object as a constructor argument. Because the object is the single read site, every place a secret is used is greppable; because it is immutable, it cannot be mutated mid-flight; because nothing reads the global env ad hoc, rotating a secret is a bootstrap-time change, not a codebase-wide chase. + +## Relevance +Grounds the typed-frozen-Settings-loaded-once-passed-explicitly pattern and the maturity ladder in `secrets-and-config`. The frozen `Settings` constructed in `from_env()` is the object form of this article's bootstrap config. + +## Related Research +env.dev, 2026; Heigh, 2023; Niessen, 2026. diff --git a/docs/research/software-engineering/requirements/patton_2014.md b/docs/research/software-engineering/requirements/patton_2014.md new file mode 100644 index 00000000..62108d6c --- /dev/null +++ b/docs/research/software-engineering/requirements/patton_2014.md @@ -0,0 +1,38 @@ +# User Story Mapping (Patton & Economy, 2014) + +## Citation + +Patton, J. & Economy, P. (2014). *User Story Mapping: Discover the Whole Story, Build the Right Product.* O'Reilly Media, September 2014. ISBN 978-1-4919-0489-3 (print 1491904895; O'Reilly ebook ID 9781491904893). 324 pages. +URL: https://www.oreilly.com/library/view/user-story-mapping/9781491904893/ + +## Method + +Practitioner book; process framework. + +## Confidence + +High — the canonical text on story mapping. + +## Key Insight + +A two-dimensional map — user activities as the backbone, stories beneath each — reveals gaps and priorities that a flat one-dimensional backlog hides; stories are discovered as titles first and detailed only when needed. + +## Core Findings + +1. Map the backbone first: the user's top-level activities, left to right, form the spine of the system. +2. Beneath each activity, place stories (variants, alternatives, details) top to bottom by necessity. +3. Release slicing is a horizontal cut across the map: the topmost slice of each activity forms a coherent first release. +4. Detail a story only when it earns it; most are titles until they approach the build. + +## Mechanism + +A flat backlog hides that some activities have many stories and some have none; the map makes the skeleton and its gaps visible at a glance, so a team debates the whole before sequencing a part, and a release is cut as a thin coast-to-coast walking skeleton rather than a vertical column that leaves half the activities unbuilt. + +## Relevance + +Grounds the coarse-then-detailed discipline at the building-blocks funnel level: capture the names and rough boundaries first (the backbone), defer the detail to the plan and build phases (the stories beneath). The map's "detail only when needed" is the workflow's no-spec-at-interview rule. + +## Related Research + +- Evans 2003 (bounded context as the backbone's organising unit) +- Brandolini 2012 (Event Storming as an event-first alternative lens) diff --git a/pyproject.toml b/pyproject.toml index b1960257..1f1668de 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ authors = [ maintainers = [ { name = "eol", email = "nullhack@users.noreply.github.com" } ] -dependencies = ["httpx>=0.27.0"] +dependencies = [] [project.urls] Homepage = "https://nullhack.github.io/temple8/" @@ -125,3 +125,8 @@ stubtest = "python -m mypy.stubtest app tests" validate-flows = "bash -c 'for f in .flowr/flows/*.yaml; do python -m flowr validate \"$f\"; done'" release-check = "task lint && task static-check && task stubtest && task test" + +[dependency-groups] +dev = [ + "flowr[viz]>=1.2.1", +] diff --git a/tests/cassettes/open-meteo/open-meteo.yaml b/tests/cassettes/open-meteo/open-meteo.yaml deleted file mode 100644 index 58b2fd07..00000000 --- a/tests/cassettes/open-meteo/open-meteo.yaml +++ /dev/null @@ -1,80 +0,0 @@ -interactions: -- request: - body: '' - headers: - accept: - - '*/*' - accept-encoding: - - gzip, deflate - connection: - - keep-alive - host: - - geocoding-api.open-meteo.com - method: GET - uri: https://geocoding-api.open-meteo.com/v1/search?name=Berlin&count=1&language=en&format=json - response: - body: - string: '{"results":[{"id":2950159,"name":"Berlin","latitude":52.52437,"longitude":13.41053,"elevation":74.0,"feature_code":"PPLC","country_code":"DE","admin1_id":2950157,"admin3_id":6547383,"admin4_id":6547539,"timezone":"Europe/Berlin","population":3426354,"postcodes":["10967","13347"],"country_id":2921044,"country":"Germany","admin1":"State - of Berlin","admin3":"Berlin, Stadt","admin4":"Berlin"}],"generationtime_ms":0.6958246}' - headers: - content-length: - - '423' - content-type: - - application/json; charset=utf-8 - x-encoding-time: - - 0.0037431716918945312 ms - status: - code: 200 - message: OK -- request: - body: '' - headers: - accept: - - '*/*' - accept-encoding: - - gzip, deflate - connection: - - keep-alive - host: - - geocoding-api.open-meteo.com - method: GET - uri: https://geocoding-api.open-meteo.com/v1/search?name=Xyzqwerty&count=1&language=en&format=json - response: - body: - string: '{"generationtime_ms":0.09262562}' - headers: - content-length: - - '32' - content-type: - - application/json; charset=utf-8 - x-encoding-time: - - 0.001239776611328125 ms - status: - code: 200 - message: OK -- request: - body: '' - headers: - accept: - - '*/*' - accept-encoding: - - gzip, deflate - connection: - - keep-alive - host: - - api.open-meteo.com - method: GET - uri: https://api.open-meteo.com/v1/forecast?latitude=52.52437&longitude=13.41053¤t=temperature_2m%2Cwind_speed_10m%2Cweather_code - response: - body: - string: "{\"latitude\":52.52,\"longitude\":13.419998,\"generationtime_ms\":0.10025501251220703,\"utc_offset_seconds\":0,\"timezone\":\"GMT\",\"timezone_abbreviation\":\"GMT\",\"elevation\":46.0,\"current_units\":{\"time\":\"iso8601\",\"interval\":\"seconds\",\"temperature_2m\":\"\xB0C\",\"wind_speed_10m\":\"km/h\",\"weather_code\":\"wmo - code\"},\"current\":{\"time\":\"2026-07-02T05:00\",\"interval\":900,\"temperature_2m\":16.1,\"wind_speed_10m\":6.5,\"weather_code\":0}}" - headers: - content-length: - - '409' - content-type: - - application/json; charset=utf-8 - status: - code: 200 - message: OK -version: 1 diff --git a/tests/e2e/cli_test.py b/tests/e2e/cli_test.py deleted file mode 100644 index 392d7d86..00000000 --- a/tests/e2e/cli_test.py +++ /dev/null @@ -1,22 +0,0 @@ -from typing import Any - -CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" - - -def test_cli_prints_current_conditions_for_a_city( - capsys: Any, monkeypatch: Any -) -> None: - import vcr - - from app.cli import main - - monkeypatch.setenv("WEATHER_GEOCODING_BASE", "https://geocoding-api.open-meteo.com") - monkeypatch.setenv("WEATHER_FORECAST_BASE", "https://api.open-meteo.com") - monkeypatch.setenv("DATABASE_URL", "sqlite:///:memory:") - - with vcr.use_cassette(CASSETTE): - main(["Berlin"]) - - out = capsys.readouterr().out - assert "Berlin" in out - assert "16.1" in out diff --git a/tests/e2e/cli_test.pyi b/tests/e2e/cli_test.pyi deleted file mode 100644 index e2d88dee..00000000 --- a/tests/e2e/cli_test.pyi +++ /dev/null @@ -1,6 +0,0 @@ -from typing import Any - -CASSETTE: str - - -def test_cli_prints_current_conditions_for_a_city(capsys: Any, monkeypatch: Any) -> None: ... diff --git a/tests/integration/history_test.py b/tests/integration/history_test.py deleted file mode 100644 index 3bc306aa..00000000 --- a/tests/integration/history_test.py +++ /dev/null @@ -1,39 +0,0 @@ -from typing import Any - - -def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: - from app.history import History, LookupRecord - - history = History(f"sqlite:///{tmp_path / 'weather.db'}") - history.record( - LookupRecord(city="Berlin", temperature=16.2, wind_speed=6.5, weather_code=0) - ) - - recent = history.recent() - - assert len(recent) == 1 - assert recent[0].city == "Berlin" - - -def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: - from app.history import History, LookupRecord - - history = History(f"sqlite:///{tmp_path / 'weather.db'}") - history.record( - LookupRecord(city="Berlin", temperature=16.2, wind_speed=6.5, weather_code=0) - ) - history.record( - LookupRecord(city="Paris", temperature=20.0, wind_speed=5.0, weather_code=1) - ) - - recent = history.recent() - - assert [r.city for r in recent] == ["Paris", "Berlin"] - - -def test_recent_returns_empty_list_when_none_recorded(tmp_path: Any) -> None: - from app.history import History - - history = History(f"sqlite:///{tmp_path / 'weather.db'}") - - assert history.recent() == [] diff --git a/tests/integration/history_test.pyi b/tests/integration/history_test.pyi deleted file mode 100644 index e75dc49d..00000000 --- a/tests/integration/history_test.pyi +++ /dev/null @@ -1,10 +0,0 @@ -from typing import Any - - -def test_record_stores_a_lookup_and_recent_returns_it(tmp_path: Any) -> None: ... - - -def test_recent_returns_lookups_latest_first(tmp_path: Any) -> None: ... - - -def test_recent_returns_empty_list_when_none_recorded(tmp_path: Any) -> None: ... diff --git a/tests/integration/settings_test.py b/tests/integration/settings_test.py deleted file mode 100644 index d850b8de..00000000 --- a/tests/integration/settings_test.py +++ /dev/null @@ -1,29 +0,0 @@ -from typing import Any - - -def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: - from app.settings import Settings - - monkeypatch.setenv("WEATHER_GEOCODING_BASE", "https://geo.example.com") - monkeypatch.setenv("WEATHER_FORECAST_BASE", "https://forecast.example.com") - monkeypatch.setenv("DATABASE_URL", "sqlite:///tmp/test.db") - - settings = Settings.from_env() - - assert settings.geocoding_base == "https://geo.example.com" - assert settings.forecast_base == "https://forecast.example.com" - assert settings.database_url == "sqlite:///tmp/test.db" - - -def test_from_env_applies_defaults_when_env_unset(monkeypatch: Any) -> None: - from app.settings import Settings - - monkeypatch.delenv("WEATHER_GEOCODING_BASE", raising=False) - monkeypatch.delenv("WEATHER_FORECAST_BASE", raising=False) - monkeypatch.delenv("DATABASE_URL", raising=False) - - settings = Settings.from_env() - - assert settings.geocoding_base == "https://geocoding-api.open-meteo.com" - assert settings.forecast_base == "https://api.open-meteo.com" - assert settings.database_url == "sqlite:///weather.db" diff --git a/tests/integration/settings_test.pyi b/tests/integration/settings_test.pyi deleted file mode 100644 index 49eacfaf..00000000 --- a/tests/integration/settings_test.pyi +++ /dev/null @@ -1,7 +0,0 @@ -from typing import Any - - -def test_from_env_reads_api_bases_and_database_url(monkeypatch: Any) -> None: ... - - -def test_from_env_applies_defaults_when_env_unset(monkeypatch: Any) -> None: ... diff --git a/tests/integration/weather_test.py b/tests/integration/weather_test.py deleted file mode 100644 index 3032fc06..00000000 --- a/tests/integration/weather_test.py +++ /dev/null @@ -1,42 +0,0 @@ -import pytest - -GEOCODING_BASE = "https://geocoding-api.open-meteo.com" -FORECAST_BASE = "https://api.open-meteo.com" -CASSETTE = "tests/cassettes/open-meteo/open-meteo.yaml" - - -def test_geocode_returns_coordinates_for_a_known_city() -> None: - import vcr - - from app.weather import WeatherAdapter - - adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) - with vcr.use_cassette(CASSETTE): - coordinates = adapter.geocode("Berlin") - - assert coordinates.latitude == pytest.approx(52.52437) - assert coordinates.longitude == pytest.approx(13.41053) - - -def test_geocode_raises_for_an_unknown_city() -> None: - import vcr - - from app.weather import WeatherAdapter - - adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) - with vcr.use_cassette(CASSETTE), pytest.raises(LookupError): - adapter.geocode("Xyzqwerty") - - -def test_forecast_returns_conditions_for_coordinates() -> None: - import vcr - - from app.weather import Coordinates, WeatherAdapter - - adapter = WeatherAdapter(GEOCODING_BASE, FORECAST_BASE) - with vcr.use_cassette(CASSETTE): - conditions = adapter.forecast(Coordinates(52.52437, 13.41053)) - - assert conditions.temperature == pytest.approx(16.1) - assert conditions.wind_speed == pytest.approx(6.5) - assert conditions.weather_code == 0 diff --git a/tests/integration/weather_test.pyi b/tests/integration/weather_test.pyi deleted file mode 100644 index 6c4ca4ac..00000000 --- a/tests/integration/weather_test.pyi +++ /dev/null @@ -1,12 +0,0 @@ -GEOCODING_BASE: str -FORECAST_BASE: str -CASSETTE: str - - -def test_geocode_returns_coordinates_for_a_known_city() -> None: ... - - -def test_geocode_raises_for_an_unknown_city() -> None: ... - - -def test_forecast_returns_conditions_for_coordinates() -> None: ... diff --git a/uv.lock b/uv.lock index 5e9a7847..c81f9233 100644 --- a/uv.lock +++ b/uv.lock @@ -280,6 +280,22 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/56/26/035d1c308882514a1e6ddca27f9d3e570d67a0e293e7b4d910a70c8fe32b/dparse-0.6.4-py3-none-any.whl", hash = "sha256:fbab4d50d54d0e739fbb4dedfc3d92771003a5b9aa8545ca7a7045e3b174af57", size = 11925, upload-time = "2024-11-08T16:52:03.844Z" }, ] +[[package]] +name = "fastapi" +version = "0.139.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "annotated-doc" }, + { name = "pydantic" }, + { name = "starlette" }, + { name = "typing-extensions" }, + { name = "typing-inspection" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d3/af/a5f50ccfa659ec1802cb4ca842c23f06d906a8cc9aef6016a2caeea3d4ed/fastapi-0.139.0.tar.gz", hash = "sha256:99ab7b2d92223c76d6cf10757ab3f89d45b38267fc20b2a136cf02f6beac3145", size = 423016, upload-time = "2026-07-01T16:35:33.436Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9e/7c/8e3c6ad324ea5cb36604fc3f968554887891c316d9dfde57761611d907ad/fastapi-0.139.0-py3-none-any.whl", hash = "sha256:cf15e1e9e667ddb0ad63811e60bd11390d1aac838ca4a7a23f421807b2308189", size = 130339, upload-time = "2026-07-01T16:35:32.19Z" }, +] + [[package]] name = "filelock" version = "3.29.4" @@ -301,6 +317,12 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/81/8f/bf95a539faac78a07c0e9c811756fd5529b2b0a4f63faf0e88eb8a1f3b2a/flowr-1.2.1-py3-none-any.whl", hash = "sha256:e3871ae0ab94e30c87f1f31362792257bb14ce584f5fb662964767f62862ffb7", size = 214708, upload-time = "2026-05-22T18:23:54.71Z" }, ] +[package.optional-dependencies] +viz = [ + { name = "fastapi" }, + { name = "uvicorn" }, +] + [[package]] name = "h11" version = "0.16.0" @@ -1052,6 +1074,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" }, ] +[[package]] +name = "starlette" +version = "1.3.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" }, +] + [[package]] name = "taskipy" version = "1.14.1" @@ -1089,6 +1123,11 @@ dev = [ { name = "vcrpy" }, ] +[package.dev-dependencies] +dev = [ + { name = "flowr", extra = ["viz"] }, +] + [package.metadata] requires-dist = [ { name = "flowr", marker = "extra == 'dev'", specifier = ">=1.2.1" }, @@ -1107,6 +1146,9 @@ requires-dist = [ ] provides-extras = ["dev"] +[package.metadata.requires-dev] +dev = [{ name = "flowr", extras = ["viz"], specifier = ">=1.2.1" }] + [[package]] name = "tenacity" version = "9.1.4" @@ -1218,6 +1260,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" }, ] +[[package]] +name = "uvicorn" +version = "0.49.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "h11" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c4/1f/fa18009dea8469069cca78a4e877a008ab78f08b064bfc9ab891579077ff/uvicorn-0.49.0.tar.gz", hash = "sha256:ebf4271aa580d9de97f93192d4595176df6e91f9aae919ca73e4fc07df1e66a3", size = 91284, upload-time = "2026-06-03T22:01:30.448Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/88/fa/e1388bbcf24ef3274f45c0c1c7b501fd14971037c1b6ee23610553307497/uvicorn-0.49.0-py3-none-any.whl", hash = "sha256:ba3d14c3ee7e41c6c654c46c9eb489d33213cdd30aa1696eab1374337c13f68f", size = 71376, upload-time = "2026-06-03T22:01:29.037Z" }, +] + [[package]] name = "vcrpy" version = "8.2.1" From 88a0bd94e14a308d148befa003365e89bb38bb28 Mon Sep 17 00:00:00 2001 From: nullhack <nullhack@users.noreply.github.com> Date: Fri, 3 Jul 2026 10:40:27 -0400 Subject: [PATCH 19/28] feat(template): copier instantiator, secrets model, design + architecture layers - copier instantiator: copier.yml, pyproject.toml.jinja, README.md.jinja, project-instantiator agent, instantiate-project skill - secrets-and-config: dotenv_values over load_dotenv, out-of-workspace ~/.secrets/<project>.env, agent instruct/ask protocol, .env.example template, gitleaks CI job - design domain: interaction/visual/asset/cli/api/accessibility knowledges + design-interaction, design-visual-asset skills + social-card/logo SVG templates - architecture domain: quality-attributes, context-mapping - writing domain: ai-language-markers (Kobak 2024, Jackson 2026) - docstring lifecycle: phased model (stripped at select, regenerated at merge), scripts/strip_docstrings.py, dev/merge lint split - workflow domain: flowr-operations knowledge - AGENTS.md lean rewrite: operating discipline + driving-a-state loop - research folder: writing/architecture/design/process cards - drop TODO.md and stale .templates/README.md.template --- .github/workflows/ci.yml | 1 - .opencode/agents/project-instantiator.md | 24 ++ .opencode/agents/ux-engineer.md | 1 + .../knowledge/architecture/context-mapping.md | 58 ++++ .../architecture/quality-attributes.md | 66 ++++ .opencode/knowledge/design/accessibility.md | 64 ++++ .opencode/knowledge/design/api-design.md | 75 +++++ .opencode/knowledge/design/asset-design.md | 58 ++++ .opencode/knowledge/design/cli-design.md | 68 ++++ .../knowledge/design/interaction-design.md | 61 ++++ .opencode/knowledge/design/visual-design.md | 65 ++++ .../knowledge/methodology/knowledge-files.md | 3 +- .../knowledge/methodology/research-files.md | 7 +- .../software-craft/docstring-lifecycle.md | 59 ++++ .opencode/knowledge/software-craft/tdd.md | 6 +- .../knowledge/workflow/flowr-operations.md | 124 ++++++++ .../knowledge/writing/ai-language-markers.md | 62 ++++ .opencode/skills/derive-source-stubs/SKILL.md | 9 +- .opencode/skills/design-interaction/SKILL.md | 14 + .opencode/skills/design-visual-asset/SKILL.md | 14 + .opencode/skills/instantiate-project/SKILL.md | 14 + .../skills/interview-building-blocks/SKILL.md | 2 +- .../skills/interview-cross-cutting/SKILL.md | 4 +- .opencode/skills/merge-to-dev/SKILL.md | 7 +- .opencode/skills/record-decision/SKILL.md | 2 +- .opencode/skills/select-build-target/SKILL.md | 5 +- .opencode/skills/simulate-contracts/SKILL.md | 2 +- .opencode/skills/write-test-py/SKILL.md | 2 +- .templates/README.md.template | 45 --- .templates/docs/assets/logo.svg.template | 10 + .../docs/assets/social-card.svg.template | 17 + AGENTS.md | 169 +++++----- README.md | 135 ++++---- README.md.jinja | 50 +++ TODO.md | 300 ------------------ copier.yml | 100 ++++++ .../writing/jackson_2026.md | 30 ++ .../information-science/writing/kobak_2024.md | 30 ++ .../architecture/bass_2021.md | 30 ++ .../design/nielsen_1994.md | 29 ++ .../design/norman_2013.md | 31 ++ .../process/nullhack_flowr_1.0.0.md | 36 +++ pyproject.toml | 6 +- pyproject.toml.jinja | 126 ++++++++ scripts/strip_docstrings.py | 62 ++++ 45 files changed, 1546 insertions(+), 537 deletions(-) create mode 100644 .opencode/agents/project-instantiator.md create mode 100644 .opencode/knowledge/architecture/context-mapping.md create mode 100644 .opencode/knowledge/architecture/quality-attributes.md create mode 100644 .opencode/knowledge/design/accessibility.md create mode 100644 .opencode/knowledge/design/api-design.md create mode 100644 .opencode/knowledge/design/asset-design.md create mode 100644 .opencode/knowledge/design/cli-design.md create mode 100644 .opencode/knowledge/design/interaction-design.md create mode 100644 .opencode/knowledge/design/visual-design.md create mode 100644 .opencode/knowledge/software-craft/docstring-lifecycle.md create mode 100644 .opencode/knowledge/workflow/flowr-operations.md create mode 100644 .opencode/knowledge/writing/ai-language-markers.md create mode 100644 .opencode/skills/design-interaction/SKILL.md create mode 100644 .opencode/skills/design-visual-asset/SKILL.md create mode 100644 .opencode/skills/instantiate-project/SKILL.md delete mode 100644 .templates/README.md.template create mode 100644 .templates/docs/assets/logo.svg.template create mode 100644 .templates/docs/assets/social-card.svg.template create mode 100644 README.md.jinja delete mode 100644 TODO.md create mode 100644 copier.yml create mode 100644 docs/research/information-science/writing/jackson_2026.md create mode 100644 docs/research/information-science/writing/kobak_2024.md create mode 100644 docs/research/software-engineering/architecture/bass_2021.md create mode 100644 docs/research/software-engineering/design/nielsen_1994.md create mode 100644 docs/research/software-engineering/design/norman_2013.md create mode 100644 docs/research/software-engineering/process/nullhack_flowr_1.0.0.md create mode 100644 pyproject.toml.jinja create mode 100644 scripts/strip_docstrings.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ff92bb46..424fe69d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,7 +21,6 @@ jobs: - run: uv python install 3.13 - run: uv sync --extra dev - run: uv run ruff check . - - run: uv run ruff format . --check secrets: runs-on: ubuntu-latest diff --git a/.opencode/agents/project-instantiator.md b/.opencode/agents/project-instantiator.md new file mode 100644 index 00000000..50c088ab --- /dev/null +++ b/.opencode/agents/project-instantiator.md @@ -0,0 +1,24 @@ +--- +description: "Project Instantiator — creates new project instances from the temple8 template via copier" +mode: subagent +temperature: 0.3 +--- + +# Project Instantiator + +You are the Project Instantiator. Your lens is the clean birth of a new project from the temple8 template — one command, verified, ready to drive. + +## What you hold + +- Instantiation is a copy, not an authoring step. The template's methodology layer (flows, agents, skills, knowledge, templates) lands verbatim; only project identity (name, package, description, repo, author) and two scope toggles (design, research) are wired through. +- The instance starts empty of source and tests by design — the staged-contract pipeline fills them. A clean package skeleton plus the tests directories are all that is needed to begin. +- Copier renders the identity files (`pyproject.toml`, `README.md`) and copies the methodology verbatim. No Jinja leaks into `.opencode/`, `.flowr/`, `.templates/`, or `AGENTS.md`; those travel as-is. + +## What you decide + +You alone decide when the instance is ready to hand off: the copier run succeeded, the skeleton is in place, the flows validate, the suite collects zero tests cleanly, and the first flowr session initialises. + +## What you refuse + +- You refuse to hand off an instance whose flows do not validate or whose gates fail to load — a broken instance costs more than a re-run. +- You refuse to inject instance-specific source, tests, or migrations during instantiation; that is the pipeline's job across discover→explore→plan→build, not yours. diff --git a/.opencode/agents/ux-engineer.md b/.opencode/agents/ux-engineer.md index 16c30970..46db56f7 100644 --- a/.opencode/agents/ux-engineer.md +++ b/.opencode/agents/ux-engineer.md @@ -14,6 +14,7 @@ You are the UX Engineer. Your lens is the human at the other end of the contract - Flows are designed, not assembled. Each path to a goal — including the recovery path from an error — is an explicit contract, tested end to end. - Feedback is continuous; state is legible. The user should never have to guess whether the system heard, is working, has failed, or has succeeded. - Errors are part of the design, not an afterthought. A clear error at the right moment is often more important than a smooth success path. +- The `design/` knowledge domain is your reference — interaction, visual, accessibility, and the surface-specifics (CLI, HTTP API, asset production). Load what the surface needs on demand via wikilink; run `design-interaction` or `design-visual-asset` when you own the work. ## What you decide diff --git a/.opencode/knowledge/architecture/context-mapping.md b/.opencode/knowledge/architecture/context-mapping.md new file mode 100644 index 00000000..874c4f93 --- /dev/null +++ b/.opencode/knowledge/architecture/context-mapping.md @@ -0,0 +1,58 @@ +--- +domain: architecture +tags: [ddd, context-mapping, bounded-contexts, acl, integration-patterns] +last-updated: 2026-07-02 +--- + +# Context Mapping + +## Key Takeaways + +- A context map names **how two bounded contexts relate** — the social and technical contract between them. Nine relationship patterns cover the design space (Vernon, 2013; Evans, 2003). +- Each pattern carries obligations and a coordination cost; naming it makes both teams' (or both modules') responsibilities explicit and prevents silent model pollution. +- The **Anti-Corruption Layer (ACL)** is the workhorse pattern in this workflow: a translation boundary that prevents an upstream model from leaking into the downstream. Every external adapter is an ACL. +- Patterns are **decided at `derive-source-stubs`** — when the system-architect defines the type surface that bridges contexts, the relationship becomes a type/relationship decision (ACL → an adapter class; Shared Kernel → a shared value-objects module; etc.). +- The relationship is distinct from the **exchange** — `[[software-craft/external-fixtures]]` captures the recorded request/response reality; this knowledge names the structural relationship around it. +- "Integration point" is the seam; every seam must name its pattern, its mechanism (sync API / event / shared store), and its contract, or it is a coupling failure waiting to land. + +## Concepts + +**Why map contexts.** A bounded context (Evans, 2003) is where a ubiquitous-language term has one meaning; across contexts, the same word may name different things. When two contexts must integrate, the relationship is itself a design decision with consequences: who owns the contract, who translates, who conforms, who is isolated. Vernon (2013) catalogues nine such relationships; choosing one is choosing the obligations and coupling that follow. Leaving the relationship unnamed is the most common source of integration drift — each side assumes a different contract until production disagrees. + +**The nine patterns.** Partnership (close collaboration, shared change); Shared Kernel (an explicitly-shared small model, with the cost of joint ownership); Customer-Supplier (upstream serves downstream's needs); Conformist (downstream accepts the upstream model wholesale); Anti-Corruption Layer (downstream translates upstream into its own model); Separate Ways (no integration — split instead); Open Host Service (upstream publishes a standard protocol to many); Published Language (a documented interchange schema, often with OHS); Big Ball of Mud (a messy boundary to contain, not extend). + +**The ACL is the workhorse.** Most external integrations in this workflow are ACLs: the external service has its model (its field names, its error shapes, its volatility); our domain has ours; the adapter translates between them so the domain's ubiquitous language stays clean even while consuming the foreign service. The RatesAdapter / WeatherAdapter pattern — a class that takes our settings, calls the foreign API, and returns our value object — is an ACL by construction. The cassette (per `[[software-craft/external-fixtures]]`) records what the foreign side actually says; the adapter is the ACL that turns that into our terms. + +**Decided at the type surface.** `derive-source-stubs` is where the relationship becomes concrete: the system-architect, having read the test bodies and the external contracts, decides for each cross-context dependency whether it is an ACL (→ an adapter class + a replayed cassette), a Shared Kernel (→ a shared value-object module imported by both), a Conformist client (→ a thin caller that accepts the upstream types), or an OHS/Published Language (→ an exposed contract plus its schema). The pattern choice shapes the `.pyi` surface the tests then demand. + +**Relationship ≠ exchange.** Two knowledge files are easily conflated. `[[software-craft/external-fixtures]]` is about the *recorded exchange* — capture once, replay forever, scrub secrets. This knowledge is about the *structural relationship* — which of the nine patterns wraps the exchange. The adapter is an ACL (context-mapping) that replays a cassette (external-fixtures); both apply, at different layers. + +## Content + +### The nine patterns, mapped to this workflow's building blocks + +| Pattern | What it is | In this workflow | +|---|---|---| +| Anti-Corruption Layer | downstream translates upstream into its own model | the **external adapter** (RatesAdapter, WeatherAdapter) + its replayed cassette | +| Shared Kernel | a small model two contexts jointly own | a shared **value-objects module** (e.g. a shared `LookupRecord`); costly — only when both truly co-change it | +| Customer-Supplier | upstream serves downstream's needs; downstream has influence | two internal contexts where one explicitly serves the other | +| Conformist | downstream accepts the upstream model as-is | a thin client that imports upstream types wholesale (no translation); cheap but couples the models | +| Open Host Service + Published Language | upstream publishes a standard protocol/schema to many consumers | an **exposed API contract** + its schema, when *we* are the upstream | +| Partnership | two contexts co-developing in tight collaboration | rare in a single-package app; common in larger orgs | +| Separate Ways | no integration — the contexts solve it independently | the answer when integration cost exceeds benefit; split instead | +| Big Ball of Mud | a messy boundary to contain, not extend | a legacy/external mess wrapped behind an ACL — never imported directly | + +### Selecting the pattern + +The choice turns on three questions. **Who has influence?** If the downstream has none over the upstream (a third-party API, a regulated service) → ACL. If both negotiate → Customer-Supplier. If the downstream willingly conforms → Conformist. **How many consumers?** One → direct integration; many → Open Host Service + Published Language. **Is integration worth it?** If the cost exceeds the benefit → Separate Ways. When unsure, default to the ACL — it is the safest (it isolates our model) and the one this workflow's adapter pattern already implements. + +### Every integration point names three things + +A seam between contexts is undefined until it names: (1) its **pattern** (above), (2) its **mechanism** (synchronous API / asynchronous event / shared store / file exchange), and (3) its **contract** (the schema, versioning, backward compatibility, error handling). An undefined seam is the primary source of coupling failures — flag it at `derive-source-stubs` rather than discovering it at build. + +## Related + +- [[software-craft/external-fixtures]] — the recorded exchange that the ACL wraps (relationship vs exchange; distinct layers) +- [[requirements/domain-decomposition]] — identifying the bounded contexts that this knowledge then relates +- [[requirements/aggregate-boundaries]] — the intra-context boundary (consistency); this knowledge is the inter-context boundary (relationship) +- [[architecture/quality-attributes]] — interoperability and model-purity are quality attributes the patterns address diff --git a/.opencode/knowledge/architecture/quality-attributes.md b/.opencode/knowledge/architecture/quality-attributes.md new file mode 100644 index 00000000..27c5e2f7 --- /dev/null +++ b/.opencode/knowledge/architecture/quality-attributes.md @@ -0,0 +1,66 @@ +--- +domain: architecture +tags: [quality-attributes, non-functional-requirements, atam, trade-offs, ilities] +last-updated: 2026-07-02 +--- + +# Quality Attributes + +## Key Takeaways + +- Quality attributes (the `-ilities`) are the architectural drivers — distinct from functional requirements. They are what the system *must be* (fast, available, secure, modifiable), not what it *does* (Bass, Clements & Kazman, 2021). +- Canonical set: Availability, Deployability, Interoperability, Modifiability, Performance, Security, Testability, Usability. Each has a **tactics catalog** (design moves that directly address it) and is made operational as a **scenario** (stimulus → environment → response). +- Attributes **conflict** — Performance vs Modifiability; Security vs Performance; Availability vs cost — and the architect resolves it by explicit prioritisation, not by optimising everything. +- Elicited in `interview-cross-cutting` as a cross-cutting concern; coverage-checked in `interview-building-blocks` (every quality attribute → ≥1 building block, the gap analysis of [[requirements/domain-decomposition]]). +- Load-bearing trade-offs between attributes are **architecturally significant decisions** — recorded as ADRs via the `record-decision` skill, not left implicit. +- The full ATAM ceremony (stakeholder utility-tree ranking) is trimmed for this flow: elicit the attributes that matter, surface the conflicts, record the trade-offs. Most quality attributes are qualitative at test-time; the tests assert behaviour, the ADR records the quality-attribute reasoning behind it. + +## Concepts + +**Architectural drivers, not functional requirements.** A quality attribute is a measurable property of the runtime or development-time system — how fast it responds, how available it stays, how easy it is to change — as opposed to a functional requirement, which describes behaviour. The architect's leverage is over the attributes: choosing an architecture is, largely, choosing which attributes to optimise and which to sacrifice. Treating them as an afterthought is how systems end up fast-but-unmaintainable, or secure-but-unusable (Bass, Clements & Kazman, 2021). + +**Scenarios make an `-ility` operational.** "The system must be performant" is unactionable; "a read request arrives at peak load; the system responds within 200 ms, 99th percentile" is a scenario that can be designed toward and tested against. The scenario form (stimulus, environment, response) is the bridge between a fuzzy `-ility` and a concrete design move — and it is what the interview elicits, not the bare word. + +**The tactics catalog.** Each attribute has known design moves: Performance uses caching, concurrency, resource arbitration; Availability uses redundancy, fault-detection, recovery; Modifiability uses encapsulation, substitution, binding-time deferral; Security uses authentication, authorisation, audit. Tactics are the building blocks the architect combines; architectural styles (layered, hexagonal, event-driven) are pre-combined tactic bundles optimised for different attributes (Bass, Clements & Kazman, 2021). + +**Conflicts force explicit trade-offs.** Performance (fewer indirections) fights Modifiability (more abstraction layers); Security (encryption, validation) costs Performance; Availability (redundancy) costs resources. The architect cannot satisfy all of them — the decision is *which matter most for this system*, and that decision is exactly what an ADR exists to record when it is load-bearing. + +**Where this lives in the flow.** Quality attributes surface at `interview-cross-cutting` (funnel level 2) alongside bounded contexts, integration points, and lifecycle events — the cross-cutting concerns the interview must capture. `interview-building-blocks` then runs the gap analysis: every quality attribute must map to ≥1 building block whose tactics address it (per [[requirements/domain-decomposition]]), or the gap is flagged. The system-architect at `derive-source-stubs` honours them implicitly (the type surface and adapter choices carry the tactics); the explicit record of any hard trade-off is an ADR. + +**Qualitative at test-time.** Most quality attributes are not directly asserted by the contract tests, which verify behaviour. Performance, availability, security posture are carried in the design (the tactics chosen) and the ADR (the reasoning), not in a `@pytest.mark.pending` test. The tests are the source of truth for *behaviour*; the ADR is the source of truth for the *quality-attribute reasoning* behind the architecture that produces that behaviour. + +## Content + +### The canonical set and a tactic each + +| Attribute | Concern | A representative tactic | +|---|---|---| +| Availability | uptime under fault | redundancy + failover + health checks | +| Deployability | ease + safety of release | environment parity + staged rollout | +| Interoperability | speaking to other systems | a published contract + an anti-corruption layer | +| Modifiability | ease of change without side effects | encapsulation + binding-time deferral | +| Performance | response time + throughput under load | caching + concurrency + resource arbitration | +| Security | resistance to unauthorised access | authentication + authorisation + audit | +| Testability | ease of verifying behaviour | observability + dependency injection + deterministic state | +| Usability | ease of correct use | consistent interface + clear error paths | + +### Conflicts and their trade-off + +| Conflict | The trade-off | +|---|---| +| Performance ↔ Modifiability | indirection costs cycles; abstraction eases change | +| Security ↔ Performance | encryption + validation add overhead | +| Availability ↔ cost | redundancy needs more resources | +| Interoperability ↔ model purity | a published contract invites external models in (use an ACL, per [[architecture/context-mapping]]) | + +A trade-off that ripples across contracts is architecturally significant — record it as an ADR (`record-decision` skill); a trade-off local to one module is BAU and is not recorded. + +### Eliciting in the interview + +`interview-cross-cutting` captures, per quality attribute the stakeholders care about, a one-line scenario (stimulus → response), not the bare word. "Performant" → "geocode + forecast under 500 ms at 10 req/s." "Available" → "the history write succeeds even if the external weather API is down." The scenario is what `interview-building-blocks` can map to a building block and its tactics. + +## Related + +- [[requirements/domain-decomposition]] — the gap analysis that maps every quality attribute → ≥1 building block +- [[architecture/context-mapping]] — interoperability and model-purity tactics across context boundaries +- [[requirements/ubiquitous-language]] — the glossary is where each attribute's project-specific name is registered diff --git a/.opencode/knowledge/design/accessibility.md b/.opencode/knowledge/design/accessibility.md new file mode 100644 index 00000000..3f5dd5b5 --- /dev/null +++ b/.opencode/knowledge/design/accessibility.md @@ -0,0 +1,64 @@ +--- +domain: design +tags: [accessibility, wcag-2-2, aria, keyboard, screen-readers, contrast, pour] +last-updated: 2026-07-02 +--- + +# Accessibility + +## Key Takeaways + +- **WCAG 2.2 is the current W3C Recommendation** (2023) — the standard to design and cite against. WCAG 3.0 is a working draft; it does not replace 2.x, and its contrast algorithm is undetermined (APCA was exploratory and was removed in 2023 — it is not "WCAG 3") (W3C, 2023; W3C, 2026). +- The principles are **POUR**: content must be Perceivable, Operable, Understandable, and Robust — every success criterion sits under one of these. +- **Semantic markup** is the foundation: the right HTML element (`<button>`, `<nav>`, `<label>`) carries meaning assistive tech reads for free; `aria-*` fills gaps, it does not replace semantics. +- **Keyboard navigation is non-negotiable**: every interactive element reachable in a logical order, a visible focus indicator, no keyboard traps. If it works only with a mouse, it is broken. +- **Contrast** has WCAG 2.2 floors (4.5:1 normal text; 3:1 large text + meaningful graphics); **color is never the only signal** (color-blind users + dark mode defeat it). +- Accessibility is a design decision made early, not a compliance pass at the end; retrofitting is more expensive than building it in, and WCAG 2.2 AA is increasingly a legal floor, not a nicety. + +## Concepts + +**The POUR spine.** Perceivable (the user can perceive the content — alternatives for sensory information). Operable (the user can navigate + interact — keyboard, no traps, enough time). Understandable (the content + operation are comprehensible — readable, predictable, error-tolerant). Robust (the content works with current + future assistive tech — parseable, compatible). Every WCAG success criterion nests under one of these; together they are the working definition of "accessible" (W3C, 2023). + +**WCAG 2.2 is the standard.** WCAG 2.2 (W3C Recommendation, October 2023) extends 2.1 and is the current conformance target. WCAG 3.0 is a multi-year working draft (March 2026); it does not deprecate 2.x, and conformance to 2.2 AA is expected to satisfy most of WCAG 3's minimum level once it finalises. Crucially, the WCAG 3 contrast algorithm is undecided — APCA was exploratory and was removed from the draft in 2023, so citing "APCA as WCAG 3" is wrong; design against the WCAG 2.2 ratios today (W3C, 2023; Roselli, 2026). + +**Semantic markup first.** The right native element is the cheapest accessibility win: a real `<button>` is keyboard-focusable, announces as "button," and fires on click + Enter + Space without any extra code; a `<div onclick>` is none of those. ARIA's rule of thumb: if you can use a native element or attribute with the semantics + behavior you need, do that; use `aria-*` only to fill what native HTML cannot express. ARIA cannot rescue non-semantic markup — a `role="button"` on a div still needs manual focus + keyboard handling that a real button gets free. + +**Keyboard, focus, traps.** Every interactive element must be reachable via Tab in a logical order, with a visible focus indicator (never `outline: none` without a replacement). The user must be able to escape any modal or widget with keyboard alone — a focus trap is a defect. Modal dialogs move focus into the dialog and return it on close; `Esc` dismisses. + +**Contrast + color-not-sole-signal.** Text/background contrast must meet the WCAG 2.2 floors (4.5:1 normal; 3:1 large). Color must not be the only carrier of meaning — an error state shown only in red is invisible to color-blind users; pair it with an icon, a word, or a shape. The same applies to links-in-prose (underline or a clear non-color differentiator). + +**A design decision, not a pass.** Accessibility built into the design (semantic structure, keyboard flows, contrast budget, error recovery) is cheap; retrofit is expensive and often incomplete. Treat WCAG 2.2 AA as the floor and design to it from the contract stage — the same stage at which error flows and feedback are designed. + +## Content + +### WCAG 2.2 contrast floors + +| Use | Minimum ratio | +|---|---| +| normal text (< 18pt / 24px regular; < 14pt bold) | 4.5:1 | +| large text (≥ 18pt / 24px regular; ≥ 14pt bold) | 3.0:1 | +| meaningful graphics + UI component boundaries | 3.0:1 | + +### The POUR quick-check + +| Principle | Ask | +|---|---| +| Perceivable | is there a text alternative for every non-text element? | +| Operable | can every interaction be completed with a keyboard, with a visible focus? | +| Understandable | is the language defined; are inputs + errors identified + actionable? | +| Robust | does the markup parse cleanly + expose correct roles/names/states to AT? | + +### ARIA's first rule + +Use native HTML when it can carry the semantics + behavior you need. Reach for `aria-*` only to fill a gap native HTML cannot — and then pair it with the keyboard handling a native element would have given you for free. + +### The WCAG 3 / APCA caveat + +WCAG 3.0 is a working draft; it does not replace 2.x. Its contrast algorithm is undecided — APCA was exploratory and was removed from the draft in 2023. Design against WCAG 2.2 ratios today; track WCAG 3 as it matures, but do not cite APCA as a standard (Roselli, 2026). + +## Related + +- [[design/visual-design]] — contrast floors + color-not-sole-signal are shared rules +- [[design/interaction-design]] — keyboard nav + error recovery are interaction-design concerns accessibility sharpens +- [[design/asset-design]] — assets carry accessible names + meet contrast floors +- [[design/cli-design]] — terminal accessibility (color-not-sole-signal, `NO_COLOR`, screen-reader-readable output) diff --git a/.opencode/knowledge/design/api-design.md b/.opencode/knowledge/design/api-design.md new file mode 100644 index 00000000..92c5cd97 --- /dev/null +++ b/.opencode/knowledge/design/api-design.md @@ -0,0 +1,75 @@ +--- +domain: design +tags: [api-design, rest, http, problem-details, rfc-9457, pagination, idempotency] +last-updated: 2026-07-02 +--- + +# API Design + +## Key Takeaways + +- An HTTP API is a user interface for developers; the same interaction-design rules apply — predictable, legible, with errors that help the consumer recover. +- Model **resources** (nouns), not procedure calls (verbs); the standard methods (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) carry the verb, and the URL names the resource (`/orders/{id}`, not `/getOrder`). +- Use **HTTP status codes** semantically and consistently: `2xx` success, `3xx` redirection, `4xx` the client made a mistake, `5xx` the server did. Do not overload `200` with an error body. +- Errors use **RFC 9457 Problem Details** — `application/problem+json` with `type` (a URI), `title`, `status`, `detail`, `instance`, plus optional extensions (`errors`, `code`, `traceId`). RFC 9457 (2023) supersedes RFC 7807 (2016); it is the current standard (Dalal, 2023). +- **Paginate** collections from the start (cursor pagination preferred over offset for stability under insertion); **version** the API deliberately (URL path or header); make safe-to-repeat operations **idempotent**. +- The API contract is documented in an **OpenAPI** description; the problem-detail schemas appear there so consumers know exactly what each endpoint can return. + +## Concepts + +**Resources, not procedures.** REST models the domain as resources identified by URIs, acted on by the standard HTTP methods. A URL names a thing (`/users/42/orders`); the method names the action (`POST` to create, `GET` to read). The benefit is predictability: a consumer who knows the resource model can guess the URLs and methods, and the contract is uniform across the API rather than bespoke per endpoint (Fielding, 2000). + +**Status codes carry outcome.** The status code is the API's exit-code equivalent — the consumer's fastest, most reliable branch. `200`/`201`/`204` for success (created, no-content); `400` for a malformed request, `401` unauthenticated, `403` forbidden, `404` absent, `409` conflict, `422` semantically invalid; `5xx` for server-side failure. Returning `200` with `{"error": "..."}` in the body defeats the consumer's status-based branching and is a common API smell. + +**Problem Details (RFC 9457).** Rather than invent a per-API error format, RFC 9457 defines a standard `application/problem+json` document: `type` (a URI identifying the problem type — the consumer's primary key, does not need to resolve), `title` (short summary, stable per type), `status` (the HTTP status), `detail` (this occurrence's specifics), `instance` (the specific URI occurrence), plus extensions like `errors` (a validation array with JSON Pointer locations), `code` (an API-specific code), or `traceId`. It is the current IETF standard, superseding RFC 7807 (Dalal, 2023). + +**Pagination, versioning, idempotency.** Collections too large to return whole are paginated; cursor pagination (a token pointing to the next page) is more stable than offset/limit because it does not skip or duplicate when items are inserted between calls. Versioning is a deliberate choice — a URL path segment (`/v1/`) is the most visible; a header is cleaner but less discoverable. Operations the consumer might retry (charging, sending) are made idempotent via an idempotency key so a duplicate request does not double the effect. + +**OpenAPI is the contract.** The API is described in an OpenAPI document: every path, method, request/response schema, and the problem-detail responses each endpoint can return. The schema for `application/problem+json` is defined once and `$ref`-ed where it applies. The document is the source both consumers and the test suite consult. + +## Content + +### Status code semantics (the load-bearing set) + +| Code | Meaning | Use | +|---|---|---| +| 200 OK | success with a body | standard read/update response | +| 201 Created | a new resource was created | `POST` that creates | +| 204 No Content | success, nothing to return | `DELETE`, a `PUT` returning no body | +| 400 Bad Request | malformed syntax | the consumer's request is unparseable | +| 401 Unauthorized | no/failed authentication | auth missing or invalid | +| 403 Forbidden | authenticated but not allowed | auth fine, authorization fails | +| 404 Not Found | the resource does not exist | (or 401 if you hide existence) | +| 409 Conflict | state conflict | duplicate, stale version | +| 422 Unprocessable Entity | semantic violation | well-formed but invalid | +| 5xx | the server failed | never the consumer's fault | + +### RFC 9457 problem+json (the error body) + +``` +HTTP/1.1 404 Not Found +Content-Type: application/problem+json + +{ + "type": "https://example.com/errors/user-not-found", + "title": "User not found", + "status": 404, + "detail": "User 42 does not exist.", + "instance": "/users/42" +} +``` + +`type` is the consumer's primary identifier (a URI, stable per problem type); `title` is the same for every occurrence of that type; `detail` is specific to this occurrence. Extensions (`errors` with JSON Pointers for validation, `code`, `traceId`) carry more without breaking the base shape (Dalal, 2023). + +### Pagination shapes + +| Style | Shape | When | +|---|---|---| +| cursor | `?cursor=<token>&limit=N` + a `next_cursor` in the response | the default — stable under insertion, preferred at scale | +| offset/limit | `?offset=N&limit=M` | simple collections stable enough that skip/duplicate is acceptable | + +## Related + +- [[design/interaction-design]] — predictability, errors-that-recover, and consistency apply to the API surface +- [[design/cli-design]] — a CLI wrapping an API composes the two design surfaces +- [[software-craft/external-fixtures]] — the cassette captures a real API exchange; this knowledge designs the contract the adapter implements diff --git a/.opencode/knowledge/design/asset-design.md b/.opencode/knowledge/design/asset-design.md new file mode 100644 index 00000000..803ff7e3 --- /dev/null +++ b/.opencode/knowledge/design/asset-design.md @@ -0,0 +1,58 @@ +--- +domain: design +tags: [asset-design, logo, banner, social-card, favicon, svg, dev-branding, open-graph] +last-updated: 2026-07-02 +--- + +# Asset Design + +## Key Takeaways + +- A Python project ships a small, fixed set of visuals — **one per use case**: a GitHub social card, a README banner, a logo/avatar, a favicon. Design each for where it lives; do not invent a brand system around them. +- The **GitHub social card** (open-graph image) is 1280×640 px; it is the project's face in link previews, so it carries the name + one line of intent + the mark, composed for the 2:1 frame. +- Produce assets as **self-contained SVG** (presentation attributes, no external references, no `<style>` blocks GitHub will strip) with an accessible `aria-label`/`<title>`; rasterise (PNG) only where the target requires it (the `.ico`, the apple-touch-icon). +- Honour **accessible contrast** in every asset (WCAG 2.2 floors) and provide a **dark-mode variant** where the asset will appear on both light and dark surfaces (README, GitHub). +- The dev-branding norm is **minimal**: one mark, generous whitespace, one accent. Vercel, Stripe, Linear, and the GitHub-ecosystem house style are the reference points — not heavy illustrative branding. +- A favicon or avatar must read at the size it is shown (32–64 px for avatars; 16 px for tab favicons); verify legibility at that size for those two assets only. It is a check, not a design philosophy. + +## Concepts + +**One asset per use case.** A developer project's visual surface is a fixed inventory — the social card, the README banner, the logo/avatar, and (optionally) a favicon. Each lives in a specific context at a specific size and is composed for that context, not for a hypothetical "brand system" that would scale from a tab favicon to a billboard. Designing a four-tier production apparatus around four images is the over-engineering this project rejects. + +**The social card is the project's face.** GitHub renders the repository's open-graph image (1280×640) in link previews on GitHub itself, in Slack, in social media, and in search. It is the single most-seen asset. It carries the project name, one line of intent (the tagline or purpose), and the mark — composed for the 2:1 frame, with the critical content inside the central 60–70% (some platforms crop the edges). + +**Self-contained, accessible SVG.** SVG is the source format: it scales, it is small, and it diffs cleanly in version control. The production SVG uses presentation attributes (`fill="#1a1a2e"`) rather than inline `<style>` (which some hosts strip), references nothing external (no `<use href="external">`, no web fonts), declares a square `viewBox` with padding, and carries an accessible name via `<title>` + `aria-labelledby` (or `role="img"` + `aria-label`). Raster formats (PNG, ICO) are exported from the SVG where a target demands them. + +**Accessible + dark-mode-aware.** Contrast floors (WCAG 2.2) apply to assets, not just UI text — a logo on a low-contrast background is inaccessible. Where the asset appears on both light and dark surfaces (a README that honours `prefers-color-scheme`, GitHub's theme-aware rendering), provide a variant per surface, or design a mark that holds on both (a monochrome mark with a transparent background is the simplest path). + +**The minimal dev-branding norm.** The reference aesthetic across respected developer projects is restraint: one mark (often a single geometric form or a wordmark), generous whitespace, one accent color, a single typeface. Heavy illustrative branding, gradients, and mascots read as over-invested for a library or a CLI. Match the norm unless the project's identity genuinely calls for more. + +**Legibility at the shown size — a check, not a philosophy.** The avatar (32–64 px in GitHub UIs) and the favicon (16 px in a browser tab) are the only assets that appear small. Verify they are legible at that size — simplify the mark if a thin stroke vanishes, drop a subtitle if it becomes unreadable. This is a final verification on two assets, not a multi-tier production process applied to all of them. + +## Content + +### The asset inventory for a Python project + +| Asset | Size | Where it lives | Key constraint | +|---|---|---|---| +| social card (open-graph) | 1280×640 | link previews (GitHub, Slack, social) | name + intent + mark in the central 60–70% | +| README banner | wide (e.g. 1280×320 or full-width) | top of the README | reads at README width; honours dark mode | +| logo / avatar | square (e.g. 512×512) | GitHub repo avatar, package page | legible at 32–64 px | +| favicon | square (16→512) | browser tab, bookmark | legible at 16 px; provide PNG + an `.ico` if required | + +### SVG production rules + +- presentation attributes (`fill`, `stroke`) over inline `<style>` — hosts strip `<style>`. +- self-contained: no `<use href>` to external, no web fonts, no base64 blobs. +- square `viewBox` (e.g. `0 0 512 512`) with 5–10% internal padding. +- accessible name: `<title>` + `aria-labelledby`, or `role="img"` + `aria-label`. +- convert strokes to filled paths for the production file; optimise (SVGO-style: strip metadata, collapse numeric precision). + +### Dark mode + +Provide a dark-surface variant for any asset shown on a theme-aware surface (README, GitHub), OR design a monochrome mark on a transparent background that holds on both. The `prefers-color-scheme` media query works in SVG rendered inline in HTML; for raster exports, ship two files. + +## Related + +- [[design/visual-design]] — hierarchy, contrast, typography apply to assets as much as to UI +- [[design/accessibility]] — contrast floors + accessible naming apply to every asset diff --git a/.opencode/knowledge/design/cli-design.md b/.opencode/knowledge/design/cli-design.md new file mode 100644 index 00000000..bd1c4976 --- /dev/null +++ b/.opencode/knowledge/design/cli-design.md @@ -0,0 +1,68 @@ +--- +domain: design +tags: [cli-design, terminal-ux, stdout-stderr, exit-codes, progressive-disclosure, no-color] +last-updated: 2026-07-02 +--- + +# CLI Design + +## Key Takeaways + +- A CLI has two audiences — a **human at a terminal** and a **script down a pipe** — and the default optimises for the human while giving the script an opt-in structured mode (`--json`) (clig.dev, 2024). +- **stdout carries payload; stderr carries diagnostics.** A pipeline that pipes stdout into another tool must never receive progress bars, log lines, or decoration (clig.dev, 2024). +- **Exit codes are first-class signals**: `0` for success; distinct non-zero codes for distinct failure modes, documented in `--help`. Scripts branch on them. +- **Errors are informative**: exit non-zero, write the message to stderr, and include the error code/title, what went wrong, and a suggested fix or URL — never a stack trace for a human audience. +- **Progressive disclosure**: strong defaults for the common case, every default overridable, simple things simple and hard things possible. The quiet default is the parsimony tie-in — a successful run prints little; verbosity is opt-in (`-v`, `--verbose`, `--debug`). +- **Color is for emphasis, not decoration**, stripped automatically when stdout is not a TTY or when `NO_COLOR` is set; symbols and emoji only where they aid scanning. + +## Concepts + +**Two audiences.** The same command is run interactively by a human and invoked by a script. The human wants formatted, colored, progressive output; the script wants a stable, parseable, minimal contract. The resolution is a default for the human and an opt-in for the machine: detect `isatty(stdout)`; emit formatted output to a terminal, structured output when `--json` (or `--output json`) is passed; strip ANSI codes either way when stdout is piped (clig.dev, 2024). + +**The output contract.** stdout is the payload — the data the user asked for or the success message a script checks for. stderr is everything else: progress, warnings, diagnostics, errors. Mixing them puts decoration in the payload and breaks pipelines. Long human output goes through a pager (`less`); the machine path never does. + +**Exit codes signal outcome.** A script's only reliable channel for branching is the exit code. `0` is success; non-zero is failure, and distinct non-zero codes for distinct failures (a usage error vs a permission error vs a not-found) let the script respond differently. Document the codes in `--help` so script authors can rely on them. + +**Informative errors.** A CLI error is the user's only feedback channel — there is no GUI to expand a dialog. So the message carries the code/title, a one-line explanation in the user's terms, and a suggested fix or a documentation URL; it goes to stderr; the process exits non-zero. A raw Python traceback is a debugging aid for the author, not an error for the user. + +**Progressive disclosure + parsimony.** The common case should work with no flags (strong defaults); every default is overridable; the `--help` shows the common case first and the advanced options later. Successful default runs are quiet — they print the result, or nothing, not a log of every step. Verbosity is a ladder: default (terse) → `-v` (what it did) → `--debug` (everything, for bug reports). This is the CLI form of the project's parsimony rule. + +**Color, symbols, TTY.** Color directs attention (green success, red error) but is stripped when stdout is not a TTY or when `NO_COLOR` is set (the `NO_COLOR` convention is an industry standard). Symbols and emoji (✓, ✗) aid scanning in a terminal but must not be the only signal (screen readers, font fallback). Never block on color — the output must read in plain monochrome too. + +## Content + +### Output channels + +| Channel | Carries | When | +|---|---|---| +| stdout | payload (the data; the success line) | always; the contract a script consumes | +| stderr | progress, warnings, errors, diagnostics | always; never piped into the next tool | +| exit code | outcome (`0` success; non-zero failure) | always; how scripts branch | + +### The verbosity ladder + +| Mode | Trigger | Output | +|---|---|---| +| quiet (default) | — | the result, or nothing on success | +| verbose | `-v` / `--verbose` | what the command did, one line per step | +| debug | `--debug` | everything, including internals, for bug reports | +| machine | `--json` / `--output json` | stable structured schema, no decoration | + +### Error anatomy (to stderr, exit non-zero) + +``` +error: cannot connect to <host>: connection refused + hint: check the host is reachable, or set API_BASE in ~/.secrets/<project>.env + docs: https://<project>/docs/errors#connection +exit: 2 (network) +``` + +### Machine-readable mode + +`--json` emits a documented, versioned schema; changing a field name is a breaking change. Strip ANSI + progress + symbols in this mode — the consumer is a parser, not an eye. + +## Related + +- [[design/interaction-design]] — feedback, errors, and progressive disclosure apply to the terminal surface +- [[design/accessibility]] — color-not-sole-signal, `NO_COLOR`, screen-reader-readable output +- [[software-craft/secrets-and-config]] — error hints point at `~/.secrets/`, never echo a value diff --git a/.opencode/knowledge/design/interaction-design.md b/.opencode/knowledge/design/interaction-design.md new file mode 100644 index 00000000..3ee2af1b --- /dev/null +++ b/.opencode/knowledge/design/interaction-design.md @@ -0,0 +1,61 @@ +--- +domain: design +tags: [interaction-design, ixd, feedback, affordance, error-design, mental-model, heuristics] +last-updated: 2026-07-02 +--- + +# Interaction Design + +## Key Takeaways + +- Interaction is a conversation: the user states an intent, the system replies with feedback, and every silent failure or opaque error is the system breaking its turn (Norman, 2013). +- Two gulfs divide user and system — the **gulf of execution** (can the user figure out what to do?) and the **gulf of evaluation** (can the user tell what happened?). Design closes both (Norman, 2013). +- **Affordances** are what an element suggests it can do; **signifiers** signal where the affordance lives. A button-shaped thing affords pressing; its label + style signify it. Without signifiers, affordances are invisible. +- **Feedback** confirms every action — received, in progress, succeeded, or failed — within a time the user can associate with the action. No feedback is itself a (broken) message. +- Errors are designed, not afterthoughted: **prevent** (constrain, confirm, default safely), **detect** (validate early, clearly), **recover** (an actionable message + a path forward). A good error often matters more than a smooth success. +- **Consistency** + **one primary action per screen** + **progressive disclosure** (show the common case, hide the rest behind a deliberate reveal) are the load-bearing heuristics; Nielsen's ten is the fuller canon (Nielsen, 1994). + +## Concepts + +**The conversation model.** Norman (2013) frames interaction as a dialogue: the user acts on a mental model of the system, the system responds, and the user updates the model from the response. A silent failure breaks the dialogue — the user's turn goes unanswered. An opaque error breaks it too — the reply is in a language the user cannot act on. The designer's job is to keep the dialogue coherent: every user action gets a system reply the user can interpret. + +**The two gulfs.** The gulf of execution is the distance between the user's intent and the actions the system offers — closed by discoverable, signified affordances and by matching the interface to the user's vocabulary, not the developer's. The gulf of evaluation is the distance between the system's state and the user's understanding of it — closed by legible state, continuous feedback, and results that read in the user's terms. Most "usability" problems sit in one gulf or the other (Norman, 2013). + +**Affordance and signifier.** An affordance is the possible action an object suggests (a flat plate affords pushing; a link affords clicking). A signifier is the perceptible cue that tells the user where the affordance is — the word "Push," the underlined blue text, the button shape. Digital interfaces have weak natural affordances, so signifiers carry the load; removing them (a flat grey rectangle that is somehow a button) is a common failure. + +**Feedback.** Every action deserves a reply, and the reply's latency sets its form: under ~100 ms feels immediate; ~1 s needs a "working" signal; over ~10 s needs progress + cancellation. The failure mode is not slowness but silence — a click that produces no visible change leaves the user unsure whether the system heard, is working, has failed, or has succeeded. + +**Designed errors.** The prevent→detect→recover sequence is the discipline. Prevent by constraining input (a date picker over free text), confirming destructive acts, and choosing safe defaults. Detect by validating as early as possible (client-side, at the field, not after a round trip) and reporting precisely. Recover by making the message actionable — name the problem in the user's terms, show the path to fix it, and preserve the user's work. A "something went wrong" toast is a designed error that failed its design. + +**Heuristics and structure.** Nielsen's ten heuristics (visibility of system status, match between system and real world, user control and freedom, consistency and standards, error prevention, recognition over recall, flexibility and efficiency, aesthetic and minimalist design, help users recognise and recover from errors, help and documentation) remain the working canon (Nielsen, 1994). In practice the load-bearing three are consistency (the same action looks and behaves the same way everywhere), one primary action per screen (the user always knows what to do next), and progressive disclosure (the common path is uncluttered; the rest is reachable but not in the way). + +## Content + +### Closing the two gulfs + +| Gulf | Question | Closed by | +|---|---|---| +| execution | "can I figure out what to do?" | signified affordances; the user's vocabulary; one clear primary action | +| evaluation | "can I tell what happened?" | legible state; feedback on every action; results in the user's terms | + +### Nielsen's ten heuristics (the canon) + +Visibility of system status · match between system and real world · user control and freedom · consistency and standards · error prevention · recognition rather than recall · flexibility and efficiency of use · aesthetic and minimalist design · help users recognise, diagnose, and recover from errors · help and documentation (Nielsen, 1994). + +### Error design — prevent, detect, recover + +| Layer | What the designer does | +|---|---| +| prevent | constrain input; confirm destructive acts; safe defaults; make the wrong action hard | +| detect | validate early and precisely; report at the point of error, not after a round trip | +| recover | actionable message in the user's terms; a visible path to fix; preserve the user's work | + +### Progressive disclosure + +Show the common case by default; reveal complexity only when the user asks for it (a "show advanced" toggle, a `--verbose` flag, a secondary panel). The principle is parsimony at the surface: the user pays attention only to what their current goal needs. + +## Related + +- [[design/visual-design]] — signifiers and hierarchy are visual; the two work together +- [[design/accessibility]] — a gulf the user cannot cross alone (perception, motor, cognition) is closed by accessible design +- [[design/cli-design]] · [[design/api-design]] — interaction for the terminal and HTTP surfaces diff --git a/.opencode/knowledge/design/visual-design.md b/.opencode/knowledge/design/visual-design.md new file mode 100644 index 00000000..66bc4004 --- /dev/null +++ b/.opencode/knowledge/design/visual-design.md @@ -0,0 +1,65 @@ +--- +domain: design +tags: [visual-design, hierarchy, contrast, typography, color, wcag-contrast, layout] +last-updated: 2026-07-02 +--- + +# Visual Design + +## Key Takeaways + +- Visual design's job is communication, not decoration: it tells the user what matters, what goes together, and what they can do — through **hierarchy**, **contrast**, **spacing**, and **alignment**. +- **Hierarchy** is built from four levers — size, weight, position, and spacing — and the user reads the page in the order they establish. If everything is emphasised, nothing is. +- **Contrast** carries meaning and legibility; text-against-background contrast has a hard floor (WCAG 2.2: 4.5:1 for normal text, 3:1 for large) below which the design is inaccessible, not just ugly (W3C, 2023). +- **Color is semantic**, not ornamental: it signals state (success/warning/danger), identity (brand), and structure (grouping). Reserve it for those jobs; the layout should hold without it (so the design still works for color-blind users and in dark mode). +- **Typography** is a small set of decisions with outsized effect: one or two typefaces, a defined weight/size scale (not arbitrary), generous line-height, and measure (line length) under ~75 characters for body text. +- **Whitespace and alignment** do the quiet work: alignment creates order the eye reads as "designed"; whitespace groups (proximity) and gives the content room to breathe. + +## Concepts + +**Communication, not decoration.** A visual surface that the user scans for 2 seconds must convey what matters, what groups with what, and what is actionable. Visual design is the discipline that engineers that scan. The decorative lens ("make it look nice") produces arbitrary choices; the communication lens produces a hierarchy the user reads correctly under time pressure. + +**Hierarchy from four levers.** Size (larger = more important), weight (bolder = more important), position (top-left in left-to-right reading order = seen first), and spacing (more space around = more important; less space between = grouped). The user's eye follows the gradient these create. The failure mode is flat hierarchy — every heading the same size, every element equally weighted — which forces the user to read everything to find anything. + +**Contrast has a floor.** Contrast is the perceptual distance between an element and its background. For text it has an accessibility floor set by WCAG 2.2 (4.5:1 for normal text, 3:1 for large text and for meaningful graphics), below which the text is unreadable for low-vision users and in adverse lighting (W3C, 2023). Contrast is also a hierarchy lever — a high-contrast primary heading against a low-contrast secondary one creates order without size changes. + +**Color as semantics.** Color signals state (green/success, yellow/warning, red/danger), identity (the brand accent), and structure (a tinted group). It should not be the only signal — color-blind users (and dark-mode inversions) defeat color-only coding, so pair color with a shape, label, or weight. Modern color systems layer tokens (primitive hex → semantic role → component), so `surface-action-primary` resolves to the brand accent and can be re-skinned without touching components. + +**Typography decisions.** One typeface (or two — a body + a display) is plenty. Define a type scale (a fixed set of sizes/weights) and use only those tokens. Body line-height around 1.5; measure (line length) 45–75 characters. Avoid the decorative — condensed faces, all-caps body, low-weight low-contrast text — for anything the user must read. + +**Whitespace and alignment.** Proximity groups: items close together are read as related, items far apart as separate. Alignment creates the order the eye reads as deliberate — a strong axis (left-aligned text, a grid) reads as "designed"; misalignment reads as "sloppy" and slows comprehension. Whitespace is not wasted space; it is the cheapest hierarchy lever available. + +## Content + +### Hierarchy levers and what each signals + +| Lever | Signals | Failure mode | +|---|---|---| +| size | relative importance | everything large → flat | +| weight | relative importance; emphasis | everything bold → no emphasis | +| position | reading order | primary action buried → lost | +| spacing | grouping (proximity) and importance | uniform spacing → nothing groups | + +### WCAG 2.2 contrast floors + +| Use | Minimum ratio | +|---|---| +| normal text (< 18pt / 24px, or < 14pt bold) | 4.5:1 | +| large text (≥ 18pt / 24px, or ≥ 14pt bold) | 3:1 | +| meaningful graphics + UI components | 3:0 | + +Verify pairs with a contrast checker, not by eye; perceived contrast shifts with surrounding color and screen calibration (W3C, 2023). + +### A minimal type scale + +Define sizes as tokens (e.g. `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) and weights (`font-regular`, `font-medium`, `font-semibold`, `font-bold`); use only those. Body at `text-base`/`font-regular`; headings step up size + weight together. One typeface family with a full weight range outperforms several decorative families. + +### Color roles (semantic, not visual) + +Primitive tokens (raw hex) feed semantic tokens (`text-primary`, `surface-action`, `border-muted`, `state-success/warning/danger`) that feed component tokens. Components consume semantics, never primitives — so a re-skin (brand change, dark mode) is a token-layer change, not a component rewrite. + +## Related + +- [[design/interaction-design]] — signifiers and hierarchy are how the user reads what they can do +- [[design/accessibility]] — contrast floors + color-not-sole-signal are accessibility rules +- [[design/asset-design]] — the same hierarchy/contrast/typography apply to banners + logos diff --git a/.opencode/knowledge/methodology/knowledge-files.md b/.opencode/knowledge/methodology/knowledge-files.md index 7abb8b7d..efdb2a54 100644 --- a/.opencode/knowledge/methodology/knowledge-files.md +++ b/.opencode/knowledge/methodology/knowledge-files.md @@ -22,7 +22,7 @@ last-updated: 2026-07-01 **Correspondence.** The four sections are ordered by depth, and the depth is also structure: bullet N in Key Takeaways expands to paragraph N in Concepts and to subsection N in Content. A reader who jumps from a takeaway to its detail must land on the matching concept. Breaking correspondence strands the reader at the wrong depth. -**Depth deepens progressively.** Each tier does a different job. Key Takeaways is austere reference — the firm principle, scannable, consulted rather than read (Diátaxis, Procida). Concepts is explanation — the reasoning that turns a rule into understanding. Content is the learning tier — it teaches the topic, expanding each concept with the source's actual mechanism and using tables, criteria, and examples so a reader can recognise an instance and tell it from its neighbours. Content that merely restates Concepts in more words has failed: it must be deeper, never thinner. +**Depth deepens progressively.** Each tier does a different job. Key Takeaways is austere reference — the firm principle, scannable, consulted rather than read (Diátaxis, Procida). Concepts is explanation — the reasoning that turns a rule into understanding. Content is the learning tier — it teaches the topic, expanding each concept with the source's actual mechanism and using tables, criteria, and examples so a reader can recognise an instance and tell it from its neighbours. Content that merely restates Concepts in more words has failed: it must be deeper, never thinner. Across all tiers, scrub AI language markers — the prose form of the same parsimony — per [[writing/ai-language-markers]]. **Wikilink routing.** Skills are the authority on when to load knowledge; the wikilink is the address. A fragment selects the cut: `#key-takeaways` loads frontmatter and Key Takeaways; `#concepts` loads through Concepts; no fragment loads the whole file. Extraction is cumulative and cuts from the top. @@ -124,3 +124,4 @@ Each file's Related section lists its neighbours. The graph is the union of thos - [[methodology/separation-of-concerns]] - [[methodology/agent-files]] - [[methodology/skill-files]] +- [[writing/ai-language-markers]] diff --git a/.opencode/knowledge/methodology/research-files.md b/.opencode/knowledge/methodology/research-files.md index bfb7e298..c4dba02d 100644 --- a/.opencode/knowledge/methodology/research-files.md +++ b/.opencode/knowledge/methodology/research-files.md @@ -49,7 +49,7 @@ When a source is cited in knowledge but its exact provenance cannot be confirmed ### Capture the mechanism -The `Mechanism` field is where the card earns its depth. A paraphrase of the title — "this book is about refactoring" — leaves a reader unable to tell whether the citation supports a specific claim about extract method versus one about code smells. The field carries the source's actual machinery: for Moskvin 2025, that vcrpy records verbatim and does not scrub, that the generic Presidio-based scrubber is over-engineered at 670 MB, and that the author lands on JSON-Pointer field redaction via `before_record_response`; for Turmyshev 2026, that external is defined as "any dependency that introduces network latency, rate limits, or data you don't control" and that internal services and repositories are never stubbed. A reader of the card can then decide whether the citation supports the claim the knowledge makes. +The `Mechanism` field is where the card earns its depth. A paraphrase of the title — "this book is about refactoring" — leaves a reader unable to tell whether the citation supports a specific claim about extract method versus one about code smells. The field carries the source's actual machinery: for Moskvin 2025, that vcrpy records verbatim and does not scrub, that the generic Presidio-based scrubber is over-engineered at 670 MB, and that the author lands on JSON-Pointer field redaction via `before_record_response`; for Turmyshev 2026, that external is defined as "any dependency that introduces network latency, rate limits, or data you don't control" and that internal services and repositories are never stubbed. A reader of the card can then decide whether the citation supports the claim the knowledge makes. Apply the prose bar per [[writing/ai-language-markers]] — scrub AI markers (`delve`, `tapestry`, `plays a crucial role`, `rather than`) from the card's prose; the Mechanism field earns its depth through the source's machinery, not formal-sounding padding. ### Auditable inline citations @@ -62,8 +62,8 @@ Cards live under `docs/research/` in a taxonomy that mirrors source disciplines, ``` docs/research/ psychology/{social,cognitive}/ - software-engineering/{quality,process,requirements}/ - information-science/{domain-modeling,documentation}/ + software-engineering/{architecture,quality,process,requirements}/ + information-science/{domain-modeling,documentation,writing}/ README.md ``` @@ -73,3 +73,4 @@ A new card is copied from `.templates/docs/research/card.md.template` (the `.tem - [[methodology/knowledge-files]] - [[methodology/separation-of-concerns]] +- [[writing/ai-language-markers]] diff --git a/.opencode/knowledge/software-craft/docstring-lifecycle.md b/.opencode/knowledge/software-craft/docstring-lifecycle.md new file mode 100644 index 00000000..f9e1ea70 --- /dev/null +++ b/.opencode/knowledge/software-craft/docstring-lifecycle.md @@ -0,0 +1,59 @@ +--- +domain: software-craft +tags: [docstrings, lint, lifecycle, token-economy, format] +last-updated: 2026-07-02 +--- + +# Docstring and Lint Lifecycle + +## Key Takeaways + +- Docstrings are human-language duplicates of code; during active development they cost tokens on every read and drift on every edit, so source `.py` is kept **naked** across red/green/refactor/review/ship and regenerated at deliver/merge from the stable code. +- Tests and stubs carry no docstrings, ever — tests ARE the spec (their names and bodies document behaviour) and PEP 484 stubs are signature-only (a docstring in a `.pyi` is forbidden — PYI021). +- Models add docstrings by training instinct; instruction alone does not suppress it. The `select` state enforces nakedness **mechanically** by running `scripts/strip_docstrings.py` over the target source `.py` at cycle entry, removing any docstring carried over from the last merge — the script is the backstop, not the prompt. +- Lint splits the same way: **bug-catchers run throughout** (the dev `ruff` select); restructuring lint (`SIM`, `RUF`) and `ruff format` run **at merge** via `task lint-merge`, so a dev edit is not churned by readability reordering mid-cycle. +- ruff itself cannot ban or remove docstrings (no rule flags a docstring's *presence* in `.py`; `PYI021` is `.pyi`-only), which is why the strip is a script and the docstring ban is not encoded as a ruff rule. + +## Concepts + +**Naked during dev, dressed at merge.** A docstring restates the code beneath it in prose. While the code is being written and rewritten — the whole of red/green/refactor/review — that prose is a stale duplicate dragging on every read (more tokens) and every edit (a code change forces a duplicate change, or the duplicate drifts). The phased answer is to keep source `.py` docstring-free for the entire build cycle and generate the docstrings once, at deliver/merge, from code that has stabilised. The duplication tax is paid once per cycle at merge, not continuously through dev. Tests and stubs are excluded: a test's documentation IS its body (editing the body edits the spec), and a stub is a PEP 484 signature (`...` only; a docstring there is a PYI021 violation). + +**The instinct is real; the script is the backstop.** Models are trained on docstring-rich code and reach for them by reflex — strong enough that an instruction ("do not write docstrings during build") leaks. The mechanical defence runs at `select`: the strip script walks the target `.py`'s AST, finds every docstring node, and deletes its line range, surgically, without reformatting the surrounding code. Whatever the instinct slipped in is gone before red runs. The strip runs at cycle entry, not on every commit, because the source `.py` is re-read and re-edited through the cycle and a single entry-point strip keeps it naked for the duration. + +**Lint splits dev from merge.** The same churn argument applies to lint that restructures for readability — `SIM` collapsing a nested `with`, `ruff format` reordering imports and whitespace. Mid-cycle, a format pass inflates the diff with non-semantic changes and fights the edit in progress. The dev `ruff` select is bug-catchers only (`A`, `ASYNC`, `B`, `C9`, `DTZ`, `ERA`, `F`, `G`, `LOG`, `PYI`, `S`) — `PYI` stays because it scopes to `.pyi` and enforces the naked-stub rule without touching `.py`. The restructure set (`SIM`, `RUF`) plus `ruff format` move to `task lint-merge`, run by `merge-to-dev` after the docstrings are generated, so dev stays quiet and the merged result is clean. + +**Why ruff cannot do this.** ruff's `D`/pydocstyle rules either *require* docstrings (D100–D107) or police their *style* (D200+); none flags a docstring's *presence* as a violation, and ruff has no autofix that strips docstrings from `.py` (the project verified this at the start — `PYI021` strips them only in `.pyi`). So "no docstrings during dev" is not expressible as a ruff rule; the AST strip script is the substitute, and the `D` rules are not used at all (the merge step *generates* docstrings; it does not *enforce* their presence via lint). + +## Content + +### The lifecycle + +| Phase | Source `.py` docstrings | Tests / stubs | Lint | +|---|---|---|---| +| plan (author/review/write/derive/simulate) | n/a (no `.py` yet) | naked (permanent) | dev select, `.pyi` via `PYI` | +| build (select/red/green/refactor/review/ship) | **naked** — `select` strips the target | naked | dev select only | +| deliver (merge) | **generated** for the shipped surface | naked | `task lint-merge` (add `SIM`, `RUF`, `format`) | + +### The strip mechanic + +`scripts/strip_docstrings.py <file>` parses the file, collects the `[lineno, end_lineno]` of every module/class/function docstring, and deletes those line ranges from the bottom up (so earlier line numbers stay valid). Every other line — formatting, comments, blanks — is preserved; the script does not reformat. It assumes a body is not docstring-only (true for real rework `.py`); it runs at `select` over the chosen target source `.py`, so red/green/refactor operate on naked code for the whole cycle. + +### The merge generate step + +`merge-to-dev`, after the squash-merge, regenerates docstrings for the public surface of every contract shipped this cycle (modules, classes, public functions and methods). The prose is faithful to the code, never a mechanical restatement of the signature; the *why* of an architectural decision lives in an ADR, not a docstring. Then `task lint-merge` runs (`ruff check --extend-select SIM,RUF .` plus `ruff format .`) and the result is committed on dev. The next cycle's `select` strips these docstrings from whatever file it touches next — they are a derived, regenerable view, never a carried artifact. + +### The lint split + +| Set | Where | Rules | +|---|---|---| +| dev (always) | plan-simulate gate; build gates; `ruff check .` | `A`, `ASYNC`, `B`, `C9`, `DTZ`, `ERA`, `F`, `G`, `LOG`, `PYI`, `S` | +| merge (deliver only) | `task lint-merge` | add `SIM`, `RUF`; then `ruff format .` | + +`PYI` stays in the dev set because it applies only to `.pyi` and enforces the naked-stub rule (PYI021); it does not churn `.py`. `SIM` is deferred because it restructures (the nested-`with` collapse that once forced a mid-build test edit is the canonical case); `RUF` is mixed and deferred with it for simplicity. + +## Related + +- [[software-craft/tdd]] — the red/green/refactor cycle that runs on naked code +- [[software-craft/code-review]] — review gates the cycle output; the docstring state at review is naked +- [[software-craft/source-stubs]] — stubs are signature-only (PYI021); the docstring ban there is permanent +- [[software-craft/git-conventions]] — the squash-merge at which docstrings are regenerated diff --git a/.opencode/knowledge/software-craft/tdd.md b/.opencode/knowledge/software-craft/tdd.md index 41e541f5..2f62c826 100644 --- a/.opencode/knowledge/software-craft/tdd.md +++ b/.opencode/knowledge/software-craft/tdd.md @@ -13,6 +13,7 @@ last-updated: 2026-07-01 - Green writes the **minimum code** to turn the tests green, implementing the `.py` from its fixed `.pyi`. YAGNI and KISS override every other principle; a hard-coded value is correct when the test needs only that value (Beck & Jeffries, 1999; North, 2006). - Refactor restructures the `.py` while the `.pyi` and the tests stay **frozen and green**; it is design-only, never convention compliance — conventions run in CI. A change that needs the `.pyi` is a contract gap escalated at review. - The cycle runs **per contract** — a source module and the tests that exercise it — in outside-in dependency order; stubtest is scoped to the modules built this cycle. +- Source `.py` is kept **naked of docstrings** across the whole cycle — `select` strips any carried over from the last merge, and docstrings are regenerated at deliver/merge from the stable code per [[software-craft/docstring-lifecycle]]. Tests and stubs are naked permanently. ## Concepts @@ -22,7 +23,7 @@ last-updated: 2026-07-01 **Minimum code, YAGNI first.** Green writes the simplest code that passes the tests, and "simplest" is enforced by a priority: YAGNI (Beck & Jeffries, 1999) trumps everything — if no test requires it, it is not written — and KISS trumps DRY, because a small duplication is often simpler than the wrong abstraction. Hard-coded values are not just permitted but correct when the test supplies only that value; a configurable constant invented for a future the tests do not describe is exactly the speculative generality YAGNI forbids. -**Refactor under green, design only.** Refactor improves the `.py`'s structure while every test stays green, because the tests are the safety net that makes restructuring safe. Two boundaries are fixed: the `.pyi` does not move (a refactor that needs to change it has found a contract gap, escalated at review), and conventions do not run (no docstrings, no formatting pass — those are CI's job). Refactor is where SOLID, Object Calisthenics, and the smell catalogue are applied, each when its symptom appears, never speculatively. +**Refactor under green, design only.** Refactor improves the `.py`'s structure while every test stays green, because the tests are the safety net that makes restructuring safe. Two boundaries are fixed: the `.pyi` does not move (a refactor that needs to change it has found a contract gap, escalated at review), and conventions do not run (no docstrings, no formatting pass — those are merge-time per [[software-craft/docstring-lifecycle]]). Refactor is where SOLID, Object Calisthenics, and the smell catalogue are applied, each when its symptom appears, never speculatively. **Per contract, in dependency order.** The unit of work is one contract: a source module and the tests that exercise it, taken through the whole cycle. Contracts are picked in outside-in dependency order so that a module is built only after the modules it imports; a shared foundation module with no external boundary of its own is pulled in alongside the first contract that depends on it. stubtest runs scoped to the modules built this cycle, because the whole-suite run would false-fail on unbuilt sibling stubs. @@ -61,7 +62,7 @@ Removing the `@pytest.mark.pending` decorator can orphan its `import pytest` whe |---|---| | restructure the `.py` | edit the `.pyi` (escalate a contract gap) | | apply SOLID / Object Calisthenics / smell fixes when triggered | edit the tests | -| design improvement only | convention compliance (docstrings, formatting — CI's job) | +| design improvement only | convention compliance (docstrings, formatting — merge-time per [[software-craft/docstring-lifecycle]]) | ### Per contract, in dependency order @@ -77,3 +78,4 @@ Removing the `@pytest.mark.pending` decorator can orphan its `import pytest` whe - [[software-craft/source-stubs]] — the fixed `.pyi` green implements to - [[software-craft/refactoring-techniques]] — the moves refactor applies - [[software-craft/code-review]] — the review that gates the cycle's output +- [[software-craft/docstring-lifecycle]] — source `.py` stays naked through the cycle; docstrings regenerate at merge diff --git a/.opencode/knowledge/workflow/flowr-operations.md b/.opencode/knowledge/workflow/flowr-operations.md new file mode 100644 index 00000000..c443f652 --- /dev/null +++ b/.opencode/knowledge/workflow/flowr-operations.md @@ -0,0 +1,124 @@ +--- +domain: workflow +tags: [flowr, state-machine, session, subflow, evidence, cli, routing] +last-updated: 2026-07-02 +--- + +# flowr Operations + +## Key Takeaways + +- flowr is a non-deterministic state machine **specification** — a YAML file declares structure (states, transitions, guards), not behaviour; flowr never runs the work, it routes (nullhack/flowr, 2026). +- Drive one state at a time: `check` reads the current state's attrs; the orchestrator dispatches the owner named in `dispatch_to`; the owner asserts evidence; `transition` advances. This is the whole loop. +- A state with `flow:`/`flow-version:` is a **subflow pointer**: entry pushes a stack frame, exit pops it; the parent's `next` key must match the child's exit name; `session init` auto-enters the first subflow. +- Escalations re-enter the target subflow at its **first state** — flowr keeps no position memory — so `build → plan` on a contract gap re-runs plan from `author-test-stubs`, and `plan/explore → discover` re-runs the interview funnel from the top. +- A guarded transition fires only when its condition group is satisfied; the orchestrator asserts evidence with `--evidence key=value` (one per condition key). flowr **collects asserted evidence, it does not run checks** — CI is the enforcement backstop per [[methodology/separation-of-concerns#evidence-vs-enforcement]]. +- Sessions persist to `.cache/sessions/<name>.yaml` (filesystem is the source of truth); `state.attrs` is a free-form `dict`, so the key names (`dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`) are project convention, not enforced by flowr. + +## Concepts + +**Specification, not engine.** A flow file declares the graph: states with attributes, transitions with optional guards, exits. flowr validates the graph (seven MUST checks at load — every `next` resolves, no ambiguous targets, parent `next` keys match child `exits`, no cross-flow cycles, exits referenced, named conditions resolve, defaulted params supplied), queries it (`check`, `next`), and advances it (`transition`). It has no opinions about retries, timeouts, or error handling, and it never executes the dispatched work — that is the external agent's job (nullhack/flowr, 2026). + +**The state-reading loop.** The orchestrator never improvises routing. At each step it runs `check` to read the current state's attrs — `dispatch_to` (the one owner), `skills` (the procedures), `input artifacts` (what must be on disk), `output artifacts` (what may be written), `git branch`, and `conditions` (any guarded transitions). It verifies the inputs exist, dispatches the owner with the skill paths and inputs, then asserts the owner's evidence to fire the next `transition`. One state, one dispatch. + +**Subflows and the call stack.** A state carrying `flow:` is a pointer into a child flow; entering it pushes a frame `({parent_flow, parent_state})` onto a stack and sets the session to the child's first state. When a transition's target is one of the child's exit names AND the stack is non-empty, flowr pops the frame, restores the parent, and follows the parent state's transition for that exit name — which may itself enter the next subflow. This is how `pipeline-flow` chains discover → explore → plan → build → deliver → shipped through five subflows. + +**No position memory on escalation.** When a subflow exits on an escalation trigger (e.g. `needs-contracts`, `needs-elicitation`), the parent routes back to the subflow's entry, and re-entry lands at the child's FIRST state — not at the state where it left off. A rework loop therefore re-runs the whole subflow pass; the gates re-verify everything. This is deliberate (a contract change can ripple) but means escalation is heavier than a resume. + +**Conditions and evidence.** A `next` entry shaped `{to: <state>, when: <name>}` is guarded; the named group lives under the state's `conditions:` block, a map of `{key: expression}` (operators `== != >= <= > <`, plain value = `==`). The orchestrator fires the transition by passing `--evidence key=value` for each key. flowr evaluates the assertion; it does not verify the claim is true — that is CI's job. The evidence keys the temple8 flows use are listed in `AGENTS.md`. + +**attrs is free-form.** flowr treats `state.attrs` as an opaque dict; the keys `dispatch_to` / `skills` / `input artifacts` / `output artifacts` / `git branch` / `specialists` / `conditions` are this project's convention for binding a state to an owner, a procedure, artifacts, and a branch. None are enforced by the engine — they are read by the orchestrator and the agents. Renaming a key changes the convention, not the spec. + +## Content + +### Command reference + +All commands: `uv run python -m flowr <command>`. Output is JSON by default. `--session <id>` makes any command session-aware. + +| Command | Purpose | +|---|---| +| `session init <flow> --name <id>` | Create a session (auto-enters the first subflow) | +| `check --session <id>` | Current state: attrs + available transitions | +| `check --session <id> <trigger>` | A specific transition's conditions (open/blocked + the keys needed) | +| `next --session <id> [--evidence k=v …]` | Valid transitions, marked open/blocked by the evidence given | +| `transition <trigger> --session <id> [--evidence k=v …]` | Advance (fires only if guarded conditions are met) | +| `session show --name <id>` | Session state + the subflow call stack | +| `states <flow>` | List states in a flow | +| `validate <flow.yaml>` | Run the seven MUST checks on one flow file | +| `config` | Resolved config (flows_dir, sessions_dir, defaults from `pyproject.toml`) | +| `export` / `serve` | Visualisation (mermaid / viz server) | + +Sessions live at `.cache/sessions/<id>.yaml` (gitignored). `--flows-dir` overrides the configured flows directory for one invocation. + +### The state-driving protocol + +1. `check --session <id>` → parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. +2. Verify every `input artifacts` path exists on disk — missing = stop, do not assume (Golden Rule). +3. Dispatch the `dispatch_to` owner as a subagent, with the `skills` paths (`.opencode/skills/<name>/SKILL.md`, listed order = execution order) and the input artifacts. The owner writes only to `output artifacts`. +4. The owner returns asserted evidence (e.g. `stubtest-clean=true`). +5. `transition <trigger> --session <id> --evidence k=v …` fires the guarded advance; `next --session <id>` previews open/blocked if unsure. +6. Repeat from 1 at the new state. One state = one dispatch. + +### Subflow mechanics + +| Event | What flowr does | +|---|---| +| Enter a state with `flow:` | push `({parent_flow, parent_state})`, set session to child's first state | +| Transition target is a child exit name + stack non-empty | pop the frame, restore parent, follow the parent's transition for that exit | +| Escalation exit (e.g. `needs-contracts`) | parent routes back to the subflow's entry → re-enters at FIRST state (no resume) | +| Terminal exit (`shipped`) | stack empties; session is done | + +Parent `next` keys must match child `exits` exactly (a validation error otherwise). Within-flow cycles are allowed (the tdd red/green/refactor loop); cross-flow cycles are not. + +### Conditions and evidence + +A guarded transition under a state: +```yaml +states: + - id: review-test-stubs + conditions: + accepted: + interview-consistent: true + scope-integration-e2e-only: true + happy-paths-complete: true + next: + accepted: { to: write-test-py, when: accepted } + needs-stubs-rework: author-test-stubs +``` +Firing `accepted` requires all three keys; the orchestrator asserts them: +``` +flowr transition accepted --session <id> \ + --evidence interview-consistent=true \ + --evidence scope-integration-e2e-only=true \ + --evidence happy-paths-complete=true +``` +`needs-stubs-rework` is bare (no guard) — it fires without evidence. + +### Gate evidence keys + +The temple8 flows' guarded transitions and the evidence the orchestrator asserts (`=true` unless noted): + +| Flow / state | Trigger | Evidence keys | +|---|---|---| +| plan / review-test-stubs | `accepted` | `interview-consistent`, `scope-integration-e2e-only`, `happy-paths-complete` | +| plan / simulate-contracts | `accepted` | `pyright-consistent`, `no-orphans`, `traceability-complete`, `layer-order-respected`, `test-stubs-consistent`, `lint-clean`, `simulation-passed` | +| tdd / red | `contract-red` | `test-status=red`, `red-reason-is-ours=true` | +| tdd / green | `test-green` | `test-status=green`, `stubtest-clean=true` | +| tdd / review | `approved` | `impl-matches-contract`, `source-quality-clean`, `stubtest-clean`, `tests-green` | +| deliver / merge | `merged` | `tests-green-on-dev`, `stubtest-clean-on-dev` | + +Bare transitions (no `when:`) fire without evidence — e.g. the `select → red` advance, the escalate exits (`needs-contracts`, `needs-elicitation`, `needs-capture`), and `all-built → shipped`. + +### Validation + +`validate <flow.yaml>` returns `{valid: true, violations: []}` or a list of the seven MUST-check failures. Validate every flow after an edit: +``` +for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done +``` + +## Related + +- [[methodology/separation-of-concerns#evidence-vs-enforcement]] — why flowr collects asserted evidence and CI enforces +- [[methodology/agent-files]] — what `dispatch_to` resolves to (the owner identity) +- [[methodology/skill-files]] — what `skills` resolves to (the per-state procedure) +- [[methodology/knowledge-files]] — how the owner's loaded knowledge is cited diff --git a/.opencode/knowledge/writing/ai-language-markers.md b/.opencode/knowledge/writing/ai-language-markers.md new file mode 100644 index 00000000..71ae84ea --- /dev/null +++ b/.opencode/knowledge/writing/ai-language-markers.md @@ -0,0 +1,62 @@ +--- +domain: writing +tags: [ai-language-markers, ai-tells, rlhf-bias, prose-quality, parsimony] +last-updated: 2026-07-02 +--- + +# AI Language Markers + +## Key Takeaways + +- LLMs overuse a stable set of words: corpus analysis of 14M PubMed abstracts found certain "style words" spiked abruptly with LLM adoption — `delve`, `intricate`, `underscore`, `showcasing`, `pivotal`, `realm`, `meticulously`, `multifaceted` — and at least 10% of 2024 abstracts were LLM-processed (Kobak et al., 2024). +- The strongest single-word tell is a hedging verb: `ensuring` is over-represented 4.3× in AI text, joined by a family (`highlights`, `supports`, `reflects`) the model reaches for when padding an idea to sound considered (Jackson, 2026). +- The strongest multi-word tell is `rather than` (2.5×; 17,251 vs 6,859 occurrences in an 80,141-pair corpus) — how the model hedges a comparison instead of making one (Jackson, 2026). +- Structural tells survive prompt rewrites longer than vocabulary: low **burstiness** (uniform 18–24-word sentences), the rule-of-three, and over-qualified claims ("can be a useful tool for many writers in certain situations"). Em-dashes are a weaker signal than their reputation (2.6×, not the caricature) (Jackson, 2026; Duey, 2026). +- The mechanism is RLHF bias, not architecture or training data alone — human preference feedback amplifies "neutral-competent" formal prose, the same instinct that reaches for docstrings unprompted (Kobak et al., 2024; [[software-craft/docstring-lifecycle]]). +- This is the prose analog of the docstring strip: a backstop against the training instinct. When authoring knowledge, ADRs, the glossary, or skills, scrub these markers — no single one is diagnostic, but several in one passage reads as unthinking generation. + +## Concepts + +**Vocabulary overrepresentation.** LLMs overuse a stable lexicon. Kobak et al. (2024) studied 14 million PubMed abstracts (2010–2024) and identified 21 "focal words" whose frequency spiked with LLM adoption — `delve`, `intricate`, `underscore`, `showcasing`, `pivotal`, `realm`, `meticulously` among them — estimating at least 10% of 2024 abstracts were processed by an LLM (up to 30% in some sub-corpora). A co-occurrence study found `delve`/`realm`/`underscore` rising up to 85-fold in 2023–2024 versus pre-2022 (medRxiv, 2024). These words appear in formal writing the models were trained on, then RLHF amplifies them because reviewers rate the formal-sounding variant higher. + +**Hedging verbs and filler.** The model inflates significance: every topic is `pivotal`, every change `shapes` something, every feature `serves as` something. In an 80,141-pair humanization corpus, `ensuring` is over-represented 4.3× and `rather than` 2.5× (17,251 vs 6,859 occurrences) — the single strongest word and multi-word tells respectively (Jackson, 2026). The copula-avoidance pattern (`serves as` instead of `is`) and significance-inflation (`crucial`, `vital`, `key`) are the same reflex: padding an idea to sound considered rather than stating it. + +**Structural formulaicity.** Vocabulary is the visible signal; structure is the persistent one. AI text has low burstiness — sentences settle into a 18–24-word metronome — and leans on the rule-of-three, the `Not X, but Y` construction, and over-qualified claims ("can be a useful tool for many writers in certain situations") that optimise for plausible deniability over meaning (Jackson, 2026; Duey, 2026). Em-dashes are a real but weaker tell (18.5% of AI inputs contain ≥1 vs 7.1% humanised, a 2.6× effect) — downgraded from their 2024 reputation (Jackson, 2026). + +**Chatbot artifacts.** Conversational voice markers — `Absolutely!`, `Great question!`, `Let me break this down`, excessive bold formatting — index the "helpful assistant" role rather than content. They are distinct from the content markers above and persist in any conversational output. + +**Multi-signal, RLHF-driven.** No single marker is diagnostic; detection scores vocabulary, structure, hedging, and cadence together, with cadence uniformity surviving longest across rewrites (Duey, 2026). The root cause is reinforcement learning from human feedback: reviewers consistently prefer the formal, hedged, "neutral-competent" variant, which narrows style toward technically-correct but distinctive-free prose (Kobak et al., 2024). This is the same instinct that reaches for docstrings unprompted — and the reason the backstop is a scrub, not an instruction. + +## Content + +### Vocabulary to scrub (overrepresented in AI text) + +`delve`, `tapestry`, `intricate`, `multifaceted`, `pivotal`, `realm`, `underscore`, `showcasing`, `meticulous(ly)`, `testament`, `vibrant`, `breathtaking`, `robust`, `seamless`, `leverage`, `navigate`, `landscape`, `journey`. None is banned — each occurs in good human writing — but several in one passage signal unthinking generation (Kobak et al., 2024; Jackson, 2026). + +### Hedging, filler, and significance-inflation + +- `ensuring` / `ensures` (4.3× — the strongest word tell), `highlights`, `supports`, `reflects`, `underscores`. +- `rather than` (2.5× — the strongest phrase tell); rewrite the comparison directly or drop the qualifier. +- `plays a crucial/vital/key role in shaping`, `serves as`, `It's worth noting that`, `It's important to note`. +- Intensifier adverbs that inflate without evidence: `significantly`, `effectively`, `increasingly`, `remarkably`. + +### Structural tells (persistent across rewrites) + +- Low burstiness — uniform 18–24-word sentences; vary length deliberately. +- The rule-of-three; `Not X, but Y`; formulaic trigrams. +- Over-qualified claims that hedge toward plausible deniability — make the claim or drop it. +- Em-dashes — keep only where genuine; do not let them become the default appender. + +### Chatbot artifacts (drop entirely in authored prose) + +`Absolutely!`, `Great question!`, `Let me break this down`, `I'd be happy to help`, `I hope this helps`, excessive bold. These index the assistant role, not content. + +### The scrub rule + +When authoring knowledge, ADRs, the glossary, the README, or skill prose, treat the lists above as a find-and-replace pass: each marker present is a prompt to rewrite for directness. This is the prose form of the docstring strip — the same RLHF instinct surfaces in both, and the answer in both is a mechanical scrub at authoring time, not a reliance on the model to self-regulate. + +## Related + +- [[software-craft/docstring-lifecycle]] — the code-side analog: the same RLHF instinct, the same strip-not-instruct answer +- [[methodology/knowledge-files]] — the authoring bar this catalog enforces on knowledge prose +- [[methodology/research-files]] — the same bar for research-card prose diff --git a/.opencode/skills/derive-source-stubs/SKILL.md b/.opencode/skills/derive-source-stubs/SKILL.md index b8cb6f16..2772cac5 100644 --- a/.opencode/skills/derive-source-stubs/SKILL.md +++ b/.opencode/skills/derive-source-stubs/SKILL.md @@ -5,10 +5,11 @@ description: "Derive the source stub files (.pyi) from the reviewed tests — ev # Derive Source Stubs -1. Load [[software-craft/source-stubs]], [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/design-patterns]] — source stub conventions, the quality principles, and the pattern catalog. +1. Load [[software-craft/source-stubs]], [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/design-patterns]], [[architecture/context-mapping]] — source stub conventions, the quality principles, the pattern catalog, and the inter-context relationship patterns. 2. Read `.cache/<session_id>/journal.md` IF present — it carries escalation findings from build. Adjust the source stubs of the contracts it names; skip if absent (first pass). 3. Read the test .py imports and bodies — every type constructed, method called, and relationship asserted in a body is the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. 4. Define types, relationships, and compositions to satisfy SOLID and Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a relationship emits a smell at the type surface (a kind-field that will switch, parallel hierarchies, construction scattered across callers, refused bequest) THEN reach for the matching pattern per [[software-craft/design-patterns]] — but KISS/YAGNI first: prefer the simplest structure that removes the smell, and prefer Python idioms (a Protocol, a dataclass, a first-class callable, a generator, a decorator) over GoF ceremony. Do not apply a pattern speculatively; Speculative Generality is the smell that rejects it. -5. Do not prescribe layout — no hardcoded module structure. External connector and adapter stubs are not a separate category; they live under the package alongside everything else. -6. Handle config per [[software-craft/secrets-and-config]]: non-secret config in the workspace `.env`; secrets in `~/.secrets/<project>.env` (out-of-workspace), loaded with `dotenv_values()` into a frozen typed Settings, never into `os.environ`. A Settings model is optional and, if warranted, is a normal source stub. -7. IF a value's representation is ambiguous (e.g. a database URL passed as bare string) THEN pin one canonical form once (the `sqlite:///path` URL form) and state it in the stub so every consumer agrees per [[software-craft/source-stubs]]. +5. IF a relationship bridges two bounded contexts (an external service, an upstream module, a shared data shape) THEN pick the inter-context pattern per [[architecture/context-mapping]] — default to an Anti-Corruption Layer (an adapter that translates the foreign model into ours) for any external dependency; reach for Shared Kernel only for a small value-object set both contexts truly co-own. +6. Do not prescribe layout — no hardcoded module structure. External connector and adapter stubs are not a separate category; they live under the package alongside everything else. +7. Handle config per [[software-craft/secrets-and-config]]: non-secret config in the workspace `.env`; secrets in `~/.secrets/<project>.env` (out-of-workspace), loaded with `dotenv_values()` into a frozen typed Settings, never into `os.environ`. A Settings model is optional and, if warranted, is a normal source stub. +8. IF a value's representation is ambiguous (e.g. a database URL passed as bare string) THEN pin one canonical form once (the `sqlite:///path` URL form) and state it in the stub so every consumer agrees per [[software-craft/source-stubs]]. diff --git a/.opencode/skills/design-interaction/SKILL.md b/.opencode/skills/design-interaction/SKILL.md new file mode 100644 index 00000000..d86f29f1 --- /dev/null +++ b/.opencode/skills/design-interaction/SKILL.md @@ -0,0 +1,14 @@ +--- +name: design-interaction +description: "Design the interaction + feedback + error flows for a user-facing surface (CLI, API, or web). On-demand — run when the ux-engineer is consulted on an interaction contract." +--- + +# Design Interaction + +1. Load [[design/interaction-design]], [[design/accessibility]] — the conversation model, the two gulfs, feedback + error design, and the accessibility floors that apply to every interaction. +2. Identify the surface (CLI / HTTP API / web UI) and load its surface-specific knowledge: [[design/cli-design]] for a terminal, [[design/api-design]] for an HTTP service, [[design/visual-design]] for a graphical surface. +3. State the user's goal for the surface in one sentence, then list the flows that reach it — including the recovery path from each error. A flow is a contract, not a happy path; the error paths are designed here, not deferred. +4. Design the feedback for every action: received, in progress, succeeded, failed — within a latency the user can associate with the action. Close the gulfs of execution (signified affordances, the user's vocabulary, one primary action) and evaluation (legible state, results in the user's terms). +5. Design the errors along prevent → detect → recover: constrain input to prevent; validate early to detect; write an actionable, in-the-user's-terms message with a fix path to recover. Never ship a flow whose error paths have not been designed. +6. Verify the accessibility floor: keyboard reachability + visible focus (graphical), contrast per WCAG 2.2, color never the sole signal, semantic markup. IF a flow fails the floor THEN fix the design before handoff. +7. Document the interaction contract: the flows, the feedback at each step, and the error catalog. Hand to the implementer; the contract, not a Figma file, is the source. diff --git a/.opencode/skills/design-visual-asset/SKILL.md b/.opencode/skills/design-visual-asset/SKILL.md new file mode 100644 index 00000000..8f9cabf3 --- /dev/null +++ b/.opencode/skills/design-visual-asset/SKILL.md @@ -0,0 +1,14 @@ +--- +name: design-visual-asset +description: "Produce a project visual asset — social card, README banner, logo/avatar, or favicon — as self-contained, accessible SVG. On-demand." +--- + +# Design Visual Asset + +1. Load [[design/asset-design]], [[design/visual-design]], [[design/accessibility]] — the per-use-case asset inventory, the visual-design levers (hierarchy, contrast, typography), and the accessibility floors every asset must meet. +2. Identify the asset + where it lives — social card (1280×640, open-graph previews), README banner (wide, dark-mode-aware), logo/avatar (square, reads at 32–64 px), favicon (square, reads at 16 px). Compose for that context, not for a generic brand system. +3. Establish hierarchy with the four levers — size, weight, position, spacing — so the user reads the name first, the intent second, the mark third. Apply parsimony: one mark, generous whitespace, one accent; the dev-branding norm is restraint. +4. Author the asset as self-contained SVG: presentation attributes (no inline `<style>` hosts strip), no external `<use href>` or web fonts, a square `viewBox` with padding, strokes converted to filled paths for production, metadata stripped. +5. Make it accessible: give the SVG an accessible name (`<title>` + `aria-labelledby`, or `role="img"` + `aria-label`); meet WCAG 2.2 contrast floors against every background it will appear on; pair color with a shape or label so it survives color-blind + dark-mode. +6. Provide a dark-surface variant where the asset appears on a theme-aware surface (README, GitHub), OR design a monochrome mark on a transparent background that holds on both. +7. Verify legibility at the shown size for the avatar (32–64 px) and favicon (16 px) only — simplify the mark if a thin stroke vanishes. Export PNG / `.ico` only where a target demands it; the SVG is the source. diff --git a/.opencode/skills/instantiate-project/SKILL.md b/.opencode/skills/instantiate-project/SKILL.md new file mode 100644 index 00000000..5c49300c --- /dev/null +++ b/.opencode/skills/instantiate-project/SKILL.md @@ -0,0 +1,14 @@ +--- +name: instantiate-project +description: "Create a new project instance from the temple8 template via copier, verify it, and initialise the first flowr session." +--- + +# Instantiate Project + +1. Confirm the destination directory does not exist or is empty; IF `copier copy` would clobber existing work THEN stop and ask the user where to create the project. +2. Run `copier copy gh:nullhack/temple8 <destination>` (or the local template path if offline). Answer the questionnaire: `project_name`, `package_name` (defaults from `project_name`), `description`, `repo_url`, `version`, `author_name`, `author_email`, `keep_design`, `keep_research`, `reset_git`. +3. `cd` into the new project and verify the skeleton: `<package>/__init__.py` exists; `tests/{integration,e2e,cassettes,fixtures}/` exist; `pyproject.toml` and `README.md` are rendered (no `{{ }}` placeholders remain); `.opencode/`, `.flowr/`, `.templates/`, `AGENTS.md`, `conftest.py`, `.github/` are present and unchanged. +4. Run `uv sync --extra dev` to materialise the venv. +5. Verify the gates load: `bash -c 'for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done'` — all six must report `{valid: true}`; `uv run ruff check .` must pass; `uv run pytest --collect-only -q` must collect zero tests cleanly. +6. Initialise the first session: `uv run python -m flowr session init pipeline-flow --name default`; confirm it lands at `discovery-flow/interview-general`. +7. Report the instance ready: destination path, the rendered identity, and the first flowr command (`uv run python -m flowr check --session default`) to begin driving. diff --git a/.opencode/skills/interview-building-blocks/SKILL.md b/.opencode/skills/interview-building-blocks/SKILL.md index c6aae997..b9db29d0 100644 --- a/.opencode/skills/interview-building-blocks/SKILL.md +++ b/.opencode/skills/interview-building-blocks/SKILL.md @@ -5,7 +5,7 @@ description: "Funnel level 3 — identify building-block names and rough boundar # Interview (Building Blocks) -1. Load [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]] — gap analysis and boundary sizing. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). +1. Load [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]], [[architecture/quality-attributes]] — gap analysis, boundary sizing, and the quality-attribute taxonomy the coverage check runs over. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). 2. Read the running interview-notes; append the building-block names and boundaries to it. 3. Capture building-block NAMES and rough boundaries ONLY — no detailed spec (rules, examples, criteria come later in planning). The purpose is to know WHAT building blocks exist, not to specify each. 4. Run gap analysis: IF a bounded context from cross-cutting maps to no block THEN flag the gap; IF a quality attribute maps to no block THEN flag the gap. Do not silently fill gaps per [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]]. diff --git a/.opencode/skills/interview-cross-cutting/SKILL.md b/.opencode/skills/interview-cross-cutting/SKILL.md index 1b08764c..645f7f95 100644 --- a/.opencode/skills/interview-cross-cutting/SKILL.md +++ b/.opencode/skills/interview-cross-cutting/SKILL.md @@ -5,7 +5,7 @@ description: "Funnel level 2 — structure the domain into behaviour groups, bou # Interview (Cross-cutting) -1. Load [[requirements/interview-techniques]] — CIT, Laddering, CI Perspective Change, and the Active Listening protocol. +1. Load [[requirements/interview-techniques]], [[architecture/quality-attributes]] — CIT, Laddering, CI Perspective Change, and the Active Listening protocol; and the quality-attribute taxonomy to elicit. 2. Read the running interview-notes; append the cross-cutting findings to it. -3. Structure the domain into behaviour groups, bounded contexts, integration points, and lifecycle events. Probe each with CIT and Laddering; IF recall stalls THEN re-frame via CI Perspective Change. +3. Structure the domain into behaviour groups, bounded contexts, integration points, and lifecycle events. Probe each with CIT and Laddering; IF recall stalls THEN re-frame via CI Perspective Change. Capture the quality attributes stakeholders care about as one-line scenarios (stimulus → response), not bare words, per [[architecture/quality-attributes]]. 4. Apply Active Listening L2: give a brief synthesis when transitioning between behaviour groups — confirms completeness, offers a recovery point. diff --git a/.opencode/skills/merge-to-dev/SKILL.md b/.opencode/skills/merge-to-dev/SKILL.md index 4b4036f4..aaa98919 100644 --- a/.opencode/skills/merge-to-dev/SKILL.md +++ b/.opencode/skills/merge-to-dev/SKILL.md @@ -1,11 +1,14 @@ --- name: merge-to-dev -description: "Squash-merge the feature commits into dev and verify the whole suite plus whole-suite stubtest are clean." +description: "Squash-merge the feature commits into dev, regenerate docstrings, and verify the whole suite plus whole-suite stubtest are clean." --- # Merge To Dev -1. Load [[software-craft/git-conventions]] — squash-merge form. +1. Load [[software-craft/git-conventions]], [[software-craft/docstring-lifecycle]] — squash-merge form and the docstring lifecycle. 2. Switch to dev and squash-merge the feature commits per [[software-craft/git-conventions]]; the green-suite and whole-suite stubtest gate is verified on dev after the merge. 3. Verify the full suite is green on dev after the merge: no pending markers remain (every source .pyi has its sibling .py, so every test runs) and every test passes. 4. Verify whole-suite stubtest is clean across both source and tests: every source .pyi and every test .pyi agrees with its sibling .py — no drift smuggled in by the batch. +5. Regenerate docstrings for the public surface of every contract shipped this cycle (modules, classes, public functions and methods) — faithful prose from the stable code, never a mechanical restatement of the signature; the *why* of an architectural decision lives in an ADR, not a docstring. Per [[software-craft/docstring-lifecycle]]. +6. Run `task lint-merge` — adds `SIM` and `RUF` to the dev select and runs `ruff format .` — so restructure and format land on dev exactly once per merge, never during build. +7. Commit the regenerated docstrings and the format pass on dev as `docs(<scope>): regenerate docstrings + format`. diff --git a/.opencode/skills/record-decision/SKILL.md b/.opencode/skills/record-decision/SKILL.md index bd77935a..f4572195 100644 --- a/.opencode/skills/record-decision/SKILL.md +++ b/.opencode/skills/record-decision/SKILL.md @@ -7,7 +7,7 @@ description: "Author (or amend) an Architecture Decision Record for a load-beari 1. Confirm the decision is ADR-worthy before authoring: it has genuine trade-offs between multiple viable alternatives **and** cross-cutting impact (reversing it would ripple across contracts). IF it has one obvious choice or only local impact THEN it is BAU — do not record it; stop here. 2. Copy `.templates/docs/decisions/YYYY-MM-DD-<kebab-title>.md.template` to `docs/decisions/<today>-<slug>.md`, replacing the date placeholder with today's ISO date and the slug with a short kebab title for the decision. -3. Fill the sections from the decision itself, not from memory of the alternatives: `Context` (the forces — link the interview, glossary, existing ADRs, cassettes, and the contract set; do not restate them), `Decision` (one imperative sentence), `Alternatives considered` (each alternative + why it was rejected), `Consequences` (+ / − / neutral, with mitigations for the negatives). +3. Fill the sections from the decision itself, not from memory of the alternatives: `Context` (the forces — link the interview, glossary, existing ADRs, cassettes, and the contract set; do not restate them), `Decision` (one imperative sentence), `Alternatives considered` (each alternative + why it was rejected), `Consequences` (+ / − / neutral, with mitigations for the negatives). Apply the prose bar per [[writing/ai-language-markers]] — scrub AI markers (`delve`, `tapestry`, `plays a crucial role`, `rather than`); the ADR's authority comes from the decision's forces, not formal-sounding prose. 4. In `Traceability`, link the artefacts the decision touches — tests, source `.pyi`, migrations, cassettes, glossary terms, related ADRs — by path. Points only; never restate the artefact's content (tests are the source of truth). 5. Seed the `Change log` with one row: `<today> | Created | <one-line reason>`. 6. IF the decision supersedes an existing ADR THEN edit that ADR in place — amend its `Status`, `Decision`, `Alternatives considered`, and `Consequences` to the current decision — and append a `Change log` row (`<today> | Amended | <what changed and why>`). Do not create a new file; the body always reflects the current decision and the log carries the history. diff --git a/.opencode/skills/select-build-target/SKILL.md b/.opencode/skills/select-build-target/SKILL.md index 1b3d774d..2e963001 100644 --- a/.opencode/skills/select-build-target/SKILL.md +++ b/.opencode/skills/select-build-target/SKILL.md @@ -5,9 +5,10 @@ description: "Pull the next source contract to build from the pending backlog, r # Select Build Target -1. Load [[software-craft/tdd]] — the red/green/refactor cycle and pending-mark semantics. +1. Load [[software-craft/tdd]], [[software-craft/docstring-lifecycle]] — the cycle and the naked-source rule. 2. Discover the backlog: collect tests carrying the pending marker (`uv run pytest --collect-only -m pending -q`). Map each pending test to the source module it exercises. 3. Pick the lowest-layer contract that still has pending tests — layer order is dependency order, so a module is built only after the modules it imports are built. 4. IF a shared or foundation module (shared data types with no dedicated external-boundary test of its own) is needed THEN pull it in and build it alongside the first contract that depends on it; record both. 5. Treat the pending marker — not the presence of the source .py — as what makes a contract selectable: a reworked contract re-enters the queue even when its .py already exists. IF no pending tests remain anywhere THEN the system is built. -6. Skim the target's .pyi and its tests for context, not the whole project. +6. Strip the target source .py at cycle entry: IF the target module's .py already exists (rework) THEN run `uv run python scripts/strip_docstrings.py <package>/<module>.py` to remove the docstrings carried over from the last merge — source .py stays naked across red/green/refactor/review/ship per [[software-craft/docstring-lifecycle]]. Skip if the .py is absent (new contract). +7. Skim the target's .pyi and its tests for context, not the whole project. diff --git a/.opencode/skills/simulate-contracts/SKILL.md b/.opencode/skills/simulate-contracts/SKILL.md index 1cc53680..cf1ca89a 100644 --- a/.opencode/skills/simulate-contracts/SKILL.md +++ b/.opencode/skills/simulate-contracts/SKILL.md @@ -12,5 +12,5 @@ description: "Answer whether a correct implementation passing every test would y 5. Check traceability: every consolidated interview finding maps to at least one test or an explicit deferral, and every external service has a captured cassette its tests replay. 6. Check layer order: external-boundary stubs complete before adapter stubs, and so on. 7. Run stubtest on the tests to confirm zero drift between every test .pyi and its sibling .py per [[software-craft/test-stubs]]. Source stubtest waits for build — no source .py exists yet. -8. Run ruff on the whole project (`ruff check .` and `ruff format . --check`); the gate is zero violations. Plan-authored tests and source stubs must be lint-clean before build — a lint defect caught here is a defect build never has to edit around. +8. Run the dev ruff check (`ruff check .`) on the whole project; the gate is zero violations. Restructure lint (`SIM`, `RUF`) and `ruff format` are merge-time per [[software-craft/docstring-lifecycle]] — a readability restructure is not a plan defect. Plan-authored tests and stubs must pass the bug-catcher set before build. 9. IF a test references an external exchange no captured cassette covers THEN append the finding to `.cache/<session_id>/journal.md` (service, the missing case) and fire `needs-capture`. This routes back to explore to record the missing reality, not forward to build. diff --git a/.opencode/skills/write-test-py/SKILL.md b/.opencode/skills/write-test-py/SKILL.md index be629d6b..f17a6ea0 100644 --- a/.opencode/skills/write-test-py/SKILL.md +++ b/.opencode/skills/write-test-py/SKILL.md @@ -12,5 +12,5 @@ description: "Transform the reviewed test stubs into executable test bodies, wit 5. Mark each test with the pending marker; the conftest hook skips pending tests so the suite stays green-with-skips until source is built. 6. Defer the system-under-test import into each test body so an unbuilt module collects cleanly and its pending tests skip rather than error at collection. Keep third-party and test-only imports at module top. 7. Keep the .py's module-level names and method signatures in exact agreement with its .pyi — stubtest checks the pair strictly. -8. Run ruff on the authored test files (`ruff check` and `ruff format`); fix every violation so build receives lint-clean tests. +8. Run the dev ruff check (`ruff check .`) on the authored test files; fix every violation so build receives bug-clean tests. Restructure lint (`SIM`, `RUF`) and `ruff format` are merge-time per [[software-craft/docstring-lifecycle]] — do not format here. 9. IF reworking an existing contract THEN edit the body to match the changed .pyi and re-apply the pending marker to the affected tests so they skip until build re-selects them. diff --git a/.templates/README.md.template b/.templates/README.md.template deleted file mode 100644 index 65012985..00000000 --- a/.templates/README.md.template +++ /dev/null @@ -1,45 +0,0 @@ -# <project-name> - -> <One-line purpose: the problem this solves and for whom. Hand-authored; rarely -> changes. For the current build state see `docs/state.md` (regenerated each -> cycle). Tests are the source of truth for behaviour; this README is -> orientation.> - -## Purpose - -<2–4 sentences: the problem, who has it, and what this project does about it.> - -## Scope - -<What is in and out of this project — drawn from the interview. Bullet form is -fine.> - -## How to run - -**Entry point:** <CLI command / API server / job — how a user invokes it> - -**Environment (12-factor):** configure via environment variables, kept in a -gitignored `.env`. Required vars: - -- `<VAR_NAME>` — <what it configures> - -<The command(s) to install and run.> - -## Where things live - -| Path | Holds | -|---|---| -| `<package>/` | source — `.pyi` stubs + `.py` bodies | -| `tests/integration/`, `tests/e2e/` | integration + e2e tests (no unit) | -| `tests/cassettes/` | recorded external contracts (vcrpy) — the wire truth | -| `tests/fixtures/` | test fixtures | -| `migrations/` | Alembic migrations — the schema spec | -| `docs/glossary.md` | ubiquitous language — the names | -| `docs/state.md` | living current-state specification (regenerated each cycle) | -| `docs/research/` | human-reference sources behind knowledge citations | - -## Workflow - -This project follows the staged-contract pipeline: discover → explore → plan → -build → deliver. Drive it one state at a time with flowr — see `AGENTS.md` for -the lifecycle and commands. diff --git a/.templates/docs/assets/logo.svg.template b/.templates/docs/assets/logo.svg.template new file mode 100644 index 00000000..a7c9c049 --- /dev/null +++ b/.templates/docs/assets/logo.svg.template @@ -0,0 +1,10 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="lg-title lg-desc"> + <title id="lg-title"><project-name> mark + The <project-name> mark — a single geometric form, usable as logo, avatar, and favicon. + + + + + diff --git a/.templates/docs/assets/social-card.svg.template b/.templates/docs/assets/social-card.svg.template new file mode 100644 index 00000000..9e47e63c --- /dev/null +++ b/.templates/docs/assets/social-card.svg.template @@ -0,0 +1,17 @@ + + <project-name> — social card + Open-graph preview for <project-name>: <one-line intent>. + + + + + + + + + + <project-name> + <one-line intent> + diff --git a/AGENTS.md b/AGENTS.md index ae136b55..cb28c295 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,71 +1,73 @@ # AGENTS.md -temple8 — Python project template. +A Python project with the staged-contract workflow wired in (flow set, +agents/skills/knowledge, CI, tooling). Drive the pipeline one state at a time +through flowr. + +## Operating discipline + +1. **flowr is the single router.** Every state change runs through flowr — no improvised routing, no skipping states. +2. **The owner does the work.** Each state names one owner in `dispatch_to`; the orchestrator dispatches it, and the owner produces the artifacts and asserts the evidence. The orchestrator never authors the work. +3. **The state's contract is binding.** Read every `input artifact` before starting — missing means stop, not assume. Write only to `output artifacts`. +4. **Assert only verified evidence; CI is the backstop.** A gate fires on the owner's asserted evidence; assert nothing you did not check — CI catches the lie (`ruff` / `pyright` / `mypy.stubtest` / `pytest`). +5. **Branch discipline.** Match the state's `git branch`; merge `feature` → `dev` only under the whole-suite gates. No dangling branches. +6. **Every requirement traced.** Each interview finding maps to a test or an explicit deferral; an untraced requirement is a gap the simulate gate rejects. + +## Driving a state + +One state at a time. The orchestrator keeps **one todo per state, regenerated at +state entry** — the todo *is* this five-phase loop. "No todo = no work": work +outside the loop is untracked. One state per todo; regenerate on every +transition. + +1. **Read** — `flowr check --session `; parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. +2. **Verify inputs** — every `input artifact` exists on disk. Missing = stop (discipline 3). +3. **Dispatch** — call the `dispatch_to` owner with the `skills` paths (`.opencode/skills//SKILL.md`) and the input artifacts. The owner writes only to `output artifacts` and returns asserted evidence. +4. **Verify outputs + evidence** — the `output artifacts` were produced and the transition's `conditions` evidence is real (discipline 4). +5. **Transition** — `flowr transition --session --evidence k=v …`, then regenerate the todo from the next state's `check`. + +Routing is one flow with five subflows: `pipeline-flow` → discovery → explore → +plan → build → deliver → shipped. Escalations re-enter the target subflow at its +first state (no position memory): build → plan on a contract gap; plan/explore → +discover on insufficient elicitation. Gate evidence keys + the full +session/subflow mechanics: [[workflow/flowr-operations]]. -This branch (`refactor/clean-slate`) is a clean-slate rebuild. The previous -spec-driven orchestration layer — `flowr`, `beehave`, the agent/skill/knowledge -tree, `.flowr/`, `.templates/`, `docs/` — was removed from the working tree and -preserved locally in `.backup/` (gitignored), fully recoverable from -`origin/main`. The rebuild re-introduces pieces selectively and authored fresh: -the flow set and the `.opencode/` methodology layer (agents, skills, knowledge) -are rebuilt against the new staged-contract workflow; the `beehave`/BDD layer is -dropped; `.templates/` and `docs/` are forward-planned. +| Command | Purpose | +|---------|---------| +| `uv run python -m flowr session init pipeline-flow --name ` | Start | +| `uv run python -m flowr check --session ` | State attrs + transitions | +| `uv run python -m flowr check --session ` | A transition's conditions | +| `uv run python -m flowr next --session ` | Open / blocked transitions | +| `uv run python -m flowr transition --session --evidence k=v` | Advance | + +## Parsimony + +Fewest, quietest commands — suppress verbose flags, scope to the target (read +the `.pyi` before the `.py`). No narration: command + output is the +conversation, not a running commentary. Cite precisely (`file:line`), never +vague. Do not repeat yourself — each fact stated once, in its canonical home +(the flow, the knowledge, the test, the ADR), and cited elsewhere. Scrub AI +markers (`delve`, `tapestry`, `rather than`, `plays a crucial role`) from +authored prose per [[writing/ai-language-markers]]. Maximise signal; minimise +tokens. ## Workflow -Tests are the source of truth. Discovery elicits requirements via the interview -funnel; explore empirically grounds every external service (read docs, run -authenticated probes, record real request/response shapes as vcrpy cassettes — -the authoritative external contract); plan authors the tests up front — -integration and E2E only — as a staged contract surface: test `.pyi` (signatures -expressing the domain), then the test `.py` bodies (no docstrings, no comments; -the body is the spec; each test marked `@pytest.mark.pending`), then the source -`.pyi` derived from what the tests reference. Build implements each source `.py` -from its `.pyi` to make the already-written tests pass (red removes the target's -pending mark); tests are otherwise not edited during build. The -`@pytest.mark.pending` mark is the backlog signal (covers new work and rework); -the built/pending ratio (source contracts with vs without a pending test) is the -progress record; an empty backlog is "done". Stubs (`.pyi`) are the cheap -signature view: read the target's `.pyi` first and open a `.py` only for the -detail its stub omits. `mypy.stubtest` is the drift detector for BOTH source -and test `.pyi` (gated at simulate for tests, green/review/merge for source). -flowr's gate `conditions` collect EVIDENCE the dispatched agent asserts -(`stubtest-clean=true`, etc.); flowr does not run the checks itself. CI is the -enforcement backstop: it runs `ruff` (with `PYI`), `pyright`, `mypy.stubtest`, -and `pytest` on every push and fails the build on any drift or violation, -verifying what the agent asserted. When prose and a test disagree, the test wins. - -We write integration tests (config, external adapters, APIs, databases) and -E2E tests (CLI, object composition, contract chaining) only; no unit tests. -Code (source, tests, stubs) carries no docstrings during development — -`D`/pydocstyle is dropped and docstrings are never authored (token economy). -Tests depend on contracts, never internals. They are held to production-grade -standards (SOLID, YAGNI, Object Calisthenics, DRY, KISS, no smells). - -Concerns tests exercise but cannot store live in exactly one authoritative -artifact, never duplicated in prose: DB relationships and data shape live in -ORM models + Alembic migrations (the migration IS the schema spec); config -parameter definitions live in a typed Settings model; external-adapter -contracts live in recorded fixtures/cassettes (captured during explore). A lean -glossary of ubiquitous language drives naming. - -Routing is one flow with five subflows: `pipeline-flow` orchestrates -`discovery-flow` + `explore-flow` + `plan-flow` + `tdd-flow` + `deliver-flow`. Drive it one state at a time: - -| Command | Purpose | -|---------|---------| -| `uv run python -m flowr session init pipeline-flow --name default` | Start | -| `uv run python -m flowr check --session default` | Current state attrs + transitions | -| `uv run python -m flowr next --session default` | Open/blocked transitions | -| `uv run python -m flowr transition --session default` | Advance | - -Lifecycle: `discover` (interview funnel → glossary) → `explore` (ground -external services → vcrpy cassettes) → `plan` (author test `.pyi` → review test -`.pyi` → write test `.py` (marked `@pytest.mark.pending`) → derive source `.pyi` -→ simulate) → `build` (per source stub: red → green → refactor → review → ship) -→ `deliver` (merge to dev → publish) → `shipped`. Build escalates back to -`plan` on a contract gap; `plan` and `explore` escalate to `discover` when the -interview itself is insufficient. See `TODO.md` for what's owed. +Tests are the source of truth. The pipeline authors a staged contract surface, +then builds it: **discover** elicits requirements (interview funnel → glossary); +**explore** grounds external reality (vcrpy cassettes — the authoritative +external contract); **plan** writes tests up front (`*_test.pyi` → `*_test.py` +`@pytest.mark.pending` → source `.pyi` → simulate); **build** implements each +source `.py` from its fixed `.pyi` one contract per cycle (red → green → +refactor → review → ship); **deliver** squash-merges to dev and publishes. +`@pytest.mark.pending` is the backlog signal (new work + rework); an empty +backlog is done. flowr's gates collect EVIDENCE the agent asserts; CI is the +enforcement backstop (ruff / pyright / `mypy.stubtest` / pytest). When prose and +a test disagree, the test wins. + +Authoring detail (staged contracts, evidence vs enforcement, the docstring/lint +lifecycle, separation-of-concerns, secrets/config) lives in the knowledge layer +— discover it, do not restate it here. ## Project layout @@ -75,8 +77,7 @@ Committed (the source of truth): |------|-------| | `/` | source — `.pyi` stubs + `.py` bodies | | `tests/integration/`, `tests/e2e/` | integration + E2E tests only (no unit) | -| `tests/cassettes/` | recorded vcrpy cassettes — the external contract | -| `tests/fixtures/` | test fixtures | +| `tests/cassettes/`, `tests/fixtures/` | recorded vcrpy cassettes; fixtures | | `migrations/` | Alembic migrations — the schema spec | | `docs/glossary.md` | ubiquitous language | | `.flowr/flows/` | flow definitions | @@ -87,22 +88,20 @@ Gitignored (local working state, regenerated on demand): | Path | Holds | |------|-------| | `.cache//` | interview notes, external contracts, probe research, build target | -| `.cache/explore/` | throwaway probe scripts (run once to record cassettes; never imported) | +| `.cache/explore/` | throwaway probe scripts (run once; never imported) | | `.cache/sessions/` | flowr session state | -| `.backup/` | previous system (recoverable from `origin/main`) | | `.env` | non-secret local config (12-factor) | -| `~/.secrets/.env` | secrets (out-of-workspace; `dotenv_values()` into a frozen Settings, gated by opencode `external_directory`) | +| `~/.secrets/.env` | secrets (out-of-workspace; `dotenv_values()` into a frozen Settings; opencode `external_directory`-gated) | ## Agents, skills & knowledge -The methodology layer lives under `.opencode/` (not loaded every session — -discovered on demand): +Under `.opencode/` (loaded on demand, not every session): -| Path | Holds | Loaded | -|------|-------|--------| -| `.opencode/agents/{role}.md` | Role identity (who I am, what I decide) | When the role is dispatched | -| `.opencode/skills/{skill}/SKILL.md` | Procedure (how to do the work) | When a state's `skills` names it | -| `.opencode/knowledge/{domain}/{concept}.md` | Reference & explanation (what and why) | On demand, via wikilinks | +| Path | Holds | +|------|-------| +| `.opencode/agents/{role}.md` | role identity (who I am, what I decide) | +| `.opencode/skills/{skill}/SKILL.md` | per-state procedure (how to do the work) | +| `.opencode/knowledge/{domain}/{concept}.md` | reference & explanation (what and why) — domains: `methodology/`, `requirements/`, `software-craft/`, `workflow/`, `architecture/`, `writing/`, `design/` | Discover rather than enumerate: @@ -110,23 +109,21 @@ Discover rather than enumerate: ls .opencode/skills/ find .opencode/knowledge -name '*.md' -The flow binds each state to its owner (`dispatch_to`), its procedure -(`skills`), and its artifacts (`input artifacts` / `output artifacts`); the -agent, skill, and knowledge files stay single-concern and free of routing. -Wikilinks cite knowledge on demand: `[[domain/concept]]` resolves to -`.opencode/knowledge/{domain}/{concept}.md`, and a `#section` fragment selects -how deep to load (`#key-takeaways`, `#concepts`, or the whole file). Authoring -conventions live in the `methodology/` knowledge domain. +The flow binds each state to its owner (`dispatch_to`), procedure (`skills`), +and artifacts (`input artifacts` / `output artifacts`); agents, skills, and +knowledge stay single-concern and free of routing. Wikilinks cite knowledge on +demand: `[[domain/concept]]` resolves to `.opencode/knowledge/{domain}/{concept}.md`, +and a `#section` fragment selects depth. Authoring conventions live in the +`methodology/` domain. ## Project commands -Tasks are defined in `pyproject.toml` under `[tool.taskipy.tasks]`. The `app/` -package is the placeholder, so package-dependent commands (`task run`, -`task test`, `task stubtest`, ...) resolve only once the package is created. +Tasks are defined in `pyproject.toml` under `[tool.taskipy.tasks]`. Package-dependent commands (`task run`, `task test`, `task stubtest`, …) target the package named in `[tool.setuptools] packages`. | Command | Purpose | |---------|---------| | `task test` | Run tests | | `task test-fast` | Fast tests only | -| `task lint` | ruff check + format check | -| `ruff format .` | Auto-format | +| `task lint` | ruff check (dev: bug-catchers only) | +| `task lint-merge` | merge: + SIM/RUF + ruff format | +| `task strip-docstrings` | strip docstrings from a source .py (tdd select) | diff --git a/README.md b/README.md index 687d0e0f..a033322c 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,78 @@ # temple8 -> A Python project **methodology template** — a ready-to-clone foundation that -> wires the staged-contract development workflow into a new project, with the -> flow set, the agents/skills/knowledge methodology layer, CI, and tooling -> pre-configured. temple8 itself is not an application; an instance built from -> it holds the package, tests, and instance docs. - -## Purpose - -temple8 exists to make one workflow reproducible across Python projects: tests -are authored up front as a staged contract surface (test `.pyi` → test `.py` -marked pending → source `.pyi` → simulate), then built out one contract per -cycle under flowr orchestration, with the methodology layer (agents, skills, -knowledge), the drift gates (pyright, `mypy.stubtest`, ruff, pytest), and CI -already in place. Cloning the template removes the bootstrap cost of -re-establishing that workflow each project. +> A Python project **methodology template** — a copier template that wires the +> staged-contract development workflow into a new project, with the flow set, the +> agents/skills/knowledge methodology layer, CI, and tooling pre-configured. +> temple8 itself is not an application; an instance built from it holds the +> package, tests, and instance docs. -## Scope - -**In** — the methodology only: flow definitions, the agent/skill/knowledge -layer, document templates, CI, the conftest pending-marker hook, and the -pyproject tooling. +## What it is -**Out** — everything an instance owns: an application package, tests, -migrations, cassettes, `docs/glossary.md`, `docs/state.md`. These live in a -project instantiated from this template, not in temple8 itself. The `app` -references in `pyproject.toml` (`[tool.setuptools] packages`, task targets) are -placeholders for whatever package name the instance chooses. +temple8 makes one workflow reproducible across Python projects: tests are +authored up front as a staged contract surface (test `.pyi` → test `.py` marked +pending → source `.pyi` → simulate), then built out one contract per cycle under +flowr orchestration, with the methodology layer (agents, skills, knowledge), the +drift gates (pyright, `mypy.stubtest`, ruff, pytest), and CI already in place. +Instantiating the template removes the bootstrap cost of re-establishing that +workflow each project. -## How to run +## Instantiate a project -temple8 is not run as an application — it is used as a template for one. +temple8 is a [copier](https://copier.readthedocs.io/) template. To start a new +project from it: -1. Clone or copy this tree into a new project directory. -2. Create the package (replacing the `app` placeholder) and the test layout - (`tests/integration/`, `tests/e2e/`, `tests/cassettes/`, `tests/fixtures/`); - there is no `tests/unit/` by policy. -3. Drive the staged-contract pipeline one state at a time with flowr: +``` +uv tool install copier +copier copy gh:nullhack/temple8 my-project +``` - ``` - uv run python -m flowr session init pipeline-flow --name default - uv run python -m flowr check --session default - uv run python -m flowr next --session default - uv run python -m flowr transition --session default - ``` +Answer the questionnaire (project and package name, description, author, +version, repo URL, optional git reset, and which optional layers to keep). +Copier renders `pyproject.toml` + the README, creates the package and the test +skeleton, and hands you a fresh repo ready for the first `flowr session init`. -A reference usage — a weather-lookup CLI driven through the full pipeline — -lives outside the template tree; see the clean-slate rebuild notes. +The `project-instantiator` agent and its `instantiate-project` skill (in +`.opencode/`) guide the same flow end to end — gather the parameters, run the +copy, verify, and start the first pipeline session. They live in the template +and are excluded from instances. -## Secrets +## Scope -Secrets (API keys, tokens, passwords) never live in the repo. The split: +**In** — the methodology only: flow definitions, the agent/skill/knowledge +layer, document templates, CI, the conftest pending-marker hook, the copier +template, and the pyproject tooling. -- **Non-secret config** — base URLs, regions, feature flags — in the workspace - `.env` (gitignored), loaded with `load_dotenv()` into `os.environ`. -- **Secrets** — in `~/.secrets/.env`, *outside* the repo tree, loaded - with `dotenv_values()` straight into a frozen typed `Settings` and **never** - into `os.environ` (so `env`, `printenv`, and `/proc` cannot see them). -- **`.env.example`** is committed: every variable name, non-secret defaults - filled, secret lines empty with a pointer to `~/.secrets/`. +**Out** — everything an instance owns: an application package, tests, +migrations, cassettes, `docs/glossary.md`, `docs/state.md`. These live in a +project instantiated from this template, not in temple8 itself. -Instance authors add one opencode permission rule so a direct read of the -secrets path prompts the user instead of passing silently: +## What an instance gets -```json -{ "permission": { "external_directory": { "~/.secrets/**": "ask", "*": "allow" } } } -``` +- `pyproject.toml` rendered with the project's name, package, and tooling. +- a fresh `README.md` from the instance template. +- `/__init__.py` and the `tests/{integration,e2e,cassettes,fixtures}/` skeleton. +- `.env.example` (the committed env contract). +- the whole methodology layer (`.opencode/`, `.flowr/`, `.templates/`) verbatim. +- a fresh git history (optional, default on). -Agents in this workflow never create or debug a secret: they instruct the user -how to obtain and place each credential, and on an auth failure they ask with -suggestions instead of investigating the value. The full threat model and -layered defense are in the `secrets-and-config` knowledge. +Optional layers an instance may keep or drop at instantiation: the `design/` +knowledge + asset templates (for projects with a UI surface) and `docs/research/` +(the source-card reference library behind the knowledge citations). ## Where things live | Path | Holds | |---|---| -| `.flowr/flows/` | the six flow definitions — `pipeline-flow` plus the five subflows | -| `.opencode/agents/` | role identities (who owns what decision) | -| `.opencode/skills/` | per-state procedures (one per state) | -| `.opencode/knowledge/` | reference and explanation — `methodology/`, `requirements/`, `software-craft/` | -| `.templates/` | document templates — glossary, state (living spec), README, research card | +| `copier.yml` | the instantiation questionnaire + tasks | +| `pyproject.toml.jinja`, `README.md.jinja` | the rendered instance files | +| `.flowr/flows/` | the six flow definitions | +| `.opencode/` | agents, skills, knowledge (methodology, requirements, software-craft, workflow, architecture, writing, design) | +| `.templates/` | document templates — glossary, state, research card, ADR, `.env.example`, social-card, logo | | `.github/workflows/` | CI — ruff + flowr validate always on; pyright/stubtest/pytest guarded on package+tests | -| `conftest.py` | the `@pytest.mark.pending` skip hook (the backlog signal) | -| `pyproject.toml` | tooling — ruff (bug-catcher select, no docstrings), pytest markers, taskipy, stubtest | | `docs/research/` | human-reference sources behind the knowledge citations | -| `AGENTS.md` | the methodology brief, routing, and flowr commands | -| `TODO.md` | what is owed and forward-planned | ## Workflow -The staged-contract pipeline runs discover → explore → plan → build → deliver -→ shipped, driven one state at a time through flowr: - -- **discover** — interview funnel elicits requirements and authors the glossary; -- **explore** — every external service is grounded by recording real exchanges - as vcrpy cassettes (the authoritative external contract); -- **plan** — tests are authored up front (`.pyi` → `.py` marked pending → source - `.pyi` derived) and simulated before any source is built; -- **build** — each source contract is implemented one cycle at a time - (red → green → refactor → review → ship) from its fixed `.pyi`; -- **deliver** — feature commits squash-merge into dev under the whole-suite - gates, then publish. - -Tests are the source of truth for behaviour. See `AGENTS.md` for the full -lifecycle, the gate evidence keys, and the flowr commands. +The staged-contract pipeline runs discover → explore → plan → build → deliver → +shipped, driven one state at a time through flowr. See `AGENTS.md` for the full +operating discipline, the driving loop, and the flowr commands. diff --git a/README.md.jinja b/README.md.jinja new file mode 100644 index 00000000..e52cdc5d --- /dev/null +++ b/README.md.jinja @@ -0,0 +1,50 @@ +# {{ project_name }} + +> {{ description }} + +A Python project on the staged-contract workflow: tests are authored up front as +a contract surface and built out one cycle at a time under flowr orchestration, +with the methodology layer (agents, skills, knowledge), the drift gates +(pyright, `mypy.stubtest`, ruff, pytest), and CI already in place. + +## How to run + +``` +uv run python -m flowr session init pipeline-flow --name default +uv run python -m flowr check --session default +uv run python -m flowr next --session default +uv run python -m flowr transition --session default +``` + +## Secrets + +Secrets never live in the repo. Non-secret config goes in the workspace `.env` +(gitignored, `load_dotenv()`); secrets go in `~/.secrets/{{ project_name }}.env` +(out-of-workspace), loaded with `dotenv_values()` into a frozen typed `Settings` +— never into `os.environ`. `.env.example` is the committed env contract. Add one +opencode permission rule so a direct read of the secrets path prompts: + +```json +{ "permission": { "external_directory": { "~/.secrets/**": "ask", "*": "allow" } } } +``` + +Full threat model in the `secrets-and-config` knowledge. + +## Where things live + +| Path | Holds | +|---|---| +| `{{ package_name }}/` | source — `.pyi` stubs + `.py` bodies | +| `tests/integration/`, `tests/e2e/` | integration + E2E tests only (no unit) | +| `tests/cassettes/`, `tests/fixtures/` | recorded vcrpy cassettes; fixtures | +| `migrations/` | Alembic migrations — the schema spec | +| `docs/glossary.md` | ubiquitous language | +| `.flowr/flows/` | the six flow definitions | +| `.opencode/`, `.templates/`, `.github/` | methodology, templates, CI | + +## Workflow + +The staged-contract pipeline runs discover → explore → plan → build → deliver → +shipped, one state at a time through flowr. Tests are the source of truth for +behaviour. See `AGENTS.md` for the operating discipline, the driving loop, and +the flowr commands. diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 1867c7c9..00000000 --- a/TODO.md +++ /dev/null @@ -1,300 +0,0 @@ -# TODO — temple8 clean-slate rebuild - -Rebuilding temple8 on a tests-as-truth model. Requirements are elicited via the -interview funnel (discovery); every external service is empirically grounded -(explore — read docs, run authenticated probes, record real request/response -shapes as vcrpy cassettes); the requirements + captured reality are then encoded -up front (plan) as a staged contract surface: test `.pyi` → reviewed test `.py` -(bodies, each marked `@pytest.mark.pending`) → source `.pyi` derived from the -tests → simulated. Build implements each source `.py` from its `.pyi` to make -the already-written tests pass (red removes the target's pending mark); tests -are otherwise not edited during build. Tests are the source of truth for -behaviour; the one authoritative artifact for each concern tests can't store -(ORM + migrations, typed Settings, adapter cassettes) is never duplicated in -prose. Each unit of work ships as its own source `.py` + structural artifacts — -one commit. - -Flow: `pipeline-flow` orchestrates five subflows. -- `discovery-flow`: `interview-general → interview-cross-cutting → - interview-building-blocks → consolidate-interview` (exit `interview-ready`). -- `explore-flow`: `select-external-target → research-provider → write-probe → - record-cassette` (loop, one service per pass; exits `explored-ready`, - `needs-elicitation`). -- `plan-flow`: `author-test-stubs → review-test-stubs → write-test-py → - derive-source-stubs → simulate-contracts` (exits `contracts-ready`, - `needs-elicitation`). -- `tdd-flow`: `select → red → green → refactor → review → ship` - (exits `all-built`, `needs-contracts`). -- `deliver-flow`: `merge → publish` (exit `delivered`). -Lifecycle: `discover → explore → plan → build → deliver → shipped`; `build` -re-enters `plan` on `needs-contracts`; `plan` and `explore` re-enter `discover` -on `needs-elicitation`. - -## Contract chain - -The contract is staged, cheap-to-skim first, executable next, source-surface -last — each step forces the next via imports. Explore grounds the external -layer in reality first (committed cassettes); plan produces the full surface -(test `.pyi` + test `.py` + source `.pyi`); build implements the source `.py`. -Drift between `.pyi` and `.py` is caught by `mypy.stubtest` (run at green, -review, ship, and merge). - -Sequence (the authoritative development order): - -1. **interview-general** *(discover)* — Funnel L1: seven big-picture questions - (Who, What, Why, When/Where, Success, Failure, Out-of-scope); CIT + - Laddering + CI Perspective; active listening L1 (paraphrase each answer). No - category labels (priming bias). Begins the single running interview-notes - artifact. -2. **interview-cross-cutting** *(discover)* — Funnel L2: behaviour groups, - bounded contexts, integration points, lifecycle events; active listening L2 - (synthesis per group). Appends to interview-notes. -3. **interview-building-blocks** *(discover)* — Funnel L3: building-block names + rough - boundaries only (no detailed spec); gap analysis (every context / quality - attribute → ≥1 building block). Appends to interview-notes. -4. **consolidate-interview** *(discover)* — active listening L3: full synthesis - → stakeholder approval; author `docs/glossary.md`. Exit `interview-ready`. -5. **explore external services** *(explore)* — a four-state loop, one external - service per pass. `select-external-target` reads the interview's external - services, cross-checks committed `tests/cassettes//`, picks the - next un-probed one (→ `.cache//probe-target.md`), or exits - `explored-ready` when none remain (pass-through when the interview named no - external services). `research-provider` identifies the exact provider, - researches it ONLINE (websearch + webfetch the official docs; no probe code - until docs are read), determines the access shape, and recommends the ≤1 - advisory specialist (→ `.cache//probe-research.md`). - `write-probe` authors the minimal probe script (success + ≥1 error) under - `.cache/explore//` (gitignored throwaway). `record-cassette` runs the - probe, RECORDS the real exchange into `tests/cassettes//` with - decode + secret/volatile scrubbing, and appends - `.cache//external-contracts.md`; then `captured` back to - select. External services only (third-party APIs/SaaS, external managed - DBs/stores — not DBs we design or UI we define). Only four knobs vary by - kind (docs-focus, recorder, scrub-fields, default specialist) — they live in - each skill's kind-dispatch table, not separate states. Re-enter `discover` - (`needs-elicitation`, from research-provider/record-cassette) when reality - contradicts the interview. -6. **author-test-stubs** *(plan)* — author `tests/integration|e2e/**/*_test.pyi` - (signatures expressing domain / relationships / compositions) in layer order, - asserting external stubs against the captured cassettes (real shapes, not - guesses). Each test `.pyi` is a COMPLETE stub: every module-level name - (constants, fixtures, helpers) + class + method signatures; NO third-party - imports (they trip mypy import-untyped; stubtest doesn't need them). - Integration + E2E ONLY (no unit tests); drawn from the interview + explore, - not BDD features. No `.py` yet. -7. **review-test-stubs** *(plan)* — gate: consistency vs interview + ubiquitous - language (external stubs match the cassettes); scope is integration + E2E - only; happy-path completeness (every building block → ≥1 stub). Not a code-quality - gate (that's next). -8. **write-test-py** *(plan)* — transform the reviewed stubs into - `tests/**/*_test.py` bodies (no docstrings, no comments). Bodies define how - entities relate / compose. SOLID / DRY / KISS / YAGNI / Object Calisthenics - gate HERE. Each test is marked `@pytest.mark.pending` (conftest skips it). - The `` (system-under-test) import is DEFERRED into each test body so - an unbuilt module collects cleanly and its pending tests skip rather than - error; third-party / test-only imports stay at module top. The imports assert - the surface the source stubs must provide. Reworking an EXISTING contract: - edit the `.py` body to match the changed `.pyi` and re-apply - `@pytest.mark.pending` so it skips until build re-selects it. -9. **derive-source-stubs** *(plan)* — derive `/**/*.pyi` from the - reviewed test `.py`: every type a test references gets a definition. No - hardcoded layout (no `models/`, no `config.pyi`); config follows the - secrets/config split per the `secrets-and-config` knowledge (non-secret config - in workspace `.env`; secrets in `~/.secrets/.env` via - `dotenv_values()`, never `os.environ`; a typed Settings model is optional, a - normal source `.pyi` if warranted). -10. **simulate-contracts** *(plan)* — gate: would passing these tests yield a - complete, working system? pyright (combined set consistent; every import - resolves), no-orphans, traceability (every external service has a captured - cassette), layer order, `stubtest tests` (test `.pyi`/`.py` drift-free — - source stubtest waits for build, no source `.py` yet). Exit `contracts-ready`. -11. **red** *(build)* — remove the target contract's `@pytest.mark.pending` - marks, run its tests (already written); they fail for the right reason: - `ImportError` for new work (source absent — `.pyi` is invisible to runtime - import; the deferred in-body import raises), or assertion failure for - rework (source `.py` stale against the changed contract). No other test - editing. Escalate `needs-contracts` on a contract gap. -12. **green** *(build)* — implement `/**/*.py` from its `.pyi`; emit - structural artifacts (migrations; replay the cassettes captured in explore); - `.pyi` fixed; `stubtest` clean. -13. **refactor → review → ship** *(build)* — source `.py` fluid, `.pyi` fixed; - SOLID/DRY/KISS/YAGNI/Object Calisthenics on the `.py`; `stubtest` + tests - green; ship one commit per unit. (Progress is read on demand from the - pending marks — no PROGRESS file.) -14. **merge** *(deliver)* — no `@pytest.mark.pending` markers remain on dev - (all source built), full suite green on dev AND `stubtest` clean on dev. - -Build layer order (outside-in): L1 external-boundary (external APIs, databases, -UI, UX) → L2 adapters/connectors/facades → L3 internal data representations → -L4 internals (CLI, business rules). Enforced as a rule inside `select` (pick -lowest-layer pending source stub) and `author-test-stubs` (author in order). - -Read discipline: stubs (`.pyi`) are the cheap signature view — read the target -contract's `.pyi` first and open a `.py` only for the detail its stub omits; -operate on the target (recorded in `.cache//build-target.md` during -build), never ingest the whole project. - -Design decisions: - -- Discovery elicits; explore grounds external reality; plan authors contracts. - The interview is four funnel-aligned states; explore is one empirical state; - the technique (CIT, Laddering, CI Perspective, Funnel, Active Listening - L1/L2/L3) lives in the `requirements/interview-techniques` knowledge file, - loaded by each of the four `interview-*` skills (one skill per funnel state). -- Explore produces two sharply separated artifacts: committed vcrpy cassettes - (`tests/cassettes/**` — the authoritative external contract, replayed by - tests/CI offline) and gitignored throwaway probe scripts (`.cache/explore/` — - reference for the green implementer, never imported by `` or tests). - Capture needs real credentials the user supplies in - `~/.secrets/.env` (see the `secrets-and-config` knowledge — agent - instructs, never creates or debugs a secret); CI never runs explore, it - replays the cassettes. -- Every state has its OWN skill — no skill is reused across states (the four - interview states each have a distinct skill that loads the shared technique - from knowledge). -- Test `.pyi` is the cheap-to-skim signature view; the test `.py` (written at - `write-test-py`) is the executable truth. Both persist; `stubtest` keeps them - in sync. -- Source `.pyi` is the pre-implementation design surface, derived from the test - `.py`; `simulate-contracts` validates the combined set before any source `.py` - body exists. -- The source `.pyi` is FIXED during build — if implementation reveals the - contract is insufficient, escalate to plan (`needs-contracts`) rather than - edit the stub ad hoc. -- `@pytest.mark.pending` (custom marker; root `conftest.py` hook skips pending - tests) IS the build backlog signal - it covers BOTH new work (source not yet - implemented) AND rework (source stale against a changed contract). The - `` import is deferred into each test body so unbuilt modules collect - cleanly and pending tests skip rather than error. Build's red removes the mark - from the target contract's tests; deliver's merge requires no markers remain. - Reworking an existing contract in plan = change its `.pyi` + `.py` and - RE-APPLY the mark, so the test skips and re-enters the build queue even though - its source `.py` already exists. -- `mypy.stubtest` is the single drift detector for BOTH source and tests — - pyright and ruff do NOT detect `.py`/`.pyi` drift (pyright actively hides it - by preferring the stub). -- Config follows 12-factor: environment variables, never a hardcoded config - artifact. A typed Settings model is optional. -- `` is the flowr session name (the `--name` passed to - `flowr session init pipeline-flow --name `). Per-session artifacts - (`interview-notes.md`, `external-contracts.md`, `build-target.md`) live under - `.cache//`; shared artifacts (`docs/glossary.md`) live at the - repo root under `docs/`. -- No docstrings: code (source, tests, stubs) carries no docstrings during - development — `D`/pydocstyle is dropped from ruff; docstrings are never - authored (token economy — no duplicate code/docstring snippets to sync). -- Evidence vs enforcement: flowr gate `conditions` collect EVIDENCE the agent - asserts; flowr does not run checks. CI is the enforcement backstop — it runs - ruff (with `PYI`), pyright, mypy.stubtest, and pytest on every push and - verifies the asserted evidence. - -Progress mechanism: the backlog is the set of tests carrying -`@pytest.mark.pending` (`uv run pytest --collect-only -m pending -q` lists -them), grouped by the source contract each exercises. The built/pending ratio -is source contracts with no pending test (built) vs with at least one pending -test (pending). It is read on demand — never written to a file. - -Known constraints (revisit if they bite): - -- pyright prefers `.pyi` over `.py` (PEP 484): while a `.pyi` exists, pyright - checks the stub and ignores the `.py`. Tests opt out of `ANN`/`D` - (`pyproject.toml` per-file-ignores), so this is moot for type-checking but - means pyright won't catch a stale `.py` — `stubtest` must. -- After `write-test-py`, test `.pyi` and test `.py` coexist and can drift; - `mypy.stubtest` checks the test pair STRICTLY: the test `.pyi` must declare - every module-level name (constants, fixtures, helpers) + the class + method - signatures, and must NOT import third-party libs (they trip mypy - import-untyped; stubtest doesn't require them). `stubtest tests` runs at - simulate; scoped `stubtest . tests.` at green/review; - whole `stubtest app tests` at merge. Source and tests are BOTH first-class - stubtest targets. -- `stubtest` imports modules at runtime; it is a SEPARATE step from - `static-check` (pyright); both run in `release-check`. -- `stubtest` ships with `mypy` (added to dev deps). Every `.pyi` is a second - source of truth that must be kept synced with its `.py`; `stubtest` catches - drift only when run, not on every edit. -- The deferred `` import convention is required for the pending mark to - produce clean skips; if a test imports the SUT at module top, an unbuilt - module errors at collection (before the conftest hook runs) instead of - skipping. -- Committed vcrpy cassettes can leak secrets unless `filter_headers` / - `before_record` scrub them at record time; review cassettes before commit. - -Markers: `[x]` done · `[ ]` pending · `[~]` in progress. - -## Flow design debt (rework path — happy path verified in simulation, rework path untested) -- [ ] `needs-contracts` carries no persisted handoff — build/red `output artifacts: []`, so the gap relies on undocumented orchestrator prompt-stuffing. Add a `.cache//contract-gap.md` that `author-test-stubs` reads on re-entry, or document the prompt-stuffing convention explicitly. -- [ ] Plan authoring states (`author-test-stubs`, `write-test-py`, `derive-source-stubs`) list their OUTPUT globs but not the EXISTING instances — a fresh pass is explicit, a rework pass is implicit ("read what's on disk"). Add the existing-output globs as inputs. -- [ ] Escalations re-enter subflows at the FIRST state (flowr has no position memory); rework re-runs the whole chain and full gates. Document the cost or accept it. - -## Knowledge to author (Stage 3 — derived from the skills' `[[...]]` citations) -18 distinct knowledge files cited across the 21 skills. Ordered by LIFECYCLE — the sequence in which an agent meets them as a session runs (discover → explore → plan → build → deliver); each appears once, at its first encounter. Raw material lives in `.backup/.opencode/knowledge/` — restore selectively and rewrite (the backup is beehave-stale; do NOT bulk-copy). Skills' forward-ref wikilinks resolve once these exist; track as debt until authored. - -**Discover (interview funnel):** -- [x] `requirements/interview-techniques.md` — Elicitation methods (CIT, Laddering/Means-End, CI Perspective Change, Funnel, Active Listening L1-L3) applied at each funnel depth. *(interview-general, interview-cross-cutting)*. AUTHORED. -- [x] `requirements/domain-decomposition.md` — Decomposing each bounded context into DDD building blocks (aggregate-first); gap analysis as a coverage matrix (every context → ≥1 block; every quality attribute → ≥1 block). *(interview-building-blocks, review-test-stubs)*. AUTHORED. -- [x] `requirements/aggregate-boundaries.md` — Sizing and splitting aggregates: single-entity default, reference-by-identity, split on invariant seams (Evans ch 4; Vernon ch 10). *(interview-building-blocks)*. AUTHORED. -- [x] `requirements/ubiquitous-language.md` — Curating the glossary: term extraction, genus-differentia definitions, bounded-context grouping (Evans DDD). *(consolidate-interview)*. AUTHORED. - -**Explore (ground externals):** -- [x] `software-craft/external-fixtures.md` — Capturing external reality: record-once-replay-forever (vcrpy HTTP cassettes; CI under `VCR_RECORD_MODE=none`), the kind-dispatch table (recorder/docs-focus/scrub-fields/specialist per kind — vcrpy is HTTP-only), two scrubs (safety + determinism), 12-factor creds, capture-is-truth. *(research-provider, write-probe, record-cassette)*. AUTHORED. -- [x] `software-craft/secrets-and-config.md` — The secrets/config split: non-secret config in workspace `.env`; secrets in `~/.secrets/.env` (out-of-workspace) read with `dotenv_values()` into a frozen typed Settings, never `os.environ`; the LLM-agent threat model (5 vectors) + layered defense; agent never creates/reads/debugs a secret (instructs the user; asks with suggestions on auth failure); `.env.example` as the committed env contract. *(write-probe, research-provider, derive-source-stubs, implement-from-stub)*. AUTHORED. - -**Plan (author contracts):** -- [x] `software-craft/test-stubs.md` — PEP 484 `.pyi` signature files for tests (disambiguated from the Meszaros test double); `.pyi`-preferred hides drift from pyright, stubtest is the sole detector; mirror the complete module surface; stdlib-typing-only with types under `TYPE_CHECKING`. *(author-test-stubs, simulate-contracts)*. AUTHORED. -- [x] `software-craft/test-design.md` — Observable behaviour not implementation; sociable tests at two grains only (integration narrow + E2E broad, no solitary unit); one behaviour per test; spec value fidelity; property tests (Hypothesis) prove invariants. *(author-test-stubs, write-test-py)*. AUTHORED. -- [x] `software-craft/code-review.md` — Adversarial review (Fagan 1976; Tetlock); fail-fast at the first defect; reviewer reports APPROVED/REJECTED only, never edits, "minor" is not a pass; two modes (review-test-stubs = coverage/scope/happy-path vs interview; review-implementation = correctness/quality/drift/green); PASS/FAIL record per criterion. *(review-test-stubs, review-implementation)*. AUTHORED. -- [x] `software-craft/solid.md` — The 5 SOLID principles (Martin 2000/2003), applied when a smell triggers, never speculatively; violation→smell→fix map. *(write-test-py, refactor-green, review-implementation)*. AUTHORED. -- [x] `software-craft/object-calisthenics.md` — Jeff Bay's 9 rules (ThoughtWorks Anthology, 2008): an exercise-turned-guideline, applied as the quality bar not a literal counter. *(write-test-py, refactor-green)*. AUTHORED. -- [x] `software-craft/smell-catalogue.md` — Fowler's (1999) 5 categories (Bloaters, OO Abusers, Change Preventers, Dispensables, Couplers) with Smell/Signal/Fix tables; a Comment is a symptom of code needing extraction. *(write-test-py, refactor-green, review-implementation)*. AUTHORED. -- [x] `software-craft/source-stubs.md` — Source `.pyi` derived from the test bodies (inverse of conventional); signature-only `...`; FIXED during build (escalate on gap); no prescribed layout; config 12-factor; structural artifacts keyed to the module; scoped stubtest. *(derive-source-stubs, implement-from-stub)*. AUTHORED. -- [x] `requirements/spec-simulation.md` — Mental execution of the contract SET (tests are the spec, not prose): walk the e2e path hop-by-hop + trace each domain value across tests for shape coherence; the tool floor (pyright/stubtest/no-orphans/traceability) is necessary but not sufficient — composition + cross-test coherence are tool-blind. Output is a judgment + named gaps, not JSON ceremony. *(simulate-contracts)*. AUTHORED. - -**Build (implement):** -- [x] `software-craft/tdd.md` — The red/green/refactor cycle adapted: tests pre-exist so red un-marks + confirms the right failure (ImportError = new, assertion = rework); minimum code YAGNI/KISS; refactor under green with `.pyi` frozen; per-contract in dependency order. *(select-build-target, confirm-red-failure, implement-from-stub)*. AUTHORED. -- [x] `software-craft/design-patterns.md` — GoF patterns applied only when a smell triggers (Gamma 1994; Shvets 2014); foregrounds the small set this flow's architecture hosts (Adapter, Repository, Facade, Strategy/State, Factory, value object); smell→pattern lookup. *(implement-from-stub)*. AUTHORED. -- [x] `software-craft/refactoring-techniques.md` — Fowler's (1999) refactor moves organised by problem (composing methods, moving features, organising data, simplifying conditionals/calls, generalisation); reference index pointing at the right move, mechanics deferred to the skill/book; `.pyi` fixed under green. *(refactor-green)*. AUTHORED. - -**Deliver (ship):** -- [x] `software-craft/git-conventions.md` — Conventional Commits (`(): `); one logical change per commit (ship-unit: one contract, `.pyi` unchanged); refactor separate from feature; three-branch model `feature`→`dev`→`release`/`main`; squash-merge into dev gates whole-suite + stubtest. *(ship-unit, merge-to-dev, publish-release)*. AUTHORED. -- [x] `software-craft/versioning.md` — SemVer 2.0.0 bump rules + 0.x instability; PEP 440 for Python (`X.Y.Z` core, `+local` stripped by indexes); CalVer when timing matters more than compatibility; pyproject `version` is the single source of truth; publish picks notes / PR to main / `v{version}` tag. *(publish-release)*. AUTHORED. - - -## pyproject + tooling -- [x] `[project].readme` and `[project.urls]` — kept as-is (identity not reset per decision); README authoring tracked under Docs. -- [x] `version` and `description` — kept as-is per identity decision. -- [x] Consolidated to one `[project.optional-dependencies].dev`; deleted `[dependency-groups].dev`. `flowr` moved from runtime to dev; `flowr[viz]` dropped. -- [x] Dropped the `conventions` task (the style backdoor selecting `I`/`ANN`/`N`/`E`/`W`/…); `release-check` now uses `ruff check .` via `lint`. -- [ ] Wire `stubtest` / `static-check` / coverage (`--cov`) / `run` tasks to the real package once created (all target the `app` placeholder; `doc-serve`/`doc-build`/`doc-publish` dropped until the package exists). -- [x] Dropped `beehave` / `pytest-beehave` deps + `[tool.beehave]`. -- [x] `requires-python` set to `>=3.13` (flowr>=1.2.1 requires >=3.13; 3.12 was the intent but deps constrain it). -- [x] Task runner: `taskipy`, invoked via `uv run task `. - -## Package + tests skeleton -- [ ] Decide package name (old default `app`) and create the minimal package. -- [ ] `tests/integration/` — one module per boundary (config, external - adapters, APIs, databases). -- [ ] `tests/e2e/` — CLI / object-composition / contract-chaining tests. -- [ ] `tests/cassettes/` — recorded vcrpy cassettes (captured during explore; - committed; replayed by tests + CI offline). -- [ ] `tests/fixtures/` — static fixtures not covered by cassettes. -- [ ] No `tests/unit/` by policy. - -## Structural artifacts (one authoritative home each, no prose duplicate) -- [ ] ORM models + Alembic migration skeleton — relationships / data shape. -- [ ] Typed Settings model — config parameter definitions (12-factor: env vars). -- [ ] External-adapter cassettes — recorded in explore; replayed in tests. -- [ ] `docs/glossary.md` — ubiquitous language; drives naming (from template). - -## Docs -- [ ] `README.md` — author a fresh one for the rebuild (deleted in clean-slate; pyproject references it). -- [ ] `CHANGELOG.md` — decide whether to maintain (deleted; `publish-release` implies one may be wanted). - -## Docs-as-derived -- [ ] Decide the derivation mechanism (tool? extraction script? manual?) that - regenerates docs/specs from the green suite. - -## Template mechanism -- [ ] Decide how downstream projects inherit this (cookiecutter / copier / - plain copy), replacing the old `.templates/` + `template-config.yaml` + - setup-* skills (all in `.backup/`). diff --git a/copier.yml b/copier.yml new file mode 100644 index 00000000..f2a6c3b0 --- /dev/null +++ b/copier.yml @@ -0,0 +1,100 @@ +_min_copier_version: "8.0.0" + +project_name: + type: str + help: Human-readable project name (e.g. "weather-lookup"). + validator: >- + {% if not (project_name | regex_search('^[a-z][a-z0-9-]*$')) %} + lowercase letters, digits, dashes; start with a letter. + {% endif %} + +package_name: + type: str + help: Python import package name (e.g. "weather_lookup"). Must be a valid identifier. + default: "{{ project_name | replace('-', '_') }}" + validator: >- + {% if not (package_name | regex_search('^[a-z][a-z0-9_]*$')) %} + lowercase letters, digits, underscores; start with a letter (valid Python identifier). + {% endif %} + +description: + type: str + help: One-line project description. + +repo_url: + type: str + help: Repository URL (e.g. https://github.com/owner/repo). Leave blank if none yet. + default: "" + +version: + type: str + default: "0.1.0" + +author_name: + type: str + help: Your name (for pyproject authors). + +author_email: + type: str + help: Your email (for pyproject authors). + +keep_design: + type: bool + default: true + help: Keep the design knowledge domain (interaction/visual/asset/cli/api/accessibility) + design skills + asset templates? Drop for pure-backend projects with no UI surface. + +keep_research: + type: bool + default: true + help: Keep the docs/research/ reference library + research-files knowledge + research card template? + +reset_git: + type: bool + default: true + help: Initialize a fresh git repository in the new project? + +_exclude: + # copier defaults (re-listed: defining _exclude replaces the default) + - copier.yml + - copier.yaml + - "~*" + - "*.py[co]" + - __pycache__ + - .git + - .DS_Store + - .svn + # temple8 working files (the .jinja versions render the instance's) + - pyproject.toml + - README.md + # template-only artifacts (never in instances) + - .backup + - .opencode/agents/project-instantiator.md + - .opencode/skills/instantiate-project + - docs/decisions/2026-07-02-use-pyi-first-contracts.md + # conditional design removal + - "{% if not keep_design %}.opencode/knowledge/design{% endif %}" + - "{% if not keep_design %}.opencode/skills/design-interaction{% endif %}" + - "{% if not keep_design %}.opencode/skills/design-visual-asset{% endif %}" + - "{% if not keep_design %}.templates/docs/assets{% endif %}" + - "{% if not keep_design %}docs/research/software-engineering/design{% endif %}" + # conditional research removal + - "{% if not keep_research %}docs/research{% endif %}" + - "{% if not keep_research %}.opencode/knowledge/methodology/research-files.md{% endif %}" + - "{% if not keep_research %}.templates/docs/research{% endif %}" + +_tasks: + - "mkdir -p {{ package_name }}" + - "touch {{ package_name }}/__init__.py" + - "mkdir -p tests/integration tests/e2e tests/cassettes tests/fixtures" + - "touch tests/cassettes/.gitkeep tests/fixtures/.gitkeep" + - "{% if reset_git %}git init{% endif %}" + +_message_after_copy: | + Project "{{ project_name }}" created at {{ _copier_conf.dst_path }}. + + Next: + 1. cd {{ _copier_conf.dst_path }} + 2. uv sync --extra dev + 3. uv run python -m flowr session init pipeline-flow --name default + + Drive the pipeline one state at a time. See AGENTS.md for the operating discipline. diff --git a/docs/research/information-science/writing/jackson_2026.md b/docs/research/information-science/writing/jackson_2026.md new file mode 100644 index 00000000..ef1ab251 --- /dev/null +++ b/docs/research/information-science/writing/jackson_2026.md @@ -0,0 +1,30 @@ +# The Real Signature of AI Writing Isn't the Em-Dash Anymore (Jackson, 2026) + +## Citation +Jackson, I. (2026). "The Real Signature of AI Writing Isn't the Em-Dash Anymore." *WriteHuman* blog, 21 April 2026. +URL: https://writehuman.ai/blog/ai-tells-in-2026 + +## Method +Corpus analysis of 80,141 humanization pairs (AI input vs humanized output) from the WriteHuman service, scored with the G² log-likelihood ratio (Dunning, 1993); positive G² = over-represented in AI input. + +## Confidence +Medium-High — a vendor blog, but the method, sample size (80,141 pairs), and per-feature statistics are stated; corroborated by independent sources on burstiness and hedging. + +## Key Insight +The strongest 2026 AI tells are structural (hedging verbs and formulaic sentence shapes), not the em-dash of 2024 reputation; `ensuring` and `rather than` are the single strongest word and multi-word signals. + +## Core Findings +1. `ensuring` / `ensures` over-represented 4.3× — the strongest single-word tell; joined by a hedging-verb family (`highlights`, `supports`, `reflects`). +2. `rather than` over-represented 2.5× (17,251 occurrences in AI inputs vs 6,859 in humanized) — the strongest multi-word tell. +3. Em-dashes: 18.5% of AI inputs contain ≥1 vs 7.1% of humanized (2.6×) — a real but weaker signal than its reputation. +4. "Relational connectors" (`rather`, `broader`, `reducing`) act as glue the model uses to avoid making a direct claim. +5. The G² log-likelihood ratio (Dunning, 1993) is the scoring statistic — the standard corpus-vs-corpus comparison. + +## Mechanism +Each feature's occurrence is compared between AI inputs and humanized outputs across 80,141 pairs; G² quantifies over-representation. Hedging verbs and significance-inflation emerge because the model optimises for "considered-sounding" prose (RLHF preference), padding claims rather than stating them. The humanizer strips these, exposing them as the differential. + +## Relevance +Grounds the hedging-verb, filler, and structural-marker claims in `writing/ai-language-markers` with concrete multipliers, and downgrades the em-dash from its caricatured status. The actionable edits (cut `rather than`; restate the comparison directly; drop significance-inflation) come straight from the data. + +## Related Research +Kobak et al., 2024 (vocabulary overrepresentation); Duey, 2026 and Leap AI, 2026 (burstiness / cadence uniformity as the persistent structural signal). diff --git a/docs/research/information-science/writing/kobak_2024.md b/docs/research/information-science/writing/kobak_2024.md new file mode 100644 index 00000000..ffd9775f --- /dev/null +++ b/docs/research/information-science/writing/kobak_2024.md @@ -0,0 +1,30 @@ +# Delving into ChatGPT usage in academic writing through excess vocabulary (Kobak et al., 2024) + +## Citation +Kobak, D., et al. (2024). "Delving into ChatGPT usage in academic writing through excess vocabulary." *arXiv:2406.07016* (published *Scientometrics*, 2025). +URL: https://arxiv.org/abs/2406.07016 + +## Method +Large-scale corpus analysis of ~14 million PubMed abstracts (2010–2024); "excess word" frequency analysis after a baseline, with comparative RLHF model testing. + +## Confidence +High — peer-reviewed-scale bibliometric study; method and data described transparently. + +## Key Insight +The arrival of LLMs caused an abrupt, unprecedented spike in the frequency of certain "style words" in scientific abstracts, and an excess-vocabulary lower bound estimates at least 10% of 2024 PubMed abstracts were processed by an LLM. + +## Core Findings +1. Twenty-one "focal words" whose PubMed frequency spiked with LLM adoption (e.g. `delve`, `intricate`, `underscore`, `showcasing`, `pivotal`, `realm`, `meticulously`). +2. At least 10% of 2024 abstracts were LLM-processed; the lower bound reaches ~30% in some sub-corpora (by country, journal, discipline). +3. The vocabulary shift exceeds the effect of major events like the COVID-19 pandemic on scientific language. +4. Comparative model testing (Llama with/without RLHF) is consistent with RLHF contributing to the overuse — architecture and training data alone do not explain it. +5. Pre-LLM baselines show these words were rare; the spike is not a continuation of a prior trend. + +## Mechanism +The authors compute per-word frequency trajectories across 14M abstracts, identify words whose post-2022 frequency far exceeds the pre-LLM baseline ("excess" vocabulary), and use the aggregate excess to estimate a lower bound on LLM-processed abstracts. The RLHF role is probed by comparing models with and without RLHF fine-tuning. + +## Relevance +Grounds the vocabulary-overrepresentation claims in `writing/ai-language-markers`: the overused lexicon is empirically established (not anecdotal), the RLHF mechanism is named (not the unverified "regional annotator" story), and the scale (≥10% of 2024 abstracts) shows the instinct's reach. + +## Related Research +medRxiv (2024) co-occurrence study (`delve`/`realm`/`underscore`, 85-fold rise); Jackson, 2026 (structural tells); arXiv:2412.11385 (the "puzzle of lexical overrepresentation" formalisation). diff --git a/docs/research/software-engineering/architecture/bass_2021.md b/docs/research/software-engineering/architecture/bass_2021.md new file mode 100644 index 00000000..e4674f28 --- /dev/null +++ b/docs/research/software-engineering/architecture/bass_2021.md @@ -0,0 +1,30 @@ +# Software Architecture in Practice, 4th ed. (Bass, Clements & Kazman, 2021) + +## Citation +Bass, L., Clements, P., & Kazman, R. (2021). *Software Architecture in Practice*, 4th Edition. Addison-Wesley Professional (SEI Series in Software Engineering). 464 pp. ISBN 978-0-13-688609-9. +URL: https://www.informit.com/store/software-architecture-in-practice-9780136886099 + +## Method +Practitioner reference (the SEI's canonical software-architecture text); synthesises ATAM, the quality-attribute tactics catalogs, and architecture-analysis practice. + +## Confidence +High — the foundational SEI text; widely cited. + +## Key Insight +Quality attributes (the `-ilities`) are the architectural drivers, distinct from functional requirements; each has a tactics catalog and an analysis method (ATAM), and trade-offs between conflicting attributes are the architect's core decision. + +## Core Findings +1. A canonical quality-attribute set: Availability, Deployability, Interoperability, Modifiability, Performance, Security, Testability, Usability (the 4th-edition list). +2. Each attribute has a **tactics catalog** — design moves that directly address it (Performance: caching/concurrency/resource arbitration; Availability: redundancy/fault-detection/recovery; Modifiability: encapsulation/binding-time/substitution; etc.). +3. Attributes conflict (Performance vs Modifiability; Security vs Performance) and the architect resolves them by **explicit prioritisation**, not by optimising everything. +4. **ATAM** (Architecture Tradeoff Analysis Method) prioritises via a utility tree: scenarios ranked by business value × architectural difficulty, so the highest-value, hardest scenarios get attention first. +5. Quality-attribute **scenarios** (stimulus → environment → response) make an `-ility` concrete enough to design and test against. + +## Mechanism +A quality attribute is made operational as a scenario ("a user request arrives under peak load; the system responds within 200ms 99% of the time"). The scenario is the unit of analysis: tactics are selected to satisfy it, architectural styles are judged by whether their tactics cover it, and ATAM ranks scenarios to force explicit, business-justified prioritisation of the conflicts. Trade-offs that survive the analysis are the architecturally significant decisions worth recording. + +## Relevance +Grounds `architecture/quality-attributes`: the taxonomy, the conflict/trade-off model, and the scenarios that make `-ilities` elicitable in an interview. The full ATAM ceremony is trimmed for this flow (no separate assessment state) — what survives is *elicit the attributes that matter, surface the conflicts, record the load-bearing trade-offs as ADRs*. + +## Related Research +Evans, 2003 (bounded-context boundaries as a modifiability/interoperability tactic); Vernon, 2013 (context-mapping as inter-context trade-off management). diff --git a/docs/research/software-engineering/design/nielsen_1994.md b/docs/research/software-engineering/design/nielsen_1994.md new file mode 100644 index 00000000..c96612e2 --- /dev/null +++ b/docs/research/software-engineering/design/nielsen_1994.md @@ -0,0 +1,29 @@ +# 10 Usability Heuristics for User Interface Design (Nielsen, 1994) + +## Citation +Nielsen, J. (1994). "10 Usability Heuristics for User Interface Design." *Nielsen Norman Group* (article first published 1994; updated 2020). URL: https://www.nngroup.com/articles/ten-usability-heuristics/ +Academic source: Nielsen, J. (1994). "Enhancing the Explanatory Power of Usability Heuristics." *CHI '94 Proceedings*, 152–158. DOI: 10.1145/191666.191729. + +## Method +Heuristic evaluation — a discount-usability method: expert review of an interface against a small set of broad principles (heuristics), refined here by a factor analysis of 249 usability problems to maximise explanatory power. + +## Confidence +High — the working canon of heuristic evaluation for 30+ years; the heuristics have been stable since 1994. + +## Key Insight +Ten broad principles — visibility of system status, match between system and the real world, user control and freedom, consistency and standards, error prevention, recognition rather than recall, flexibility and efficiency of use, aesthetic and minimalist design, help users recognise/diagnose/recover from errors, and help and documentation — explain the great majority of usability problems and let an evaluator find violations by inspection. + +## Core Findings +1. The ten heuristics derive from a factor analysis of usability-problem explanations; they were chosen for maximum coverage of real problems, not invented top-down. +2. The set has been stable and relevant since 1994 — a durability the author attributes to its grounding in fundamental human cognition rather than any one technology. +3. Heuristic evaluation is a discount method: cheaper than user testing, most effective when paired with it, and a way to catch the majority of issues before the more expensive test cycle. +4. The heuristics are deliberately broad rules of thumb, not specific prescriptive guidelines — they apply across interaction styles (the same ten cover GUI, web, mobile, CLI-adjacent). + +## Mechanism +An evaluator walks the interface task by task and asks, at each step, which heuristic is violated. The ten heuristics are the lens: a hidden system status violates "visibility"; an inconsistent action violates "consistency and standards"; an error the user cannot recover from violates the error-recovery heuristic. The method's power is coverage — the ten were selected to explain the largest share of a real problem database — and its economy — one trained evaluator finds most issues in hours. + +## Relevance +Grounds `design/interaction-design`: the heuristics table cited there is Nielsen's ten, and the load-bearing three (consistency, one-primary-action, progressive disclosure) are a working subset. They apply to every surface the ux-engineer designs. + +## Related Research +Norman, 2013 (the cognitive-science foundations the heuristics operationalise); Molich & Nielsen, 1990 (the original heuristic-evaluation method). diff --git a/docs/research/software-engineering/design/norman_2013.md b/docs/research/software-engineering/design/norman_2013.md new file mode 100644 index 00000000..93e537cc --- /dev/null +++ b/docs/research/software-engineering/design/norman_2013.md @@ -0,0 +1,31 @@ +# The Design of Everyday Things, Revised and Expanded (Norman, 2013) + +## Citation +Norman, D. A. (2013). *The Design of Everyday Things: Revised and Expanded Edition*. New York: Basic Books. 368 pp. ISBN 978-0-465-05065-9. +URL: https://jnd.org/books/the-design-of-everyday-things-revised-and-expanded-edition/ + +## Method +Practitioner / academic book (cognitive-science foundations applied to design). + +## Confidence +High — the foundational text of human-centered design; the revised edition is the current canon. + +## Key Insight +Good design closes the two gulfs between user and system — execution (figuring out what to do) and evaluation (figuring out what happened) — through discoverable affordances, clear signifiers, continuous feedback, and constraints that make the wrong action hard. + +## Core Findings +1. The **gulf of execution** is the gap between the user's intent and the actions the system offers; closed by signified affordances and matching the interface to the user's mental model. +2. The **gulf of evaluation** is the gap between the system's state and the user's understanding; closed by legible state and feedback on every action. +3. **Affordances** are possible actions an object suggests; **signifiers** (added in the revised edition) are the perceptible cues that signal where the affordance lives. Digital interfaces have weak natural affordances, so signifiers carry the load. +4. **Feedback** must be timely and informative; its absence reads as a system failure. +5. Designing for error (prevent, detect, recover) is more valuable than designing only for the happy path. +6. Human-centered design iterates on real user behavior, not on designer intuition. + +## Mechanism +Norman grounds the rules in cognitive psychology: the user forms a mental model of the system and acts on it; the system's feedback lets the user correct that model. Affordances + signifiers reduce the cost of mapping intent to action; feedback reduces the cost of mapping system state to understanding. Constraints (physical, semantic, cultural, logical) narrow the action space so the user is more likely to choose the right one. The two gulfs are the diagnostic frame — a usability problem sits in one or the other. + +## Relevance +Grounds `design/interaction-design`: the conversation model, the two gulfs, affordance/signifier/feedback, and designed-error are all Norman's framework, applied across CLI, API, and graphical surfaces in this project. + +## Related Research +Nielsen, 1994 (the heuristics that operationalise these principles); W3C WCAG 2.2 (closing the gulf for users who cannot cross it alone). diff --git a/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md b/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md new file mode 100644 index 00000000..13cd7954 --- /dev/null +++ b/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md @@ -0,0 +1,36 @@ +# flowr 1.0.0: Non-Deterministic State Machine Specification (nullhack, 2026) + +## Citation +nullhack/flowr. (2026). flowr v1.0.0. GitHub. +URL: https://github.com/nullhack/flowr · Docs: https://nullhack.github.io/flowr/ + +## Method +Specification review (the official v1.0.0 specification document and reference CLI). + +## Confidence +High — the specification is the contract; the CLI is a reference implementation. + +## Key Insight +flowr 1.0.0 is the first stable release of a non-deterministic state machine specification: it formalises a YAML format that declares what a workflow IS (structure — states, transitions, guards) and deliberately not what it DOES (no execution engine, no side effects, no opinions on retries/timeouts/error handling). The format is the foundation; shared tooling (validators, editors, visualisers, session trackers) works across any project that adopts it. + +## Core Findings +1. **Formal specification** with RFC 2119 key words (MUST/SHOULD/MAY), a formal syntax grammar, normative examples, and visual reference diagrams. The specification is the contract. +2. **Condition operators**: `~=` removed; supported are `==`, `!=`, `>=`, `<=`, `>`, `<`, with plain values as implicit `==` and numeric extraction on both sides (e.g. `>=80%` vs `75%` compares 80 vs 75). +3. **`when` forms**: a dict (inline condition-map), a string (named condition-group reference), or a list mixing both; all conditions AND-combine. +4. **Named condition groups**: states define `conditions:` blocks; transitions reference them by name in `when:`. Unknown cross-state references are validation errors. +5. **Extension + reserved keys**: `attrs` is the designated extension point for implementation-specific data. Reserved: `flow, version, params, exits, attrs, states, id, next, to, when, conditions, flow-version`. +6. **Params with defaults**: simple string lists (required) or objects with `name` + optional `default`; params without defaults must be supplied at invocation. +7. **Conformance levels**: MUST (required), SHOULD (recommended), MAY (optional). +8. **Validation (seven MUST checks at load)**: every `next` target resolves; no ambiguous targets; parent `next` keys match child `exits`; no cross-flow cycles; exit names referenced by ≥1 state; named condition references resolve; params without defaults provided. +9. **Subflow semantics**: `flow:` on a state invokes a subflow; `flow-version` constrains compatible child versions via semver ranges; parent `next` keys must match child `exits` exactly; call-stack push on entry, pop on exit; cross-flow cycles forbidden, within-flow cycles allowed. +10. **Session model**: tracks `flow, state, name, created_at, updated_at, stack, params`; atomic writes (temp-file-then-rename); filesystem is the source of truth. +11. **Semver conventions**: adding an exit = minor; adding states = patch; removing/renaming exits = major (breaking). + +## Mechanism +flowr defines what a workflow IS, not what it DOES. A YAML file declares structure; a validator checks integrity; tools query, track, and visualise. Because the format is precisely defined, validators/editors/visualisers/session-trackers interoperate across any conforming project. The non-determinism is in the routing: a state may declare several `next` transitions, and the orchestrator (an external agent) decides which to fire by asserting evidence against the guarded conditions — flowr never executes the work itself. + +## Relevance +flowr is the workflow engine that powers temple8's staged-contract pipeline. This card grounds the `workflow/flowr-operations` knowledge: the session model, the subflow call-stack, the conditions/evidence model, the validation rules, and the CLI surface that the orchestrator drives one state at a time. The "golden rules" of the operating discipline (no skip state, no bypass dispatch, evidence-based transitions) are direct consequences of this specification. + +## Related Research +Connects to finite state machine theory (Harel, 1987) and workflow management patterns (Russell et al., 2006). diff --git a/pyproject.toml b/pyproject.toml index 1f1668de..4348abee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,9 +57,7 @@ select = [ "G", "LOG", "PYI", - "RUF", "S", - "SIM", ] mccabe.max-complexity = 10 @@ -119,7 +117,9 @@ test-slow = "pytest -m slow" ruff-check = "ruff check ." ruff-format = "ruff format ." ruff-format-check = "ruff format . --check" -lint = "task ruff-check && task ruff-format-check" +lint = "task ruff-check" +lint-merge = "ruff check --extend-select SIM,RUF . && ruff format ." +strip-docstrings = "python scripts/strip_docstrings.py" static-check = "pyright app tests" stubtest = "python -m mypy.stubtest app tests" validate-flows = "bash -c 'for f in .flowr/flows/*.yaml; do python -m flowr validate \"$f\"; done'" diff --git a/pyproject.toml.jinja b/pyproject.toml.jinja new file mode 100644 index 00000000..4ea78675 --- /dev/null +++ b/pyproject.toml.jinja @@ -0,0 +1,126 @@ +[project] +name = "{{ project_name }}" +version = "{{ version }}" +description = "{{ description }}" +readme = "README.md" +requires-python = ">=3.13" +license = { file = "LICENSE" } +authors = [ + { name = "{{ author_name }}", email = "{{ author_email }}" } +] +maintainers = [ + { name = "{{ author_name }}", email = "{{ author_email }}" } +] +dependencies = [] + +[project.urls] +Homepage = "{{ repo_url }}" +Repository = "{{ repo_url }}" + +[project.optional-dependencies] +dev = [ + "flowr>=1.2.1", + "pytest>=9.0.3", + "pytest-cov>=6.1.1", + "pytest-html>=4.0.0", + "pytest-mock>=3.14.0", + "pytest-vcr>=1.0.2", + "vcrpy>=6.0.1", + "ruff>=0.11.5", + "taskipy>=1.14.1", + "hypothesis>=6.148.4", + "pyright>=1.1.407", + "mypy>=1.13.0", + "safety>=3.7.0", +] + +[tool.flowr] +flows_dir = ".flowr/flows" +sessions_dir = ".cache/sessions" +default_flow = "pipeline-flow" +default_session = "default" + +[tool.setuptools] +packages = ["{{ package_name }}"] + +[tool.ruff.lint] +ignore = [] +select = [ + "A", + "ASYNC", + "B", + "C9", + "DTZ", + "ERA", + "F", + "G", + "LOG", + "PYI", + "S", +] +mccabe.max-complexity = 10 + +[tool.ruff.lint.per-file-ignores] +"tests/**" = ["S101", "S404"] + +[tool.pytest.ini_options] +minversion = "6.0" +markers = [ + "slow: marks tests as slow (deselect with '-m \"not slow\"')", + "bug: marks tests that reproduce a reported defect (deselect with '-m \"not bug\"')", + "pending: contract test defined in discovery but not yet implemented; auto-skipped (the backlog). Remove the marker to activate (red). Query with: -m pending", +] +addopts = """ +--maxfail=10 \ +--color=yes \ +--tb=short \ +-qq \ +""" +testpaths = ["tests"] +python_files = ["*_test.py"] +python_functions = ["test_*"] + +[tool.coverage.report] +fail_under = 80 +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "if self.debug:", + "if settings.DEBUG", + "raise AssertionError", + "if 0:", + "if __name__ == .__main__.:", +] + +[tool.taskipy.tasks] +run = "python -m {{ package_name }}" +test-build = """\ +pytest \ + --doctest-modules \ + --cov-config=pyproject.toml \ + --cov-report html:docs/coverage \ + --cov-report term:skip-covered \ + --cov={{ package_name }} \ + --hypothesis-show-statistics \ + --html=docs/tests/report.html \ + --self-contained-html \ +""" +test = """\ +pytest \ + --cov-config=pyproject.toml \ + --cov-report= \ + --cov={{ package_name }} +""" +test-fast = "pytest -m \"not slow\" -q --no-header --tb=no" +test-slow = "pytest -m slow" +ruff-check = "ruff check ." +ruff-format = "ruff format ." +ruff-format-check = "ruff format . --check" +lint = "task ruff-check" +lint-merge = "ruff check --extend-select SIM,RUF . && ruff format ." +strip-docstrings = "python scripts/strip_docstrings.py" +static-check = "pyright {{ package_name }} tests" +stubtest = "python -m mypy.stubtest {{ package_name }} tests" +validate-flows = "bash -c 'for f in .flowr/flows/*.yaml; do python -m flowr validate \"$f\"; done'" + +release-check = "task lint && task static-check && task stubtest && task test" diff --git a/scripts/strip_docstrings.py b/scripts/strip_docstrings.py new file mode 100644 index 00000000..1a625215 --- /dev/null +++ b/scripts/strip_docstrings.py @@ -0,0 +1,62 @@ +"""Strip docstrings from Python source files (surgical, line-range based). + +Used by the tdd `select` state to naked a target source `.py` at cycle entry, +removing docstrings carried over from the last merge's generation pass. Tests +and stubs are never passed through here — they stay naked permanently. + +The edit is line-range only: each docstring's `[lineno, end_lineno]` is removed +and every other line (formatting, comments, blank lines) is preserved, so the +file does not get reformatted as a side-effect. Assumes bodies are not +docstring-only (true for real rework `.py`); a docstring-only body would need a +`pass` substituted, which this script does not do. +""" + +import ast +import sys +from pathlib import Path + +_NODE_TYPES = (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef) + + +def _docstring_ranges(source: str) -> list[tuple[int, int]]: + tree = ast.parse(source) + ranges: list[tuple[int, int]] = [] + for node in ast.walk(tree): + if isinstance(node, _NODE_TYPES) and node.body: + first = node.body[0] + if ( + isinstance(first, ast.Expr) + and isinstance(first.value, ast.Constant) + and isinstance(first.value.value, str) + ): + ranges.append((first.lineno, first.end_lineno)) + return ranges + + +def strip_file(path: Path) -> int: + source = path.read_text(encoding="utf-8") + ranges = _docstring_ranges(source) + if not ranges: + return 0 + lines = source.splitlines(keepends=True) + for start, end in sorted(ranges, reverse=True): + del lines[start - 1 : end] + path.write_text("".join(lines), encoding="utf-8") + return len(ranges) + + +def main(argv: list[str]) -> int: + if len(argv) < 2: + print("usage: strip_docstrings.py [...]", file=sys.stderr) + return 2 + stripped = 0 + for arg in argv[1:]: + n = strip_file(Path(arg)) + if n: + print(f"stripped {n} docstring(s) from {arg}") + stripped += n + return 0 if stripped >= 0 else 1 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) From 5864e31c3e57f6c9b6e351151b0788c160cca542 Mon Sep 17 00:00:00 2001 From: nullhack Date: Fri, 3 Jul 2026 13:12:34 -0400 Subject: [PATCH 20/28] docs(methodology): rename dispatch concept "owner" to "dispatched agent" Aligns methodology prose with the flowr dispatch_to key. Five files touched (AGENTS.md, domain-expert + security-engineer identities, flowr-operations + separation-of-concerns knowledge); prose-only -- no flow YAML, no Python. The product-owner agent name and the concern-attribution Owner column in separation-of-concerns are intentionally kept. --- .opencode/agents/domain-expert.md | 2 +- .opencode/agents/security-engineer.md | 2 +- .../methodology/separation-of-concerns.md | 2 +- .opencode/knowledge/workflow/flowr-operations.md | 14 +++++++------- AGENTS.md | 8 ++++---- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.opencode/agents/domain-expert.md b/.opencode/agents/domain-expert.md index 69c501c8..1a4872a7 100644 --- a/.opencode/agents/domain-expert.md +++ b/.opencode/agents/domain-expert.md @@ -6,7 +6,7 @@ temperature: 0.5 # Domain Expert -You are the Domain Expert. Your lens is the real-world semantics the software models — the meaning behind the terms, the edge cases that only surface in practice, and the regulatory or industry constraints that a generalist engineer will never infer from first principles. You are consulted, not the owner of a state; you supply the truth the generalists defer to. +You are the Domain Expert. Your lens is the real-world semantics the software models — the meaning behind the terms, the edge cases that only surface in practice, and the regulatory or industry constraints that a generalist engineer will never infer from first principles. You are consulted, not a state's dispatched agent; you supply the truth the generalists defer to. ## What you hold diff --git a/.opencode/agents/security-engineer.md b/.opencode/agents/security-engineer.md index 8c24bf1e..f0aaf932 100644 --- a/.opencode/agents/security-engineer.md +++ b/.opencode/agents/security-engineer.md @@ -6,7 +6,7 @@ temperature: 0.3 # Security Engineer -You are the Security Engineer. Your lens is the adversary and the blast radius. You look at any surface and ask who is trusted, what they are trusted with, how that trust is established and revoked, and what fails — for the user and for the system — when trust is misplaced. You are consulted, not the owner of a state; you deliver verdicts the owner must weigh. +You are the Security Engineer. Your lens is the adversary and the blast radius. You look at any surface and ask who is trusted, what they are trusted with, how that trust is established and revoked, and what fails — for the user and for the system — when trust is misplaced. You are consulted, not a state's dispatched agent; you deliver verdicts that agent must weigh. ## What you hold diff --git a/.opencode/knowledge/methodology/separation-of-concerns.md b/.opencode/knowledge/methodology/separation-of-concerns.md index 0c31c757..26983c41 100644 --- a/.opencode/knowledge/methodology/separation-of-concerns.md +++ b/.opencode/knowledge/methodology/separation-of-concerns.md @@ -10,7 +10,7 @@ last-updated: 2026-07-01 - Four artifact kinds, one question each: the flow answers **where** (routing), an agent answers **who** (identity), a skill answers **how** (procedure), knowledge answers **what and why** (reference). - Each fact lives in exactly one canonical location; any copy becomes a second source that drifts, and the stale copy usually wins attention at runtime. -- The flow YAML is the spine — it binds a state to its owner, procedure, artifacts, branch, gate, and exits; the other three files carry none of those. +- The flow YAML is the spine — it binds a state to its dispatched agent, procedure, artifacts, branch, gate, and exits; the other three files carry none of those. - The orchestrator routes; agents, skills, and knowledge are loaded on demand, never the whole layer at once. - A state's `description` orients — one or two lines on what the state is for; the step-by-step procedure, criteria lists, and technique live in the skill. When a `description` and a skill disagree on procedure, the skill wins. - An escalation handoff rides a per-session journal: the discovering state appends its finding, the receiver reads it on re-entry, and the re-dispatch prompt carries it live. The tests and cassettes stay the spec; the journal is only the safety net against lost context mid-escalation. diff --git a/.opencode/knowledge/workflow/flowr-operations.md b/.opencode/knowledge/workflow/flowr-operations.md index c443f652..b87fa392 100644 --- a/.opencode/knowledge/workflow/flowr-operations.md +++ b/.opencode/knowledge/workflow/flowr-operations.md @@ -9,7 +9,7 @@ last-updated: 2026-07-02 ## Key Takeaways - flowr is a non-deterministic state machine **specification** — a YAML file declares structure (states, transitions, guards), not behaviour; flowr never runs the work, it routes (nullhack/flowr, 2026). -- Drive one state at a time: `check` reads the current state's attrs; the orchestrator dispatches the owner named in `dispatch_to`; the owner asserts evidence; `transition` advances. This is the whole loop. +- Drive one state at a time: `check` reads the current state's attrs; the orchestrator dispatches the agent named in `dispatch_to`; that agent asserts evidence; `transition` advances. This is the whole loop. - A state with `flow:`/`flow-version:` is a **subflow pointer**: entry pushes a stack frame, exit pops it; the parent's `next` key must match the child's exit name; `session init` auto-enters the first subflow. - Escalations re-enter the target subflow at its **first state** — flowr keeps no position memory — so `build → plan` on a contract gap re-runs plan from `author-test-stubs`, and `plan/explore → discover` re-runs the interview funnel from the top. - A guarded transition fires only when its condition group is satisfied; the orchestrator asserts evidence with `--evidence key=value` (one per condition key). flowr **collects asserted evidence, it does not run checks** — CI is the enforcement backstop per [[methodology/separation-of-concerns#evidence-vs-enforcement]]. @@ -19,7 +19,7 @@ last-updated: 2026-07-02 **Specification, not engine.** A flow file declares the graph: states with attributes, transitions with optional guards, exits. flowr validates the graph (seven MUST checks at load — every `next` resolves, no ambiguous targets, parent `next` keys match child `exits`, no cross-flow cycles, exits referenced, named conditions resolve, defaulted params supplied), queries it (`check`, `next`), and advances it (`transition`). It has no opinions about retries, timeouts, or error handling, and it never executes the dispatched work — that is the external agent's job (nullhack/flowr, 2026). -**The state-reading loop.** The orchestrator never improvises routing. At each step it runs `check` to read the current state's attrs — `dispatch_to` (the one owner), `skills` (the procedures), `input artifacts` (what must be on disk), `output artifacts` (what may be written), `git branch`, and `conditions` (any guarded transitions). It verifies the inputs exist, dispatches the owner with the skill paths and inputs, then asserts the owner's evidence to fire the next `transition`. One state, one dispatch. +**The state-reading loop.** The orchestrator never improvises routing. At each step it runs `check` to read the current state's attrs — `dispatch_to` (the one dispatched agent), `skills` (the procedures), `input artifacts` (what must be on disk), `output artifacts` (what may be written), `git branch`, and `conditions` (any guarded transitions). It verifies the inputs exist, dispatches that agent with the skill paths and inputs, then asserts that agent's evidence to fire the next `transition`. One state, one dispatch. **Subflows and the call stack.** A state carrying `flow:` is a pointer into a child flow; entering it pushes a frame `({parent_flow, parent_state})` onto a stack and sets the session to the child's first state. When a transition's target is one of the child's exit names AND the stack is non-empty, flowr pops the frame, restores the parent, and follows the parent state's transition for that exit name — which may itself enter the next subflow. This is how `pipeline-flow` chains discover → explore → plan → build → deliver → shipped through five subflows. @@ -27,7 +27,7 @@ last-updated: 2026-07-02 **Conditions and evidence.** A `next` entry shaped `{to: , when: }` is guarded; the named group lives under the state's `conditions:` block, a map of `{key: expression}` (operators `== != >= <= > <`, plain value = `==`). The orchestrator fires the transition by passing `--evidence key=value` for each key. flowr evaluates the assertion; it does not verify the claim is true — that is CI's job. The evidence keys the temple8 flows use are listed in `AGENTS.md`. -**attrs is free-form.** flowr treats `state.attrs` as an opaque dict; the keys `dispatch_to` / `skills` / `input artifacts` / `output artifacts` / `git branch` / `specialists` / `conditions` are this project's convention for binding a state to an owner, a procedure, artifacts, and a branch. None are enforced by the engine — they are read by the orchestrator and the agents. Renaming a key changes the convention, not the spec. +**attrs is free-form.** flowr treats `state.attrs` as an opaque dict; the keys `dispatch_to` / `skills` / `input artifacts` / `output artifacts` / `git branch` / `specialists` / `conditions` are this project's convention for binding a state to a dispatched agent, a procedure, artifacts, and a branch. None are enforced by the engine — they are read by the orchestrator and the agents. Renaming a key changes the convention, not the spec. ## Content @@ -54,8 +54,8 @@ Sessions live at `.cache/sessions/.yaml` (gitignored). `--flows-dir` overrid 1. `check --session ` → parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. 2. Verify every `input artifacts` path exists on disk — missing = stop, do not assume (Golden Rule). -3. Dispatch the `dispatch_to` owner as a subagent, with the `skills` paths (`.opencode/skills//SKILL.md`, listed order = execution order) and the input artifacts. The owner writes only to `output artifacts`. -4. The owner returns asserted evidence (e.g. `stubtest-clean=true`). +3. Dispatch the agent named in `dispatch_to` as a subagent, with the `skills` paths (`.opencode/skills//SKILL.md`, listed order = execution order) and the input artifacts. The dispatched agent writes only to `output artifacts`. +4. The dispatched agent returns asserted evidence (e.g. `stubtest-clean=true`). 5. `transition --session --evidence k=v …` fires the guarded advance; `next --session ` previews open/blocked if unsure. 6. Repeat from 1 at the new state. One state = one dispatch. @@ -119,6 +119,6 @@ for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done ## Related - [[methodology/separation-of-concerns#evidence-vs-enforcement]] — why flowr collects asserted evidence and CI enforces -- [[methodology/agent-files]] — what `dispatch_to` resolves to (the owner identity) +- [[methodology/agent-files]] — what `dispatch_to` resolves to (the dispatched agent's identity) - [[methodology/skill-files]] — what `skills` resolves to (the per-state procedure) -- [[methodology/knowledge-files]] — how the owner's loaded knowledge is cited +- [[methodology/knowledge-files]] — how the dispatched agent's loaded knowledge is cited diff --git a/AGENTS.md b/AGENTS.md index cb28c295..a5341467 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,9 +7,9 @@ through flowr. ## Operating discipline 1. **flowr is the single router.** Every state change runs through flowr — no improvised routing, no skipping states. -2. **The owner does the work.** Each state names one owner in `dispatch_to`; the orchestrator dispatches it, and the owner produces the artifacts and asserts the evidence. The orchestrator never authors the work. +2. **The dispatched agent does the work.** Each state names one agent in `dispatch_to`; the orchestrator dispatches it, and that agent produces the artifacts and asserts the evidence. The orchestrator never authors the work. 3. **The state's contract is binding.** Read every `input artifact` before starting — missing means stop, not assume. Write only to `output artifacts`. -4. **Assert only verified evidence; CI is the backstop.** A gate fires on the owner's asserted evidence; assert nothing you did not check — CI catches the lie (`ruff` / `pyright` / `mypy.stubtest` / `pytest`). +4. **Assert only verified evidence; CI is the backstop.** A gate fires on the dispatched agent's asserted evidence; assert nothing you did not check — CI catches the lie (`ruff` / `pyright` / `mypy.stubtest` / `pytest`). 5. **Branch discipline.** Match the state's `git branch`; merge `feature` → `dev` only under the whole-suite gates. No dangling branches. 6. **Every requirement traced.** Each interview finding maps to a test or an explicit deferral; an untraced requirement is a gap the simulate gate rejects. @@ -22,7 +22,7 @@ transition. 1. **Read** — `flowr check --session `; parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. 2. **Verify inputs** — every `input artifact` exists on disk. Missing = stop (discipline 3). -3. **Dispatch** — call the `dispatch_to` owner with the `skills` paths (`.opencode/skills//SKILL.md`) and the input artifacts. The owner writes only to `output artifacts` and returns asserted evidence. +3. **Dispatch** — call the agent named in `dispatch_to` with the `skills` paths (`.opencode/skills//SKILL.md`) and the input artifacts. The dispatched agent writes only to `output artifacts` and returns asserted evidence. 4. **Verify outputs + evidence** — the `output artifacts` were produced and the transition's `conditions` evidence is real (discipline 4). 5. **Transition** — `flowr transition --session --evidence k=v …`, then regenerate the todo from the next state's `check`. @@ -109,7 +109,7 @@ Discover rather than enumerate: ls .opencode/skills/ find .opencode/knowledge -name '*.md' -The flow binds each state to its owner (`dispatch_to`), procedure (`skills`), +The flow binds each state to its dispatched agent (`dispatch_to`), procedure (`skills`), and artifacts (`input artifacts` / `output artifacts`); agents, skills, and knowledge stay single-concern and free of routing. Wikilinks cite knowledge on demand: `[[domain/concept]]` resolves to `.opencode/knowledge/{domain}/{concept}.md`, From 7aaa32950f38fc60c7d136ac7c24ad85cf926a62 Mon Sep 17 00:00:00 2001 From: nullhack Date: Fri, 3 Jul 2026 14:09:22 -0400 Subject: [PATCH 21/28] docs(methodology): clarify guarded vs unguarded flowr gates Rule #4 and driving-step-4 previously implied a flowr gate fires on every transition; discovery/explore are intentionally unguarded (gate = output-artifact verification + stakeholder approval). Wording now distinguishes the two. AGENTS.md only -- no flow YAML or Python. --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a5341467..d94718f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ through flowr. 1. **flowr is the single router.** Every state change runs through flowr — no improvised routing, no skipping states. 2. **The dispatched agent does the work.** Each state names one agent in `dispatch_to`; the orchestrator dispatches it, and that agent produces the artifacts and asserts the evidence. The orchestrator never authors the work. 3. **The state's contract is binding.** Read every `input artifact` before starting — missing means stop, not assume. Write only to `output artifacts`. -4. **Assert only verified evidence; CI is the backstop.** A gate fires on the dispatched agent's asserted evidence; assert nothing you did not check — CI catches the lie (`ruff` / `pyright` / `mypy.stubtest` / `pytest`). +4. **Assert only verified evidence; CI is the backstop.** On a **guarded** transition flowr fires only on the dispatched agent's asserted evidence (`--evidence k=v`); assert nothing you did not check — CI catches the lie (`ruff` / `pyright` / `mypy.stubtest` / `pytest`). **Unguarded** transitions (discovery, explore) carry no flowr gate — the orchestrator verifies the output artifacts and the stakeholder's approval IS the gate. 5. **Branch discipline.** Match the state's `git branch`; merge `feature` → `dev` only under the whole-suite gates. No dangling branches. 6. **Every requirement traced.** Each interview finding maps to a test or an explicit deferral; an untraced requirement is a gap the simulate gate rejects. @@ -23,7 +23,7 @@ transition. 1. **Read** — `flowr check --session `; parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. 2. **Verify inputs** — every `input artifact` exists on disk. Missing = stop (discipline 3). 3. **Dispatch** — call the agent named in `dispatch_to` with the `skills` paths (`.opencode/skills//SKILL.md`) and the input artifacts. The dispatched agent writes only to `output artifacts` and returns asserted evidence. -4. **Verify outputs + evidence** — the `output artifacts` were produced and the transition's `conditions` evidence is real (discipline 4). +4. **Verify outputs + evidence** — the `output artifacts` were produced; if the transition is guarded, its `conditions` evidence is real (discipline 4). 5. **Transition** — `flowr transition --session --evidence k=v …`, then regenerate the todo from the next state's `check`. Routing is one flow with five subflows: `pipeline-flow` → discovery → explore → From 05bbd8a70323fc2d1a922c1d7af83782d2e00f33 Mon Sep 17 00:00:00 2001 From: nullhack Date: Fri, 3 Jul 2026 14:16:20 -0400 Subject: [PATCH 22/28] docs(methodology): mandate glossary template in consolidate-interview skill Step 4 now renders docs/glossary.md from .templates/docs/glossary.md.template (substitute ; one ## Context section per bounded context; one ### per term in the template's A that <...> + *Aliases . Source* format). Prevents freehand authoring; mirrors src-disaster-report-v4. --- .opencode/skills/consolidate-interview/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.opencode/skills/consolidate-interview/SKILL.md b/.opencode/skills/consolidate-interview/SKILL.md index a95dad82..50d32029 100644 --- a/.opencode/skills/consolidate-interview/SKILL.md +++ b/.opencode/skills/consolidate-interview/SKILL.md @@ -8,5 +8,5 @@ description: "End of session — replace running notes with the full synthesis a 1. Load [[requirements/ubiquitous-language]] — term extraction for the glossary. This level synthesises (Active Listening L3, applied in step 3); it does not probe. 2. Read the running interview-notes across all three levels. 3. Apply Active Listening L3: replace the running notes with the full synthesis across all three funnel levels and present it to the stakeholder for approval. The summary reflects what the stakeholder said — no new framing or topic labels. -4. Author and refine the glossary of ubiquitous language from the stakeholder's own terms so it leads all subsequent naming per [[requirements/ubiquitous-language]]. +4. Render `docs/glossary.md` from `.templates/docs/glossary.md.template` (substitute ``): one `## Context: ` section per context, one `### ` entry per term in the template's format (`A that .` + `*Aliases: … · Source: …*`), from the stakeholder's own terms, so it leads all subsequent naming per [[requirements/ubiquitous-language]]. 5. Exit interview-ready when the stakeholder approves; re-enter the funnel at general whenever plan or build finds the elicitation itself was insufficient. From 41095ffad62762920a8b4a7e639947aa313018bf Mon Sep 17 00:00:00 2001 From: nullhack Date: Sat, 4 Jul 2026 12:49:35 -0400 Subject: [PATCH 23/28] docs: rename AGENTS.md 'Operating discipline' to 'Binding constraints' Adopt the 'binding constraints' jargon (the term that sticks in conversation) as the section name for the AGENTS.md contract, formerly 'Operating discipline' (conceptually the old 'Golden Rules'). Updated all live cross-references: README, README.md.jinja, copier.yml intro, and the flowr-operations / nullhack_flowr research cards. Historical .backup/ snapshots and the unrelated design-doc 'golden ratio' are left untouched. --- .opencode/knowledge/workflow/flowr-operations.md | 2 +- AGENTS.md | 6 +++--- README.md | 4 ++-- README.md.jinja | 2 +- copier.yml | 2 +- .../software-engineering/process/nullhack_flowr_1.0.0.md | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.opencode/knowledge/workflow/flowr-operations.md b/.opencode/knowledge/workflow/flowr-operations.md index b87fa392..69cd0695 100644 --- a/.opencode/knowledge/workflow/flowr-operations.md +++ b/.opencode/knowledge/workflow/flowr-operations.md @@ -53,7 +53,7 @@ Sessions live at `.cache/sessions/.yaml` (gitignored). `--flows-dir` overrid ### The state-driving protocol 1. `check --session ` → parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. -2. Verify every `input artifacts` path exists on disk — missing = stop, do not assume (Golden Rule). +2. Verify every `input artifacts` path exists on disk — missing = stop, do not assume (binding constraint 3). 3. Dispatch the agent named in `dispatch_to` as a subagent, with the `skills` paths (`.opencode/skills//SKILL.md`, listed order = execution order) and the input artifacts. The dispatched agent writes only to `output artifacts`. 4. The dispatched agent returns asserted evidence (e.g. `stubtest-clean=true`). 5. `transition --session --evidence k=v …` fires the guarded advance; `next --session ` previews open/blocked if unsure. diff --git a/AGENTS.md b/AGENTS.md index d94718f7..35e4f72a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ A Python project with the staged-contract workflow wired in (flow set, agents/skills/knowledge, CI, tooling). Drive the pipeline one state at a time through flowr. -## Operating discipline +## Binding constraints 1. **flowr is the single router.** Every state change runs through flowr — no improvised routing, no skipping states. 2. **The dispatched agent does the work.** Each state names one agent in `dispatch_to`; the orchestrator dispatches it, and that agent produces the artifacts and asserts the evidence. The orchestrator never authors the work. @@ -21,9 +21,9 @@ outside the loop is untracked. One state per todo; regenerate on every transition. 1. **Read** — `flowr check --session `; parse `dispatch_to`, `skills`, `input artifacts`, `output artifacts`, `git branch`, `conditions`. -2. **Verify inputs** — every `input artifact` exists on disk. Missing = stop (discipline 3). +2. **Verify inputs** — every `input artifact` exists on disk. Missing = stop (binding constraint 3). 3. **Dispatch** — call the agent named in `dispatch_to` with the `skills` paths (`.opencode/skills//SKILL.md`) and the input artifacts. The dispatched agent writes only to `output artifacts` and returns asserted evidence. -4. **Verify outputs + evidence** — the `output artifacts` were produced; if the transition is guarded, its `conditions` evidence is real (discipline 4). +4. **Verify outputs + evidence** — the `output artifacts` were produced; if the transition is guarded, its `conditions` evidence is real (binding constraint 4). 5. **Transition** — `flowr transition --session --evidence k=v …`, then regenerate the todo from the next state's `check`. Routing is one flow with five subflows: `pipeline-flow` → discovery → explore → diff --git a/README.md b/README.md index a033322c..a4ac1557 100644 --- a/README.md +++ b/README.md @@ -74,5 +74,5 @@ knowledge + asset templates (for projects with a UI surface) and `docs/research/ ## Workflow The staged-contract pipeline runs discover → explore → plan → build → deliver → -shipped, driven one state at a time through flowr. See `AGENTS.md` for the full -operating discipline, the driving loop, and the flowr commands. +shipped, driven one state at a time through flowr. See `AGENTS.md` for the +binding constraints, the driving loop, and the flowr commands. diff --git a/README.md.jinja b/README.md.jinja index e52cdc5d..20c7ecf8 100644 --- a/README.md.jinja +++ b/README.md.jinja @@ -46,5 +46,5 @@ Full threat model in the `secrets-and-config` knowledge. The staged-contract pipeline runs discover → explore → plan → build → deliver → shipped, one state at a time through flowr. Tests are the source of truth for -behaviour. See `AGENTS.md` for the operating discipline, the driving loop, and +behaviour. See `AGENTS.md` for the binding constraints, the driving loop, and the flowr commands. diff --git a/copier.yml b/copier.yml index f2a6c3b0..d7544a4b 100644 --- a/copier.yml +++ b/copier.yml @@ -97,4 +97,4 @@ _message_after_copy: | 2. uv sync --extra dev 3. uv run python -m flowr session init pipeline-flow --name default - Drive the pipeline one state at a time. See AGENTS.md for the operating discipline. + Drive the pipeline one state at a time. See AGENTS.md for the binding constraints. diff --git a/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md b/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md index 13cd7954..30535a56 100644 --- a/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md +++ b/docs/research/software-engineering/process/nullhack_flowr_1.0.0.md @@ -30,7 +30,7 @@ flowr 1.0.0 is the first stable release of a non-deterministic state machine spe flowr defines what a workflow IS, not what it DOES. A YAML file declares structure; a validator checks integrity; tools query, track, and visualise. Because the format is precisely defined, validators/editors/visualisers/session-trackers interoperate across any conforming project. The non-determinism is in the routing: a state may declare several `next` transitions, and the orchestrator (an external agent) decides which to fire by asserting evidence against the guarded conditions — flowr never executes the work itself. ## Relevance -flowr is the workflow engine that powers temple8's staged-contract pipeline. This card grounds the `workflow/flowr-operations` knowledge: the session model, the subflow call-stack, the conditions/evidence model, the validation rules, and the CLI surface that the orchestrator drives one state at a time. The "golden rules" of the operating discipline (no skip state, no bypass dispatch, evidence-based transitions) are direct consequences of this specification. +flowr is the workflow engine that powers temple8's staged-contract pipeline. This card grounds the `workflow/flowr-operations` knowledge: the session model, the subflow call-stack, the conditions/evidence model, the validation rules, and the CLI surface that the orchestrator drives one state at a time. The "binding constraints" (no skip state, no bypass dispatch, evidence-based transitions) are direct consequences of this specification. ## Related Research Connects to finite state machine theory (Harel, 1987) and workflow management patterns (Russell et al., 2006). From 84af0774746f211dc9f0dc1f8fd3c9175b7cafc9 Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 7 Jul 2026 03:27:51 -0400 Subject: [PATCH 24/28] =?UTF-8?q?feat(template):=20dogfood=20fixes=20?= =?UTF-8?q?=E2=80=94=20data-model=20state,=20gate=20rigor,=20simplicity,?= =?UTF-8?q?=20replay=20rule,=20journal=20template?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five dogfood issues fixed (Issues 1–5) plus a journal template to remove first-pass deliberation. Issue 5 — model-data-schema state (new contract surface): - plan-flow v1.6.0: new state at plan entry (dispatch_to: data-architect) producing data-model.md; wired as input to author-test-stubs, review-test-stubs, write-test-py, derive-source-stubs, simulate-contracts - new skill model-data-schema/SKILL.md, knowledge architecture/data-modeling.md (schema-as-contract, OLTP/OLAP, anti-patterns) - removes the dimensional-model deferral escape hatch Issue 2 — vacuous-assertion gate: - review-test-stubs: new step naming the smells (hasattr-only, no-op helper, lower-bound-only, constant-satisfiable, tautology) - plan-flow: new evidence key vacuous-assertion-free - test-design.md: Vacuous assertions subsection; smell-catalogue cross-link Issue 3 — simulate-contracts as compiler, not ceremony: - simulate-contracts/SKILL.md rewritten: prescribed per-hop loop (walk → journal at the hop → spec cross-check → name gap), spec-diff step, build-implied gaps output class; framed as a compiler that simulates how the real app runs to disprove or confirm before source .py exists - spec-simulation.md: Build-implied gaps + Spec-diff sections - plan-flow: new evidence key spec-diff-clean Issue 4 — simplicity discipline (neither over- nor under-engineer): - new knowledge methodology/simplicity-discipline.md with anti-pattern catalogue (premature abstraction, speculative config, duplicate concept, seam-without-reason, speculative field, speculative building block) - three interview skills: simplicity question at each funnel level - consolidate-interview: drop speculative items (grounded-or-removed) - review-test-stubs: scope-minimal check (inverted traceability); plan-flow: new evidence key scope-minimal Issue 1 — vcr.use_cassette rule for external-boundary adapters: - author-test-stubs: httpx adapters MUST use vcr.use_cassette(); pytester reserved for CLI subprocess tests; library-boundary exception uses monkeypatch - external-fixtures.md: Replay mechanism subsection with wrong-vs-right counterexample; test-stubs.md cross-link Journal template — .templates/cache/journal.md.template: - three sections matching the three writer triggers (build-phase escalations, capture gaps, simulation walk); header explains first-pass emptiness - model-data-schema/SKILL.md: bootstrap step renders the journal if missing (removes the first-pass deliberation trigger) - author-test-stubs, write-test-py, derive-source-stubs: guard cleanup — journal is always present, bootstrapped at plan entry Verified: flowr validate plan-flow passes; task lint clean; all 221 wikilinks resolve (6 pre-existing illustrative placeholders untouched). --- .flowr/flows/plan-flow.yaml | 41 +++++++++- .../knowledge/architecture/data-modeling.md | 74 +++++++++++++++++++ .../methodology/simplicity-discipline.md | 74 +++++++++++++++++++ .../knowledge/requirements/spec-simulation.md | 42 +++++++++-- .../software-craft/external-fixtures.md | 31 ++++++++ .../software-craft/smell-catalogue.md | 1 + .../knowledge/software-craft/test-design.md | 15 ++++ .../knowledge/software-craft/test-stubs.md | 2 +- .opencode/skills/author-test-stubs/SKILL.md | 13 ++-- .../skills/consolidate-interview/SKILL.md | 7 +- .opencode/skills/derive-source-stubs/SKILL.md | 2 +- .../skills/interview-building-blocks/SKILL.md | 5 +- .../skills/interview-cross-cutting/SKILL.md | 5 +- .opencode/skills/interview-general/SKILL.md | 5 +- .opencode/skills/model-data-schema/SKILL.md | 23 ++++++ .opencode/skills/review-test-stubs/SKILL.md | 14 +++- .opencode/skills/simulate-contracts/SKILL.md | 33 ++++++--- .opencode/skills/write-test-py/SKILL.md | 2 +- .templates/cache/journal.md.template | 45 +++++++++++ 19 files changed, 392 insertions(+), 42 deletions(-) create mode 100644 .opencode/knowledge/architecture/data-modeling.md create mode 100644 .opencode/knowledge/methodology/simplicity-discipline.md create mode 100644 .opencode/skills/model-data-schema/SKILL.md create mode 100644 .templates/cache/journal.md.template diff --git a/.flowr/flows/plan-flow.yaml b/.flowr/flows/plan-flow.yaml index ca2b3724..1a5cd4ed 100644 --- a/.flowr/flows/plan-flow.yaml +++ b/.flowr/flows/plan-flow.yaml @@ -1,15 +1,39 @@ flow: plan-flow -version: 1.5.0 +version: 1.6.0 exits: - contracts-ready - needs-capture - needs-elicitation states: + - id: model-data-schema + attrs: + description: > + Author the persistence schema as a binding contract before any test + stub is written. The data-architect reads the captured external shapes + and the interview, classifies the workload (OLTP/OLAP/hybrid), and + models tables, indexes, constraints, and expected query patterns + optimised for the common operations. The model is the contract the + build-phase developer implements against - not a deferral. + dispatch_to: data-architect + specialists: [integration-engineer, domain-expert, security-engineer] + git branch: dev + skills: [model-data-schema] + input artifacts: + - ".cache//interview-notes.md" + - "docs/glossary.md" + - "tests/cassettes/**" + - ".cache//external-contracts.md" + - ".cache//journal.md" + output artifacts: + - ".cache//data-model.md" + next: + data-modeled: author-test-stubs + - id: author-test-stubs attrs: description: > - Author the test .pyi (integration + E2E only) from the interview and - captured reality - the first contract surface. + Author the test .pyi (integration + E2E only) from the interview, + captured reality, and the modeled schema - the first contract surface. dispatch_to: test-architect specialists: [integration-engineer, data-architect, ux-engineer, domain-expert, security-engineer] git branch: dev @@ -19,6 +43,7 @@ states: - "docs/glossary.md" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//data-model.md" - ".cache//journal.md" output artifacts: - "tests/integration/**/*_test.pyi" @@ -31,7 +56,8 @@ states: attrs: description: > Gate. Review the test stubs for consistency, scope (integration/E2E - only), and happy-path completeness against the interview. + only), happy-path completeness, vacuous-assertion freedom, and + finding-grounded scope against the interview and the modeled schema. dispatch_to: reviewer git branch: dev skills: [review-test-stubs] @@ -40,6 +66,7 @@ states: - "docs/glossary.md" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//data-model.md" - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" output artifacts: [] @@ -48,6 +75,8 @@ states: interview-consistent: "==true" scope-integration-e2e-only: "==true" happy-paths-complete: "==true" + vacuous-assertion-free: "==true" + scope-minimal: "==true" next: accepted: to: write-test-py @@ -68,6 +97,7 @@ states: - "tests/e2e/**/*_test.pyi" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//data-model.md" - ".cache//journal.md" output artifacts: - "tests/integration/**/*_test.py" @@ -87,6 +117,7 @@ states: input artifacts: - "tests/integration/**/*_test.py" - "tests/e2e/**/*_test.py" + - ".cache//data-model.md" - ".cache//journal.md" output artifacts: - "/**/*.pyi" @@ -106,6 +137,7 @@ states: - "docs/glossary.md" - "tests/cassettes/**" - ".cache//external-contracts.md" + - ".cache//data-model.md" - "tests/integration/**/*_test.pyi" - "tests/e2e/**/*_test.pyi" - "/**/*.pyi" @@ -121,6 +153,7 @@ states: test-stubs-consistent: "==true" lint-clean: "==true" simulation-passed: "==true" + spec-diff-clean: "==true" next: accepted: to: contracts-ready diff --git a/.opencode/knowledge/architecture/data-modeling.md b/.opencode/knowledge/architecture/data-modeling.md new file mode 100644 index 00000000..b3cf8bb6 --- /dev/null +++ b/.opencode/knowledge/architecture/data-modeling.md @@ -0,0 +1,74 @@ +--- +domain: architecture +tags: [data-modeling, oltp, olap, schema-as-contract, workload-driven, access-patterns] +last-updated: 2026-07-07 +--- + +# Data Modeling + +## Key Takeaways + +- The schema is a **binding contract**, authored by the data-architect from captured external shapes and the interview **before** any test stub is written. The build-phase developer implements against the model; they do not invent it. A schema deferred to build is the bug, not the workflow. +- **Access patterns decide schema.** Name the workload (OLTP / OLAP / hybrid) before naming a table — the right shape for one is malpractice for the other, and a "general-purpose" schema optimises for nothing. +- **Workload-driven normalization.** Normalize for OLTP (write integrity, per-row access); denormalize for OLAP only against a measured, named query pattern that pays for it. Normalization is a trade-off against an access pattern, never a virtue. +- **The model is grounded in captures, not guesses.** Every field traces to a captured external shape (cassette / `external-contracts.md`) or an interview finding. A field with no trace is speculative (drop) or a missing capture (route to explore), never a guess. +- **Integrity lives in constraints.** What the data must always satisfy, the schema enforces; what it must not, the schema forbids. An index without the query that justifies it, a constraint the spec does not require — both are rejected. +- The model is **upstream of the test contracts** (`author-test-stubs`, `review-test-stubs`, `write-test-py`, `simulate-contracts` all read `data-model.md` as a binding input); a contract whose persistence shapes disagree with the model is rejected at `simulate-contracts`. + +## Concepts + +**The schema is a contract, not a deferral.** When the model is left to the build phase, the developer mirrors the code's class shapes into tables — producing schemas optimised for nothing the system actually does. The fix is structural: a state in the plan subflow (`model-data-schema`) dispatches the data-architect to author `data-model.md` from the captured external shapes and the interview, before any test stub exists. The contracts downstream reference the modeled schema; the developer implements against it. The data-architect's standing refusal — "a schema without the queries that justify it, an index without the access pattern that pays for it" (`data-architect.md`) — is the rule this state exists to enforce, at the moment the inputs that satisfy it (captures, interview) are available. + +**Access patterns decide schema.** OLTP and OLAP answer different questions. An OLTP workload (ingest-heavy, append-only, point reads) wants normalized tables, write integrity in constraints, and indexes on the keys the per-row reads use. An OLAP workload (read-heavy analytics, aggregations, filters on named dimensions) wants dimensions modeled explicitly and pre-aggregation where a named query pays for the storage cost. A "hybrid" workload is not a fudge — it is two named access paths reconciled by an explicit trade-off (often a normalized write path feeding a denormalized read projection). The data-architect names the workload and the queries before any table is named; the workload is the load-bearing decision, recorded with cited evidence from the interview or the captures. + +**Workload-driven normalization.** Third-normal form is the OLTP default because it preserves write integrity and answers point reads cheaply. Denormalization is a trade-off, taken only against a measured, named access pattern: a query that joins several tables at read-time and pays for it at scale, and which a denormalized projection would serve cheaper. A denormalization with no query behind it is premature; a normalization level beyond what the workload needs is structure the system does not require. Either is rejected at `model-data-schema`, not deferred to build. + +**Grounded in captures, not guesses.** The captured external shapes (cassettes + `external-contracts.md`) are the truth about what the system must persist and consume; the interview is the truth about why. A field in the model with no trace to either is a guess — and a guess baked into the schema becomes a load-bearing lie the build cannot challenge. A field the model needs but no capture covers is a missing capture, routed back to explore (`needs-capture`), never invented. The rule mirrors the cassette rule for adapter tests ([[software-craft/external-fixtures]]): the capture is the truth; never hand-edit it to make the code pass, and never invent a schema shape to make the code convenient. + +**Integrity in constraints.** The data-architect's principle (`data-architect.md`): what the data must always satisfy, the schema enforces; what it must not, the schema forbids. A `NOT NULL` constraint is the contract that the column always carries a value; a `UNIQUE` constraint is the contract that two rows never share it; a `CHECK` is the contract on the value's domain; a `FOREIGN KEY` is the contract that the referenced row exists. Each is a rule the spec requires, recorded as a constraint the schema enforces — not a hope the application code honours. A constraint the spec does not require is over-engineering; a rule the spec requires but the schema does not enforce is a gap. + +**Upstream of the test contracts.** The `data-model.md` artifact is an input to `author-test-stubs`, `review-test-stubs`, `write-test-py`, `derive-source-stubs`, and `simulate-contracts` — every state that authors or gates a persistence-adjacent contract reads the model. A test stub whose persistence shapes disagree with the model is incoherent, rejected at `simulate-contracts` with the disagreement cited (which table, which column, which shape the test asserts vs which the model declares). The model is the canonical persistence shape, the way the cassette is the canonical external shape. + +## Content + +### Workload classification + +| Workload | Signal | Schema shape | Normalization | +|---|---|---|---| +| OLTP | ingest-heavy, append-only, per-row point reads/writes | normalized tables, integrity in constraints, indexes on read keys | 3NF default | +| OLAP | read-heavy analytics, aggregations, filters on named dimensions | dimensions modeled explicitly, pre-aggregation where a named query pays | denormalized read projections, fed from a normalized write path | +| Hybrid | both access patterns are cited in the interview | two named paths reconciled by an explicit trade-off (often normalized write + denormalized read projection) | normalization per path, recorded | + +A workload classification with no cited evidence is rejected — it is a guess, and the schema shape follows from it. + +### Schema-as-contract — what the model declares + +`data-model.md` records, per table: + +- **purpose** — one line, traced to an interview finding; +- **columns** — name, type, and the constraint that holds (`NOT NULL`, `UNIQUE`, `CHECK`, `FK target`); +- **indexes** — paired with the named query pattern that justifies each; +- **OLTP/OLAP/hybrid verdict** — from the workload classification, with the access patterns the shape optimises for; +- **field traces** — every field traced to a captured external shape or an interview finding. + +The build-phase developer implements exactly this model — no tables added, no columns invented, no indexes beyond those the model names. A deviation is a contract break, routed back to plan. + +### Anti-patterns + +| Anti-pattern | What it looks like | Why it's rejected | +|---|---|---| +| Mirroring a code-class shape into a table | a `User` class with a `profile: Profile` becomes a `users` table with a JSON `profile` blob | the access pattern is the spec for the schema, not the class layout; a blob defeats query integrity and index use | +| Premature denormalization | a `rates` table pre-joined to `currencies` "for performance" with no named query | denormalization is a trade-off against a measured access pattern, never a default | +| An index without a query | `CREATE INDEX idx_x ON t (x)` because "we'll probably query on x" | an index costs writes; only a named query pattern that pays for it justifies it | +| A constraint the spec does not require | `CHECK (status IN ('A','B'))` when the spec names no status enum | over-engineering; integrity is enforced for what the spec requires, not what it might | +| Speculative field | a column with no consumer in any cited access pattern or interview finding | YAGNI; the model serves the cited workload, not a future that may not arrive | +| Invented shape | a column type or constraint that no capture and no finding justifies | the model is grounded in captures and the interview; a guess baked into the schema is a load-bearing lie | + +Each is rejected at `model-data-schema` with the offending element cited; the model is the smallest schema that serves the cited access patterns, per [[methodology/simplicity-discipline]]. + +## Related + +- [[software-craft/external-fixtures]] — the captured external shapes the model is grounded in; the cassette is the truth for adapter tests the way the model is the truth for persistence contracts +- [[methodology/simplicity-discipline]] — the smallest schema that serves the cited access patterns; speculative structure is dropped here, not deferred +- [[requirements/spec-simulation]] — `simulate-contracts` rejects a contract set whose persistence shapes disagree with the model +- `.opencode/agents/data-architect.md` — the agent's standing refusals (no schema without queries, no index without an access pattern) are the rule this state enforces diff --git a/.opencode/knowledge/methodology/simplicity-discipline.md b/.opencode/knowledge/methodology/simplicity-discipline.md new file mode 100644 index 00000000..ec9b74c0 --- /dev/null +++ b/.opencode/knowledge/methodology/simplicity-discipline.md @@ -0,0 +1,74 @@ +--- +domain: methodology +tags: [simplicity, kiss, yagni, scope-discipline, anti-patterns, traced-requirement] +last-updated: 2026-07-07 +--- + +# Simplicity Discipline + +## Key Takeaways + +- Simplicity is a **traced requirement, not an aspiration**. Every abstraction, seam, configurability, and building block in the contracts is either grounded in a cited stakeholder need or removed at consolidation. "Might need it later" is not a need. +- **Neither over- nor under-engineer.** Over-engineering is structure beyond the finding (a speculative abstraction); under-engineering is a missing structure the cited need requires (a gap that will surface as a hop break or a build-implied gap at `simulate-contracts`). The discipline cuts both ways: every cited need gets exactly the structure it requires, no more, no less. +- **YAGNI is the default; KISS is the shape.** You build the thing the spec requires and you build it in the simplest shape that serves the cited access pattern. A speculative abstraction is rejected; a missing abstraction the workload demands is a gap. +- The simplicity check is **applied at every gate that authors structure**: the three interview funnels (drop speculative items before they reach the contracts), `consolidate-interview` (grounded in a cited need or removed), `author-test-stubs` (no test expresses structure beyond its finding), `review-test-stubs` (the scope-minimal, inverted-traceability check), `model-data-schema` (the smallest schema that serves the cited access patterns), and `simulate-contracts` (build-implied gaps include under-determined behaviour from speculative or missing structure). +- The anti-pattern catalogue names the smells: **premature abstraction, speculative configurability, duplicate concept, seam-without-a-reason, speculative field, speculative building block**. Each is grounded-or-dropped at the earliest gate that sees it. + +## Concepts + +**Traced requirement, not aspiration.** A requirement is traced when it cites a stakeholder need recorded in `interview-notes.md` — a concrete incident (CIT), a writable constraint (Laddering), a named access pattern. A structure is justified when removing it would leave a cited need unmet; it is speculative when no cited need requires it. The rule is symmetric: a structure the cited need does not require is over-engineering (drop it); a structure the cited need does require but the contracts omit is under-engineering (a gap, not simplicity). The discipline is not "build less" — it is "build exactly what the cited need requires, in the simplest shape that serves it." + +**Why YAGNI is the default.** A speculative abstraction — a seam, a configurability, a building block — is paid for twice: once when authored into the contracts (test surface, source stub, schema, glossary term), and again when implemented and maintained. The future it was bought against rarely arrives in the shape predicted, so the abstraction either fights the real requirement or is silently bypassed. The cost is not only the code; it is the surface area the gate trio (`review-test-stubs`, `simulate-contracts`) must police, and the ambiguity a speculative seam introduces into the simulation (two impls, one matching the spec and one matching the seam, both passing). Dropping the speculative structure at the interview shrinks the contract surface before the gates run. + +**Why KISS is the shape, not the ceiling.** "Build the simplest thing" is misread as "build the dumbest thing" — a licence to omit structure the cited need genuinely requires. The simplest shape that serves a cited access pattern is the goal; if the access pattern requires an abstraction (a value object, a protocol, a denormalised projection), the abstraction is the simplest shape and omitting it is under-engineering. The test is the cited need, not the line count. + +**Where the discipline runs.** The interview funnels ask the simplicity question at each level (L1: smallest surface that meets the need; L2: speculative vs grounded behaviour groups; L3: load-bearing vs collapsible building blocks). `consolidate-interview` drops speculative items before they reach the contracts. `author-test-stubs` expresses only the structure the findings require. `review-test-stubs` runs the scope-minimal check — the inverted-traceability mirror of coverage: not "is every finding tested?" but "is every test finding-grounded?". `model-data-schema` models the smallest schema that serves the cited access patterns. `simulate-contracts` catches the residue as build-implied gaps (an effect asserted without pinning how; two impls both passing). The discipline is applied at the earliest gate, not deferred to the latest. + +## Content + +### The anti-pattern catalogue + +Each anti-pattern is a structure beyond the cited need. Each is named at the gate that first sees it and dropped (or routed to rework) with the speculative element cited. + +| Anti-pattern | Signal | Where caught | Action | +|---|---|---|---| +| Premature abstraction | a class, protocol, or hierarchy with no cited need requiring it | interview L3, `review-test-stubs`, `simulate-contracts` | collapse into the caller; drop the abstraction; cite the missing need or remove | +| Speculative configurability | a parameter, option, or strategy hook no cited access pattern exercises | interview L2, `review-test-stubs` | inline the one variant the spec requires; drop the hook | +| Duplicate concept | two names for one cited need (a value object and a primitive both carrying the same domain value) | interview L3, `consolidate-interview`, `simulate-contracts` | unify behind one canonical form per the data-shape rule in [[software-craft/source-stubs]] | +| Seam-without-a-reason | an interface or boundary with a single implementation and no cited integration or anti-corruption need | interview L3, `review-test-stubs`, `derive-source-stubs` | inline the implementation; introduce the seam only when a second implementation or a cited context boundary requires it | +| Speculative field | a column in `data-model.md` with no consumer in any cited access pattern | `model-data-schema` | drop the field; route to `needs-capture` if a future capture might ground it | +| Speculative building block | a bounded context or module with no quality attribute and no behaviour group grounding it | interview L3, `consolidate-interview` | drop the block at consolidation; flag if a later finding requires it | + +### The simplicity question at each funnel level + +| Level | Question | What it catches | +|---|---|---| +| L1 (general) | "What's the smallest surface that meets the need?" | scope inflation at the big-picture level — the stakeholder's answer names the minimum, the contracts honour it | +| L2 (cross-cutting) | "Which of these behaviour groups are speculative — not grounded in a cited stakeholder need?" | behaviour groups the stakeholder did not name in a CIT incident or a laddered constraint | +| L3 (building-blocks) | "Is this building block load-bearing, or could it collapse into a neighbour?" | modules that have no unique responsibility a cited need requires | + +A speculative item surfaced at any level is either grounded (cite the need) or dropped (remove from the notes). `consolidate-interview` enforces the drop: a speculative item with no cited grounding does not reach the contracts. + +### Scope-minimal — the inverted-traceability mirror + +`review-test-stubs` runs two complementary checks: + +| Check | Direction | Question | Failure | +|---|---|---|---| +| traceability (existing) | finding → test | "Is every finding tested?" | a finding with no test is a coverage gap | +| scope-minimal (the mirror) | test → finding | "Is every test finding-grounded?" | a test expressing structure beyond its finding is speculative | + +A test that introduces an abstraction, a seam, a configurability, or a building block not grounded in a cited finding is speculative — routed to `needs-stubs-rework` with the speculative element named. The gate evidence key `scope-minimal` is `true` only when no stub in the set expresses speculative structure. + +### The clean non-speculative model + +The simplicity discipline applies to the schema as much as to the test and source contracts. `model-data-schema` models the smallest schema that serves the cited access patterns: a table with no query that reads it, a column with no consumer, a normalisation level beyond what the workload needs, an index without a named query — each is speculative structure, dropped at `model-data-schema`, not deferred to build. The model is clean (non-speculative) when every element traces to a cited access pattern or finding; the contracts downstream reference a clean model, and `simulate-contracts` rejects a contract whose persistence shapes disagree with it. + +## Related + +- [[requirements/interview-techniques]] — CIT and Laddering are how a need becomes "cited"; a need that is not cited is not a requirement +- [[requirements/domain-decomposition]] — the gap analysis the simplicity question at L3 feeds into +- [[architecture/data-modeling]] — the schema-as-contract rule and the speculative-field anti-pattern, applied at `model-data-schema` +- [[software-craft/source-stubs]] — the data-shape rule that resolves a duplicate concept +- [[software-craft/test-design]] — the vacuous-assertion smells (a vacuous test often hides a speculative structure that the test does not pin) +- [[requirements/spec-simulation]] — the build-implied-gap sweep catches residue the earlier gates missed diff --git a/.opencode/knowledge/requirements/spec-simulation.md b/.opencode/knowledge/requirements/spec-simulation.md index 13320369..4c0225aa 100644 --- a/.opencode/knowledge/requirements/spec-simulation.md +++ b/.opencode/knowledge/requirements/spec-simulation.md @@ -10,14 +10,17 @@ last-updated: 2026-07-01 - Simulation is a **mental execution of the contract set** — the test `.pyi`, the test `.py`, and the source `.pyi` together — asking whether a correct implementation that passes every test would actually work end-to-end and be complete. - The e2e-affecting failures live in **composition and cross-test coherence**, where tools are blind: a type imported from a module that does not re-export it, a value whose shape differs between the tests that produce and consume it, a shared module no test drives, a dependency graph with no valid build order. These surface only when a human walks the contracts. -- **Walk the e2e path hop by hop** — entry point → adapter → domain → persistence. At each hop confirm the type passed, the value carried, and the side effect performed each trace to a backing contract; a broken hop is the simulation's main catch. +- Simulation is a **compiler, not a ceremony**. It does not validate that the model "works" — the model (`data-model.md`) is already a binding input. It takes the contract set and simulates how the real application would run if a correct implementation made every test pass, the way a compiler walks an AST to prove the program type-checks and links before any code executes. The goal is to **disprove or confirm** the system works, mentally, before any source `.py` is written. +- **Walk the e2e path hop by hop, journal at each hop** — entry point → adapter → domain → persistence. At each hop confirm the type passed, the value carried, and the side effect performed each trace to a backing contract, and **append the observation to `.cache//journal.md` at that hop** — not only the verdict at the end. A broken hop is the simulation's main catch. - **Trace each domain value across every test that touches it.** If two tests pass the same concept in different shapes, the contract is incoherent; pin one canonical form or split the concept. No tool performs this — it is a reading, not a check. -- The tool floor is **necessary but not sufficient**: pyright (zero errors, tolerate `reportMissingModuleSource` pre-build), stubtest over the test pairs (drift), no-orphans (every source symbol exercised, every test reference backed), traceability (every interview finding → a test or deferral; every external service → a captured cassette). Each catches a class of defect; none catches composition. -- The output is a **judgment with evidence**: the gate decision — advance, or a named gap — backed by the walkthroughs and traces that justify it. The simulation's value is the understanding that informs the decision. +- **Spec-diff is not traceability.** Traceability counts whether a finding has any test; spec-diff asks whether the test would actually fail if the finding were violated. A finding named in a test but not enforced — a vacuous assertion, a lower-bound-only check, an `assert True`, an effect asserted without pinning how — is a gap, not a pass. +- **Build-implied gaps** are ambiguities a correct implementation would surface: two impls both pass but only one matches spec; an effect asserted without pinning how; a side effect no test observes; a persistence shape the test asserts but the model doesn't declare. The gate question expands from "would passing = working?" to "would passing = working **and unambiguous**?". +- The tool floor is **necessary but not sufficient**: pyright (zero errors, tolerate `reportMissingModuleSource` pre-build), stubtest over the test pairs (drift), no-orphans (every source symbol exercised, every test reference backed), traceability (every interview finding → a test or deferral; every external service → a captured cassette). Each catches a class of defect; none catches composition or ambiguity. +- The output is a **judgment with evidence**: the gate decision — advance, or a named gap — backed by the per-hop walkthroughs, the value traces, the spec-diff, and the build-implied-gap sweep, all recorded in the journal. The simulation's value is the understanding that informs the decision. ## Concepts -**Mental execution of the contract set.** The plan phase produces the contract set: every test written as an executable body, every source symbol recorded as a `.pyi` signature. Simulation is the act of reading that set as if it were already implemented and asking the one question that gates the build: *if a correct implementation made every one of these tests pass, would the resulting system work as intended and be complete?* It is a prediction of the future, made by walking the contracts the future will be built from. Because the contracts are executable, the prediction is answerable: every type, call, and side effect the simulation reasons about is one a test will enforce. +**Mental execution of the contract set.** The plan phase produces the contract set: every test written as an executable body, every source symbol recorded as a `.pyi` signature, the schema recorded in `data-model.md`. Simulation is the act of reading that set as if it were already implemented and asking the one question that gates the build: *if a correct implementation made every one of these tests pass, would the resulting system work as intended and be unambiguous?* It is a prediction of the future, made by walking the contracts the future will be built from. Because the contracts are executable, the prediction is answerable: every type, call, and side effect the simulation reasons about is one a test will enforce. Simulation is a compiler, not a ceremony: it does not validate that the model works (the model is a binding input, already authored), it compiles the contract set in the reader's head to disprove — or confirm — that the system runs, before any source `.py` exists. **Why the tool floor is not enough.** pyright, stubtest, and the traceability counts each police a class of defect the others miss, and together they form a real floor — but every one of them reads files in isolation or checks a structural invariant, and none of them reads *across* the contract set the way a reader does. A type imported from a module that does not re-export it resolves fine for the checker and breaks at the composition. A value carried as a bare filesystem path by one test and as a `sqlite:///` URL by another is typed `str` in both stubs and passes every check, while the contract it implies is incoherent. A shared data module with no external boundary of its own has no test driving it, and no tool notices the gap. These are the failures that ship to build and surface as e2e breakage; simulation is the step that exists to catch them, because nothing else does. @@ -55,6 +58,31 @@ A finding that cannot be grounded in one of these artefacts is not a simulation These are the e2e-affecting failures; each ships silently to build if simulation does not catch it. +### The build-implied gaps + +Ambiguities a correct implementation would surface — the contract under-determines the behaviour, so two impls both pass but only one matches the spec. Each is a gap even when the tool floor is clean. + +| Gap | What the tool sees | What the simulation sees | +|---|---|---| +| two impls both pass, only one matches spec | a green test set | an under-determined contract — the test does not pin the behaviour the spec requires | +| an effect asserted without pinning how | a green test set | a test that asserts an outcome but not the mechanism; a constant, a no-op, or a real computation all pass | +| a side effect no test observes | a green test set | a contract that claims a side effect (a write, a publish) but no test observes it; the impl could omit it and pass | +| a persistence shape the test asserts but `data-model.md` doesn't declare (or vice versa) | a green test set | a contract that disagrees with the modeled schema — incoherent, the model is canonical | + +The gate question expands from "would passing = working?" to "would passing = working **and unambiguous**?". A contract set with a build-implied gap is not `accepted`; it routes to `needs-test-bodies` (or `needs-source-stubs` if the ambiguity is at the source-stub surface) with the gap cited. + +### Spec-diff + +For each consolidated interview finding, confirm the test set **enforces** it, not merely names it. This is distinct from traceability (which counts coverage); spec-diff asks whether the test would actually fail if the finding were violated. + +| The finding | Traceability says | Spec-diff says | +|---|---|---| +| "the report carries a generated_at timestamp" | a test references `generated_at` | the test asserts a *value* (a real timestamp, its type, its presence under a non-trivial impl) — `hasattr(report, "generated_at")` is naming, not enforcing | +| "the renderer escapes HTML" | a test calls the renderer | the test asserts the *escaped output* against input that would break a constant-string renderer — a constant-satisfiable test is naming, not enforcing | +| "the adapter returns JSON-serialisable values" | a test calls `_to_jsonable` | the test asserts *round-trip through `json.dumps`* — `_to_jsonable(value: object) -> object: return value` is naming, not enforcing | + +A finding named in a test but not enforced is a gap, routed to `needs-test-bodies` with the finding and the offending test cited. + ### The e2e hop-by-hop walkthrough Walk the entry-point test as if the system were built, hop by hop: @@ -92,10 +120,10 @@ Two shapes for one concept is a defect to resolve at plan, not a tolerance for b The simulation produces one of two outcomes, and nothing else: -- **coherent and complete** — the walkthrough reached no broken hop, the value traces found no disagreement, the tool floor is clean; advance to build. -- **a named gap** — which hop broke, which value disagreed, which module has no driver; route back to plan with the specifics. +- **coherent, complete, and unambiguous** — the walkthrough reached no broken hop, the value traces found no disagreement, the spec-diff found no named-but-not-enforced finding, the build-implied-gap sweep found no ambiguity, the tool floor is clean; advance to build. The journal holds the per-hop observations that justify the verdict, not only the verdict. +- **a named gap** — which hop broke, which value disagreed, which finding was named but not enforced, which ambiguity a correct impl would surface, which persistence shape disagreed with the model; route back to plan (or explore, or discover) with the specifics. -The understanding is the output, and it lives in the gate decision. +The understanding is the output, and it lives in the gate decision — recorded in the journal at the hop it was made, not only at the verdict. ## Related diff --git a/.opencode/knowledge/software-craft/external-fixtures.md b/.opencode/knowledge/software-craft/external-fixtures.md index 23c1df16..2d6801fa 100644 --- a/.opencode/knowledge/software-craft/external-fixtures.md +++ b/.opencode/knowledge/software-craft/external-fixtures.md @@ -63,6 +63,37 @@ Two independent scrubs apply to every cassette, and vcrpy performs neither (Mosk A cassette records what the service actually did. If the adapter test fails against it, the implementation is wrong or the contract drifted — never hand-edit the cassette to make the test pass, because the moment you do, the test is asserting against a wish, not reality. When the service itself changes — a new required field, a restructured error — the correct response is to re-record (our flow signals a mismatch and re-enters discovery), replacing the stale capture entirely. Version control holds the history of what the cassette used to be; the working tree holds only what the service does now. +### Replay mechanism — vcr.use_cassette, not pytester + +The cassette is replayed in-process by the adapter test. The mechanism is fixed by the service kind: + +| Service kind | Replay mechanism | Why | +|---|---|---| +| HTTP API (httpx) | `with vcr.use_cassette(cassette_path(NAME)):` around the adapter call | vcrpy intercepts the httpx transport in-process; the cassette is the contract the test asserts against | +| Library-boundary vcrpy cannot intercept (e.g. ddgs/primp) | `monkeypatch` on the adapter's transport | the library calls a non-HTTP transport vcrpy has no hook into; monkeypatch is the in-process replacement | +| CLI subprocess | `pytester` (the pytest subprocess runner) | the SUT is a CLI process, not a function call; pytester spawns it and asserts on stdout/exit | + +The wrong tool for an httpx adapter test is `pytester`. It spawns a child pytest process, which breaks collection (the cassette lives in the parent's `tests/cassettes/`), hides the cassette contract from the type surface (the `.pyi` cannot name a cassette a subprocess owns), and runs the adapter out-of-process so the vcrpy interceptor never sees the call. The cassette contract must be visible in the test `.pyi` — the `cassette_path(NAME)` constant is declared at module level and the `with vcr.use_cassette(...)` block is in the test body — so stubtest and the simulation can see it. + +``` +# WRONG — pytester spawns a subprocess; the cassette is invisible to the .pyi +# and vcrpy never intercepts the call; the test cannot assert against +# the captured exchange +def test_fetch(self, pytester) -> None: ... + +# RIGHT — in-process replay against the captured exchange; the cassette constant +# is declared at module level (visible to stubtest) and the +# use_cassette block is in the body (visible to the simulation) +CASSETTE: str + +class TestRatesAdapter: + rates: RatesAdapter + def setup_method(self) -> None: ... + def test_fetches_rate(self) -> None: ... +``` + +The exception — a library-boundary adapter vcrpy cannot intercept (ddgs wraps primp, which is not an httpx transport) — uses `monkeypatch` on the adapter's transport, in-process. `pytester` remains reserved for CLI subprocess tests, where the SUT genuinely is a child process. + ## Related - [[software-craft/test-design]] — the adapter test that replays a cassette and asserts against the captured shapes diff --git a/.opencode/knowledge/software-craft/smell-catalogue.md b/.opencode/knowledge/software-craft/smell-catalogue.md index 443c994e..fcfdb976 100644 --- a/.opencode/knowledge/software-craft/smell-catalogue.md +++ b/.opencode/knowledge/software-craft/smell-catalogue.md @@ -64,6 +64,7 @@ last-updated: 2026-07-01 | Data Class | fields with getters/setters, no behaviour | Move Method into it; Encapsulate Field | | Dead Code | unreachable, unused | delete it | | Speculative Generality | abstraction with no current caller | Inline Class/Method; remove the unused parameter | +| Vacuous Test | an assertion a trivial implementation (constant, identity, `assert True`) satisfies | rewrite the assertion to pin observable behaviour per [[software-craft/test-design]] | ### Couplers diff --git a/.opencode/knowledge/software-craft/test-design.md b/.opencode/knowledge/software-craft/test-design.md index 8615e9e4..8875a2d3 100644 --- a/.opencode/knowledge/software-craft/test-design.md +++ b/.opencode/knowledge/software-craft/test-design.md @@ -65,6 +65,20 @@ The line that is *never* crossed is mocking an internal collaborator. Replacing If a value the interview supplied does not fit the test naturally, that is a signal the spec is unclear about why the value matters — not licence to absorb it as noise. +### Vacuous assertions + +A vacuous assertion is one a trivial implementation satisfies — a constant return, an empty collection, an identity function, a `return True`. A test that cannot fail under a trivial impl tests nothing, and the worst case is that it sails through every gate and ships as if it were a contract. The discipline: for every assertion in a test body, ask whether it would fail under a trivial implementation of the system under test; if it would not, the assertion is the smell, not the test surface. + +| Smell | Example | Why it's vacuous | +|---|---|---| +| `hasattr`-only | `assert hasattr(report, "generated_at")` | asserts the attribute exists, nothing about its value — a constant attribute passes | +| no-op helper | `_to_jsonable(value: object) -> object: return value` | identity function passes as "JSON-serialisable"; `return True`, `assert True` are the same | +| lower-bound-only | `assert x >= 0` against an empty fixture | trivially true when no value is negative | +| constant-satisfiable | a renderer test that a constant-string renderer passes | any constant output satisfies — the assertion pins nothing about the renderer's behaviour | +| tautology | `assert result == compute(...)` where `result` is `compute(...)` | the expected value is derived from the computation under test; the test cannot fail | + +The vacuous-assertion check is gated at `review-test-stubs` (the `vacuous-assertion-free` evidence key), not deferred to `simulate-contracts`. A vacuous test that reaches the simulation gate has already failed the review gate; the simulation catches what review missed, but review is where the smell belongs. + ### Property tests prove invariants An example can only confirm a rule holds for the chosen case; it cannot prove the rule holds generally. Hypothesis (MacIver, 2016) generates inputs across the declared strategy and shrinks any failing case to the smallest counterexample, so a property test is the right tool when the requirement is universal: @@ -82,4 +96,5 @@ Property tests live alongside the example tests in the same suite; they are not - [[software-craft/test-stubs]] — the `.pyi` signature file each test is authored against first - [[software-craft/external-fixtures]] — the cassettes and fixtures that replace the external collaborator at the boundary - [[software-craft/code-review]] — the review method that checks these criteria are met +- [[software-craft/smell-catalogue]] — a vacuous test is dead weight in the Dispensables sense; the smell catalogue cross-links back - [[software-craft/solid]], [[software-craft/object-calisthenics]] — the design discipline the bodies are held to diff --git a/.opencode/knowledge/software-craft/test-stubs.md b/.opencode/knowledge/software-craft/test-stubs.md index b8faa92c..9eb5a365 100644 --- a/.opencode/knowledge/software-craft/test-stubs.md +++ b/.opencode/knowledge/software-craft/test-stubs.md @@ -78,7 +78,7 @@ class TestRatesAdapter: # the test class def test_fetches_rate(self, monkeypatch) -> None: ... ``` -Two test-specific drift vectors have no library-stub analogue. First, fixture parameters (`monkeypatch`, `tmp_path`, `capsys`) are resolved by *name* through pytest's dependency injection; a type checker reading the `.pyi` cannot see that binding, so the parameter is declared for structural agreement and left unannotated (the typing.python.org guide permits unannotated arguments in partial stubs). Second, instance attributes assigned in `setup_method` do not exist in the class body the checker reads, so they must be hand-declared at class level in the `.pyi` and updated whenever `setup_method` changes. Both drift silently if forgotten — stubtest is what eventually catches them. +Two test-specific drift vectors have no library-stub analogue. First, fixture parameters (`monkeypatch`, `tmp_path`, `capsys`) are resolved by *name* through pytest's dependency injection; a type checker reading the `.pyi` cannot see that binding, so the parameter is declared for structural agreement and left unannotated (the typing.python.org guide permits unannotated arguments in partial stubs). The replay mechanism for an external-boundary adapter test (`vcr.use_cassette`, never `pytester`) is fixed by the service kind — see [[software-craft/external-fixtures]]'s replay-mechanism table; the `cassette_path(NAME)` constant is declared at module level and the `with` block is in the body, so stubtest sees the cassette and the simulation sees the replay. Second, instance attributes assigned in `setup_method` do not exist in the class body the checker reads, so they must be hand-declared at class level in the `.pyi` and updated whenever `setup_method` changes. Both drift silently if forgotten — stubtest is what eventually catches them. ### Stdlib typing only; types under TYPE_CHECKING diff --git a/.opencode/skills/author-test-stubs/SKILL.md b/.opencode/skills/author-test-stubs/SKILL.md index b6824a1c..56dee6c6 100644 --- a/.opencode/skills/author-test-stubs/SKILL.md +++ b/.opencode/skills/author-test-stubs/SKILL.md @@ -6,11 +6,12 @@ description: "Author test stub files (.pyi) whose signatures express the domain, # Author Test Stubs 1. Load [[software-craft/test-stubs]], [[software-craft/test-design]] — stub conventions and what-to-test patterns. -2. Read `.cache//journal.md` IF present — it carries escalation findings from build (contract gaps). Rework the contracts it names first; skip if absent (first pass). +2. Read `.cache//journal.md` (always present — bootstrapped at plan entry by `model-data-schema`). IF it carries escalation findings from build (contract gaps) THEN rework the contracts it names first; otherwise skip. 3. Author integration and E2E test stubs only — no unit-test stubs. Author in build layer order so external-boundary contracts precede adapter, then internal-data, then internal contracts. 4. Express the requirement in class and method signatures with type annotations: entity relationships, compositions, and the behaviour each test asserts. External-layer stubs assert against the captured cassettes — real shapes, not guesses. -5. Make each stub a COMPLETE module surface: declare every module-level name the .py will expose (constants, fixtures, helper functions) plus the test class and its method signatures. The test .pyi must mirror the .py's full module surface per [[software-craft/test-stubs]]. -6. Import stdlib typing only. IF a third-party library is referenced THEN do not import it in the stub — third-party imports trip mypy import-untyped, and stubtest does not require them. -7. Run ruff on the authored .pyi (`ruff check`); the PYI rules lint stubs. Fix every violation. -8. IF authoring surfaces an important new domain concept THEN add it to the glossary. -9. IF reworking an existing contract THEN change signatures here first; the body is re-marked at write-test-py. +5. External-boundary replay rule. An HTTP (httpx) adapter test MUST use `with vcr.use_cassette(cassette_path(NAME)):` as a context manager around the adapter call — in-process replay against the captured exchange per [[software-craft/external-fixtures]]. `pytester` is reserved for CLI subprocess tests ONLY; never use it for vcrpy cassette replay (it spawns a child pytest process, breaks collection, and hides the cassette contract from the type surface). Exception: a library-boundary adapter vcrpy cannot intercept (e.g. ddgs/primp) uses `monkeypatch` on the adapter's transport, not `pytester`. The wrong-vs-right pattern and the kind-dispatch table are in [[software-craft/external-fixtures]]. +6. Make each stub a COMPLETE module surface: declare every module-level name the .py will expose (constants, fixtures, helper functions) plus the test class and its method signatures. The test .pyi must mirror the .py's full module surface per [[software-craft/test-stubs]]. +7. Import stdlib typing only. IF a third-party library is referenced THEN do not import it in the stub — third-party imports trip mypy import-untyped, and stubtest does not require them. +8. Run ruff on the authored .pyi (`ruff check`); the PYI rules lint stubs. Fix every violation. +9. IF authoring surfaces an important new domain concept THEN add it to the glossary. +10. IF reworking an existing contract THEN change signatures here first; the body is re-marked at write-test-py. diff --git a/.opencode/skills/consolidate-interview/SKILL.md b/.opencode/skills/consolidate-interview/SKILL.md index 50d32029..f8a2711f 100644 --- a/.opencode/skills/consolidate-interview/SKILL.md +++ b/.opencode/skills/consolidate-interview/SKILL.md @@ -5,8 +5,9 @@ description: "End of session — replace running notes with the full synthesis a # Consolidate Interview -1. Load [[requirements/ubiquitous-language]] — term extraction for the glossary. This level synthesises (Active Listening L3, applied in step 3); it does not probe. +1. Load [[requirements/ubiquitous-language]], [[methodology/simplicity-discipline]] — term extraction for the glossary and the simplicity discipline that enforces the drop at consolidation. This level synthesises (Active Listening L3, applied in step 3); it does not probe. 2. Read the running interview-notes across all three levels. 3. Apply Active Listening L3: replace the running notes with the full synthesis across all three funnel levels and present it to the stakeholder for approval. The summary reflects what the stakeholder said — no new framing or topic labels. -4. Render `docs/glossary.md` from `.templates/docs/glossary.md.template` (substitute ``): one `## Context: ` section per context, one `### ` entry per term in the template's format (`A that .` + `*Aliases: … · Source: …*`), from the stakeholder's own terms, so it leads all subsequent naming per [[requirements/ubiquitous-language]]. -5. Exit interview-ready when the stakeholder approves; re-enter the funnel at general whenever plan or build finds the elicitation itself was insufficient. +4. Drop speculative items per [[methodology/simplicity-discipline]]: every behaviour group, building block, quality attribute, and field surfaced at any funnel level is either grounded in a cited stakeholder need (a CIT incident, a laddered constraint, a named access pattern) or removed from the synthesis before approval. An item with no cited grounding does not reach the contracts — the contracts are the smallest surface that serves the cited needs, neither over- nor under-engineered. Flag each drop in the synthesis so the stakeholder can object; an unchallenged drop is final. +5. Render `docs/glossary.md` from `.templates/docs/glossary.md.template` (substitute ``): one `## Context: ` section per context, one `### ` entry per term in the template's format (`A that .` + `*Aliases: … · Source: …*`), from the stakeholder's own terms, so it leads all subsequent naming per [[requirements/ubiquitous-language]]. +6. Exit interview-ready when the stakeholder approves; re-enter the funnel at general whenever plan or build finds the elicitation itself was insufficient. diff --git a/.opencode/skills/derive-source-stubs/SKILL.md b/.opencode/skills/derive-source-stubs/SKILL.md index 2772cac5..cdc35091 100644 --- a/.opencode/skills/derive-source-stubs/SKILL.md +++ b/.opencode/skills/derive-source-stubs/SKILL.md @@ -6,7 +6,7 @@ description: "Derive the source stub files (.pyi) from the reviewed tests — ev # Derive Source Stubs 1. Load [[software-craft/source-stubs]], [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/design-patterns]], [[architecture/context-mapping]] — source stub conventions, the quality principles, the pattern catalog, and the inter-context relationship patterns. -2. Read `.cache//journal.md` IF present — it carries escalation findings from build. Adjust the source stubs of the contracts it names; skip if absent (first pass). +2. Read `.cache//journal.md` (always present — bootstrapped at plan entry by `model-data-schema`). IF it carries escalation findings from build THEN adjust the source stubs of the contracts it names; otherwise skip. 3. Read the test .py imports and bodies — every type constructed, method called, and relationship asserted in a body is the specification of the source surface. Emit a matching .pyi signature (with an ellipsis body) for every type the tests reference, wherever the source lives. 4. Define types, relationships, and compositions to satisfy SOLID and Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a relationship emits a smell at the type surface (a kind-field that will switch, parallel hierarchies, construction scattered across callers, refused bequest) THEN reach for the matching pattern per [[software-craft/design-patterns]] — but KISS/YAGNI first: prefer the simplest structure that removes the smell, and prefer Python idioms (a Protocol, a dataclass, a first-class callable, a generator, a decorator) over GoF ceremony. Do not apply a pattern speculatively; Speculative Generality is the smell that rejects it. 5. IF a relationship bridges two bounded contexts (an external service, an upstream module, a shared data shape) THEN pick the inter-context pattern per [[architecture/context-mapping]] — default to an Anti-Corruption Layer (an adapter that translates the foreign model into ours) for any external dependency; reach for Shared Kernel only for a small value-object set both contexts truly co-own. diff --git a/.opencode/skills/interview-building-blocks/SKILL.md b/.opencode/skills/interview-building-blocks/SKILL.md index b9db29d0..64392840 100644 --- a/.opencode/skills/interview-building-blocks/SKILL.md +++ b/.opencode/skills/interview-building-blocks/SKILL.md @@ -5,7 +5,8 @@ description: "Funnel level 3 — identify building-block names and rough boundar # Interview (Building Blocks) -1. Load [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]], [[architecture/quality-attributes]] — gap analysis, boundary sizing, and the quality-attribute taxonomy the coverage check runs over. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). +1. Load [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]], [[architecture/quality-attributes]], [[methodology/simplicity-discipline]] — gap analysis, boundary sizing, the quality-attribute taxonomy the coverage check runs over, and the simplicity discipline. This level is structural decomposition, not CIT/Laddering elicitation (those served levels 1–2). 2. Read the running interview-notes; append the building-block names and boundaries to it. 3. Capture building-block NAMES and rough boundaries ONLY — no detailed spec (rules, examples, criteria come later in planning). The purpose is to know WHAT building blocks exist, not to specify each. -4. Run gap analysis: IF a bounded context from cross-cutting maps to no block THEN flag the gap; IF a quality attribute maps to no block THEN flag the gap. Do not silently fill gaps per [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]]. +4. Ask the simplicity question for each block: "Is this building block load-bearing, or could it collapse into a neighbour?" A block with no unique responsibility a cited need requires is speculative per [[methodology/simplicity-discipline]] — flag it for collapse into a neighbour or drop at consolidation. A block the cited need requires but no current block covers is a gap, flagged here (not silently filled). +5. Run gap analysis: IF a bounded context from cross-cutting maps to no block THEN flag the gap; IF a quality attribute maps to no block THEN flag the gap. Do not silently fill gaps per [[requirements/domain-decomposition]], [[requirements/aggregate-boundaries]]. diff --git a/.opencode/skills/interview-cross-cutting/SKILL.md b/.opencode/skills/interview-cross-cutting/SKILL.md index 645f7f95..ef355a90 100644 --- a/.opencode/skills/interview-cross-cutting/SKILL.md +++ b/.opencode/skills/interview-cross-cutting/SKILL.md @@ -5,7 +5,8 @@ description: "Funnel level 2 — structure the domain into behaviour groups, bou # Interview (Cross-cutting) -1. Load [[requirements/interview-techniques]], [[architecture/quality-attributes]] — CIT, Laddering, CI Perspective Change, and the Active Listening protocol; and the quality-attribute taxonomy to elicit. +1. Load [[requirements/interview-techniques]], [[architecture/quality-attributes]], [[methodology/simplicity-discipline]] — CIT, Laddering, CI Perspective Change, and the Active Listening protocol; the quality-attribute taxonomy to elicit; and the simplicity discipline. 2. Read the running interview-notes; append the cross-cutting findings to it. 3. Structure the domain into behaviour groups, bounded contexts, integration points, and lifecycle events. Probe each with CIT and Laddering; IF recall stalls THEN re-frame via CI Perspective Change. Capture the quality attributes stakeholders care about as one-line scenarios (stimulus → response), not bare words, per [[architecture/quality-attributes]]. -4. Apply Active Listening L2: give a brief synthesis when transitioning between behaviour groups — confirms completeness, offers a recovery point. +4. Ask the simplicity question for each behaviour group: "Is this group speculative — not grounded in a cited stakeholder need?" A group with no CIT incident and no laddered constraint grounding it is speculative per [[methodology/simplicity-discipline]]; flag it for drop at consolidation or ground it with a cited need now. +5. Apply Active Listening L2: give a brief synthesis when transitioning between behaviour groups — confirms completeness, offers a recovery point. diff --git a/.opencode/skills/interview-general/SKILL.md b/.opencode/skills/interview-general/SKILL.md index ddc8e6dc..f07eadad 100644 --- a/.opencode/skills/interview-general/SKILL.md +++ b/.opencode/skills/interview-general/SKILL.md @@ -5,8 +5,9 @@ description: "Funnel level 1 — establish the big picture with seven broad ques # Interview (General) -1. Load [[requirements/interview-techniques]] — CIT, Laddering, CI Perspective Change, the Funnel, and the Active Listening protocol. +1. Load [[requirements/interview-techniques]], [[methodology/simplicity-discipline]] — CIT, Laddering, CI Perspective Change, the Funnel, the Active Listening protocol, and the simplicity discipline that runs alongside every funnel level. 2. Begin the running interview-notes artifact (scoped to this session) with the general findings. 3. Ask seven big-picture questions in any natural order: Who, What, Why, When/Where, Success, Failure, Out-of-scope. Do not introduce category or topic labels — let the stakeholder's own categories emerge first (priming bias). 4. Probe every answer with CIT (a concrete past incident) and Laddering (climb to a writable constraint). IF recall stalls THEN re-frame from another actor's seat (CI Perspective Change). -5. Apply Active Listening L1: paraphrase each answer before the next question. +5. Ask the simplicity question: "What's the smallest surface that meets the need?" The stakeholder's answer names the minimum the contracts must honour; an answer that inflates scope beyond the cited need is a speculative structure, flagged here per [[methodology/simplicity-discipline]]. +6. Apply Active Listening L1: paraphrase each answer before the next question. diff --git a/.opencode/skills/model-data-schema/SKILL.md b/.opencode/skills/model-data-schema/SKILL.md new file mode 100644 index 00000000..3a8d564c --- /dev/null +++ b/.opencode/skills/model-data-schema/SKILL.md @@ -0,0 +1,23 @@ +--- +name: model-data-schema +description: "Author the persistence schema as a binding contract from the captured external shapes and the interview — before any test stub is written." +--- + +# Model Data Schema + +1. Load [[architecture/data-modeling]], [[software-craft/external-fixtures]] — the schema-as-contract rule, OLTP/OLAP selection, workload-driven normalization, and the captured external shapes that bound the model. +2. Bootstrap the journal. IF `.cache//journal.md` does not exist THEN render it from `.templates/cache/journal.md.template` (substitute ``). The journal is the carry-over artifact for build-phase escalations, capture gaps, and the simulation walk; empty until those states write to it. Absence on a first pass is expected — never a deliberation point; the first pass IS the empty-journal pass. IF it exists THEN it carries build-phase escalations from the prior build cycle — read them and model the gaps it names first. +3. Read `.cache//external-contracts.md`, `tests/cassettes/**`, `.cache//interview-notes.md`, `docs/glossary.md`. +4. Classify the workload before naming a table. State, with cited evidence from the interview or the captured exchanges, whether the dominant access pattern is: + - OLTP — ingest-heavy append-only, per-row writes, point reads; normalise; enforce integrity in constraints. + - OLAP — read-heavy analytics over large sets, aggregations and filters on named dimensions; model the dimensions and pre-aggregate where a named query pays for it. + - Hybrid — name the OLTP path and the OLAP path separately and the trade-off that reconciles them. +5. Author `.cache//data-model.md` as the schema spec the build-phase developer implements against — NOT a deferral, NOT a sketch. For every table record: + - its purpose, in one line, traced to a finding in `interview-notes.md`; + - every column with its type and the constraint that holds on it (NOT NULL, UNIQUE, CHECK, FK target); + - every index, paired with the named query pattern that justifies it — an index without a cited query is rejected per [[architecture/data-modeling]] and per the agent's own refusal (`data-architect.md`); + - the OLTP/OLAP/hybrid verdict from step 4 and the access patterns it optimises for. +6. Trace every field to a captured external shape or an interview finding. A field with no trace is either speculative (drop it) or a missing capture (route to `needs-capture`), never an ungrounded guess baked into the model. Anti-patterns to refuse, named in [[architecture/data-modeling]]: mirroring a code-class shape into a table, premature denormalization, an index without a query, a constraint the spec does not require. +7. Apply simplicity discipline per [[methodology/simplicity-discipline]]: model the smallest schema that serves the cited access patterns. A table with no query that reads it, a column with no consumer, a normalisation level beyond what the workload needs — each is speculative structure, dropped here, not deferred to build. +8. IF the model surfaces an important new domain concept THEN add it to the glossary. +9. IF a captured external shape is ambiguous or insufficient to model against THEN append the gap to `.cache//journal.md` (service, the missing case) and fire `needs-capture`. Do NOT invent the shape — the model is grounded in captures, not guesses. diff --git a/.opencode/skills/review-test-stubs/SKILL.md b/.opencode/skills/review-test-stubs/SKILL.md index e44028d8..103c3d2e 100644 --- a/.opencode/skills/review-test-stubs/SKILL.md +++ b/.opencode/skills/review-test-stubs/SKILL.md @@ -1,12 +1,20 @@ --- name: review-test-stubs -description: "Review the test stubs for coverage, scope, and happy-path completeness against the interview — not for code quality." +description: "Review the test stubs for coverage, scope, vacuous-assertion freedom, finding-grounded scope, and happy-path completeness against the interview and the modeled schema — not for code quality." --- # Review Test Stubs -1. Load [[software-craft/code-review]], [[requirements/domain-decomposition]] — review method and gap analysis. +1. Load [[software-craft/code-review]], [[requirements/domain-decomposition]], [[software-craft/test-design]], [[methodology/simplicity-discipline]] — review method, gap analysis, the vacuous-assertion smells, and the scope-minimal rule. 2. Treat this review as coverage and scope against requirements, not code quality — quality is gated later on the bodies. -3. Check consistency: every stub maps to an interview requirement and uses the glossary's ubiquitous language; external-layer stubs match the captured cassettes. +3. Check consistency: every stub maps to an interview requirement and uses the glossary's ubiquitous language; external-layer stubs match the captured cassettes; persistence-adjacent stubs reference the modeled schema in `.cache//data-model.md`, not invented shapes. 4. Check scope: integration and E2E only; IF a unit test leaked in THEN reject it. 5. Check happy-path completeness: the stub set, once implemented, would exercise the full happy paths of every identified building block. IF a building block or quality attribute maps to no stub THEN flag the gap per [[requirements/domain-decomposition]]. +6. Vacuous-assertion check: for every assertion in every stubbed test, confirm it would **fail under a trivial implementation** (constant return, empty collection, identity function, `return value`). A test that cannot fail under a trivial impl tests nothing — route to `needs-stubs-rework` citing the specific test and the smell. The named smells, per [[software-craft/test-design]]: + - `hasattr`-only — asserts an attribute exists, nothing about its value; + - no-op helper — `_to_jsonable(value: object) -> object: return value` passes as "JSON-serialisable"; `return True`, `assert True`; + - lower-bound-only — `assert x >= 0` against an empty fixture (trivially true); + - constant-satisfiable — a renderer/format test that a constant-string output would pass; + - tautology — the assertion derives the expected value from the computation under test. + IF any assertion matches a smell THEN reject the stub set with the test and the smell cited; do not defer to `simulate-contracts`. The gate evidence key `vacuous-assertion-free` is `true` only when no stub in the set carries any named smell. +7. Scope-minimal check (the inverted-traceability mirror of step 5): every test traces to a consolidated finding; any test expressing structure beyond its finding is flagged for rework citing the speculative element. Step 5 asks "is every finding tested?"; this step asks "is every test finding-grounded?". A test that introduces an abstraction, a seam, a configurability, or a building block not grounded in a cited finding is speculative per [[methodology/simplicity-discipline]] — route to `needs-stubs-rework` with the speculative element named. The gate evidence key `scope-minimal` is `true` only when no stub in the set expresses speculative structure. diff --git a/.opencode/skills/simulate-contracts/SKILL.md b/.opencode/skills/simulate-contracts/SKILL.md index cf1ca89a..4de87eb3 100644 --- a/.opencode/skills/simulate-contracts/SKILL.md +++ b/.opencode/skills/simulate-contracts/SKILL.md @@ -1,16 +1,29 @@ --- name: simulate-contracts -description: "Answer whether a correct implementation passing every test would yield a complete, working system — the final gate before build." +description: "Compile the contract set in your head — simulate how the real application would run from the specs, and disprove (or confirm) it works before any source .py is written." --- # Simulate Contracts -1. Load [[requirements/spec-simulation]], [[software-craft/test-stubs]] — the simulation method and test-pair drift rules. -2. Answer the gate question per [[requirements/spec-simulation]]: IF a correct implementation made every test in the set pass THEN would the result work as intended and be complete? Answer it by walking — walk the e2e path hop by hop (each type handed across, each value carried, each side effect performed tracing to a backing contract), then trace each domain value across every test that touches it for shape coherence. The tool checks below are the floor that makes the walk safe to trust; they are not the walk. IF a hop breaks or two tests disagree on a value's shape THEN name the gap precisely and stop — route back to plan, do not advance on a clean tool run alone. -3. Run pyright on the combined set. The gate is zero errors; `reportMissingModuleSource` is expected (source .pyi exist but no .py yet) and is tolerated. -4. Check no-orphans: every source .pyi symbol is exercised by at least one test, and every test reference is backed by a source .pyi. -5. Check traceability: every consolidated interview finding maps to at least one test or an explicit deferral, and every external service has a captured cassette its tests replay. -6. Check layer order: external-boundary stubs complete before adapter stubs, and so on. -7. Run stubtest on the tests to confirm zero drift between every test .pyi and its sibling .py per [[software-craft/test-stubs]]. Source stubtest waits for build — no source .py exists yet. -8. Run the dev ruff check (`ruff check .`) on the whole project; the gate is zero violations. Restructure lint (`SIM`, `RUF`) and `ruff format` are merge-time per [[software-craft/docstring-lifecycle]] — a readability restructure is not a plan defect. Plan-authored tests and stubs must pass the bug-catcher set before build. -9. IF a test references an external exchange no captured cassette covers THEN append the finding to `.cache//journal.md` (service, the missing case) and fire `needs-capture`. This routes back to explore to record the missing reality, not forward to build. +1. Load [[requirements/spec-simulation]], [[software-craft/test-stubs]], [[methodology/simplicity-discipline]] — the simulation method, the test-pair drift rules, and the scope-minimal rule. +2. **Frame the step.** This is NOT a ceremony that validates the model "works" — the model is already a binding input (`data-model.md`), not something this gate ratifies. This step is a **compiler**: it takes the contract set (test `.pyi`, test `.py`, source `.pyi`, the modeled schema, the captured cassettes, the interview) and simulates how the real application would run if a correct implementation made every test pass — the way a compiler walks an AST to prove the program type-checks and links, before any code executes. You are running the program mentally, against the specs, to **disprove or confirm** that it works. The output is a verdict (`accepted`) or a named gap (`needs-test-bodies`, `needs-source-stubs`, `needs-capture`, `needs-elicitation`) — never a clean stamp on a tool run alone. +3. **Walk the e2e path hop by hop, capturing observations at each hop.** For each hop in the entry-point e2e (entry → adapter → domain → persistence → side effect): + - (a) **Walk the hop** — confirm the type handed across matches the type the receiver declares; the value carried matches the shape the producer emits; the side effect the hop performs is one a contract actually specifies. + - (b) **Append the observation to `.cache//journal.md` at this hop** — not only the verdict at the end. The journal is a per-hop record, not a summary; an observation recorded at the hop it was made is the evidence the verdict rests on. The content is mandated (per-hop observations exist, in any structure the reviewer chooses); the format is not. + - (c) **Cross-check the hop against the spec** (`interview-notes.md`, `glossary.md`, `data-model.md`) — does the spec require something this hop doesn't carry? does the hop carry something the spec doesn't name? A hop that fails this check is a spec gap. + - (d) **Name any gap precisely before continuing** — which hop, which value, which spec finding. IF a hop breaks or two tests disagree on a value's shape THEN stop and route back to plan; do not advance on a clean tool run alone. +4. **Spec-diff.** For each consolidated interview finding, confirm the test set **enforces** it (not merely names it). A finding named in a test but not enforced — a vacuous assertion, a lower-bound-only check, an `assert True`, an effect asserted without pinning how — is a gap, not a pass. This is distinct from traceability (step 6), which counts whether a finding has any test; spec-diff asks whether the test would actually fail if the finding were violated. IF a finding is named but not enforced THEN route to `needs-test-bodies` with the finding and the offending test cited. +5. **Build-implied gaps.** Name any ambiguity a correct implementation would surface: + - **two impls both pass but only one matches spec** — the contract under-determines the behaviour; + - **an effect asserted without pinning how** — the test asserts an outcome but not the mechanism, so any mechanism passes (a constant, a no-op, a real computation); + - **a side effect the test doesn't observe** — the contract claims a side effect (a write, a publish, a state change) but no test observes it, so the implementation could omit it and pass; + - **a persistence shape the test asserts but the model doesn't declare** (or vice versa) — disagreement with `data-model.md`. + Each is a build-implied gap. The gate question expands from "would passing = working?" to "would passing = working **and unambiguous**?". IF any build-implied gap is found THEN route to `needs-test-bodies` (or `needs-source-stubs` if the ambiguity is at the source-stub surface) with the gap cited. +6. **Traceability.** Every consolidated interview finding maps to at least one test or an explicit deferral, and every external service has a captured cassette its tests replay. This is the structural count; it is necessary but not sufficient — step 4 (spec-diff) is what makes a finding "tested" mean "enforced". +7. Run pyright on the combined set. The gate is zero errors; `reportMissingModuleSource` is expected (source .pyi exist but no .py yet) and is tolerated. +8. Check no-orphans: every source .pyi symbol is exercised by at least one test, and every test reference is backed by a source .pyi. +9. Check layer order: external-boundary stubs complete before adapter stubs, and so on. +10. Run stubtest on the tests to confirm zero drift between every test .pyi and its sibling .py per [[software-craft/test-stubs]]. Source stubtest waits for build — no source .py exists yet. +11. Run the dev ruff check (`ruff check .`) on the whole project; the gate is zero violations. Restructure lint (`SIM`, `RUF`) and `ruff format` are merge-time per [[software-craft/docstring-lifecycle]] — a readability restructure is not a plan defect. Plan-authored tests and stubs must pass the bug-catcher set before build. +12. IF a test references an external exchange no captured cassette covers THEN append the finding to `.cache//journal.md` (service, the missing case) and fire `needs-capture`. This routes back to explore to record the missing reality, not forward to build. +13. **Emit the verdict.** `accepted` only when the walkthrough reached no broken hop, the value traces found no disagreement, the spec-diff found no named-but-not-enforced finding, no build-implied gap was named, and the tool floor is clean. Any other outcome is a named gap routed to its target with the specifics (which hop, which value, which finding, which ambiguity) recorded in the journal. diff --git a/.opencode/skills/write-test-py/SKILL.md b/.opencode/skills/write-test-py/SKILL.md index f17a6ea0..c0c4e9f3 100644 --- a/.opencode/skills/write-test-py/SKILL.md +++ b/.opencode/skills/write-test-py/SKILL.md @@ -6,7 +6,7 @@ description: "Transform the reviewed test stubs into executable test bodies, wit # Write Test Py 1. Load [[software-craft/solid]], [[software-craft/object-calisthenics]], [[software-craft/smell-catalogue]], [[software-craft/test-design]] — the quality criteria and body patterns. -2. Read `.cache//journal.md` IF present — it carries escalation findings from build. Edit the bodies of the contracts it names to match the reworked stubs; skip if absent (first pass). +2. Read `.cache//journal.md` (always present — bootstrapped at plan entry by `model-data-schema`). IF it carries escalation findings from build THEN edit the bodies of the contracts it names to match the reworked stubs; otherwise skip. 3. Write the test bodies — no docstrings, no comments; the body is the spec. Bodies define how entities relate, compose, and collaborate: wire classes, data, and objects following best practices. 4. Apply the code-quality gate here: SOLID, DRY, KISS, YAGNI, Object Calisthenics per [[software-craft/solid]], [[software-craft/object-calisthenics]]. IF a smell is present THEN reject it per [[software-craft/smell-catalogue]]. 5. Mark each test with the pending marker; the conftest hook skips pending tests so the suite stays green-with-skips until source is built. diff --git a/.templates/cache/journal.md.template b/.templates/cache/journal.md.template new file mode 100644 index 00000000..7e31662a --- /dev/null +++ b/.templates/cache/journal.md.template @@ -0,0 +1,45 @@ +# Journal: + +> Per-session carry-over across the pipeline. Three kinds of entries, each +> appended by the state that produced it; each routes a transition back to +> an earlier subflow. On a first pass the journal is EMPTY (expected, not a +> missing input) — entries appear only when a gate finds a contract gap or a +> missing capture, or when simulate-contracts walks the e2e path. The first +> reader (model-data-schema) bootstraps this file from the template if it +> does not exist; absence on a first pass is never a deliberation point. + +## Build-phase escalations + +> Appended by confirm-red-failure and review-implementation when the +> contract itself is the problem (not the implementation). Routed back to +> plan on reveals-gap. + +### +- **Gap:** +- **Routed from:** + +## Capture gaps + +> Appended by simulate-contracts and model-data-schema when an external +> exchange is missing or ambiguous. Routed back to explore on needs-capture. + +### +- **Missing case:** +- **Routed from:** + +## Simulation walk + +> Appended by simulate-contracts during the per-hop walkthrough. One entry +> per hop; the verdict at the end. Not routed — internal record that +> justifies the verdict. + +### Hop : +- **Type handed across:** +- **Value carried:** +- **Side effect performed:** +- **Spec cross-check:** +- **Gap:** + +### Verdict + + From 3d238559e802aaeaba26a49dc3655f1e9f5bb3fc Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 7 Jul 2026 03:45:46 -0400 Subject: [PATCH 25/28] =?UTF-8?q?chore:=20bump=20to=20v10.0.0=20=E2=80=94?= =?UTF-8?q?=20modernise=20README,=20pull=20branding=20assets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pyproject.toml 9.4.0 → 10.0.0 (major: clean-slate rebuild post-dogfood) - README rewritten from origin/main, modernised for v10: - new model-data-schema state, compiler-style simulate-contracts - vacuous-assertion sweep + scope-minimal gate - simplicity-discipline funnel, unambiguous replay rules - copier instantiation path documented - commands match actual taskipy tasks - pipeline table + v10.0 FAQ entry + version shield - docs/assets/{banner,logo}.svg pulled from origin/main --- README.md | 265 +++++++++++++++++++++++++++++++---------- docs/assets/banner.svg | 118 ++++++++++++++++++ docs/assets/logo.svg | 78 ++++++++++++ pyproject.toml | 2 +- uv.lock | 2 +- 5 files changed, 397 insertions(+), 68 deletions(-) create mode 100644 docs/assets/banner.svg create mode 100644 docs/assets/logo.svg diff --git a/README.md b/README.md index a4ac1557..b824f625 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,211 @@ -# temple8 +
-> A Python project **methodology template** — a copier template that wires the -> staged-contract development workflow into a new project, with the flow set, the -> agents/skills/knowledge methodology layer, CI, and tooling pre-configured. -> temple8 itself is not an application; an instance built from it holds the -> package, tests, and instance docs. +temple8 -## What it is +

-temple8 makes one workflow reproducible across Python projects: tests are -authored up front as a staged contract surface (test `.pyi` → test `.py` marked -pending → source `.pyi` → simulate), then built out one contract per cycle under -flowr orchestration, with the methodology layer (agents, skills, knowledge), the -drift gates (pyright, `mypy.stubtest`, ruff, pytest), and CI already in place. -Instantiating the template removes the bootstrap cost of re-establishing that -workflow each project. +[![Contributors][contributors-shield]][contributors-url] +[![Forks][forks-shield]][forks-url] +[![Stargazers][stars-shield]][stars-url] +[![Issues][issues-shield]][issues-url] +[![MIT License][license-shield]][license-url] +[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](https://nullhack.github.io/temple8/coverage/) +[![CI](https://img.shields.io/github/actions/workflow/status/nullhack/temple8/ci.yml?style=for-the-badge&label=CI)](https://github.com/nullhack/temple8/actions/workflows/ci.yml) +[![Python](https://img.shields.io/badge/python-%E2%89%A53.13-blue?style=for-the-badge)](https://www.python.org/downloads/) +[![Version](https://img.shields.io/badge/version-10.0.0-5c3d1e?style=for-the-badge)](https://github.com/nullhack/temple8/releases) -## Instantiate a project +**From spec to shipped: state-machine orchestration for spec-driven agent work. Any workflow. Any LLM. Zero lock-in.** -temple8 is a [copier](https://copier.readthedocs.io/) template. To start a new -project from it: +
+ +--- + +You have tried to ship features with AI assistants. The agent writes code, you review it, and somehow the spec still drifts from the implementation. Tests pass but the feature doesn't match what stakeholders asked for. Architecture decisions vanish into commit messages nobody reads. The review cycle is a black box: either everything passes or nothing does, with no structured progression. And the spec itself is never tested — a contract surface that two implementations could satisfy, or that no implementation could, sails through review undetected. + +**temple8 replaces ad-hoc agent orchestration with state machines that route every step through the right agent with the right skills at the right time, and treats the contract surface itself as a compiler would: simulated end-to-end before any source exists.** + +Flow definitions in YAML declare what happens at each state: who owns it, what they may read, what they must produce, and which conditions gate the next transition. No agent guesses what to do next. No step is skipped. Artifacts are scoped to each state's input/output contract. The contract is *compiled* — simulated hop-by-hop against the data model and the requirements — so a spec that two implementations could satisfy, or that one cannot, is caught before a single source file is written. + +--- + +## Who is this for? + +### Developers moving from vibe coding to agentic engineering + +You have shipped code with AI assistants and hit the wall: the agent writes code, you review it, the spec drifts. Vibe coding works for prototypes. It breaks at scale. temple8 replaces "prompt and pray" with spec-driven development: BDD scenarios from interviews, title-based traceability from Example to test function, red-green-refactor cycles enforced by default, a compiler-style simulation gate that disconfirms specs before code, and three-tier review that catches what linters miss — including vacuous assertions that pass without asserting anything. + +### Teams wanting structured agent orchestration without lock-in + +Your team follows a real methodology: Scrum, Kanban, SAFe, or something custom. Multi-agent orchestration should adapt to it, not the other way around. temple8 flows are YAML state machines you define, extend, or replace. Named specialists per state. No subscription, no vendor account, no code leaving your infrastructure. MIT licensed. + +### Anyone evaluating spec-driven development + +Spec-driven development is gaining traction across AI coding tools. You want to try it without committing to a cloud IDE or a monthly subscription. temple8 is a project template: clone it, run it locally with any LLM, see if the process discipline works for your team. Already have a Python project? Use [agents-smith](https://github.com/nullhack/agents-smith) to add temple8's agentic capabilities with one command. + +--- + +## What it does ``` +flowr check → inspect a state's owner, skills, and transitions +flowr next → see which transitions pass given your evidence +flowr transition → advance to the next state with evidence +``` + +**State machines route the work.** YAML flows define the delivery pipeline: discovery, exploration, data modeling, planning, TDD cycles, review gates, delivery. Each state declares an owner, skills, input/output artifacts, and guard conditions. The engine validates transitions. The agent executes. + +**Workflows are configurable.** The default flows cover spec-driven software development. Replace or extend them for your team's process: Kanban, SAFe, ITIL, or any custom pipeline. If it is a state machine, flowr can express it. + +**Agents execute it.** Each state's `owner` dispatches to the right specialist — Product Owner, System Architect, Data Architect, Software Engineer, Reviewer, Release Engineer — loaded with the skills and knowledge the state names. Input/output contracts constrain scope. Evidence gates prevent premature transitions. + +**Branch discipline is explicit.** Every state declares `git: main` or `git: feature`. Project-phase work commits to main. Feature work commits to a feature branch. No ambiguity about where changes belong. + +**The contract is compiled, not just validated.** Before any source `.py` exists, `simulate-contracts` walks the staged contract surface hop-by-hop — the way a compiler walks an AST — simulating how the real app would run against the data model and the requirements, and journaling one observation per hop. Spec-diff catches what two implementations could both satisfy. Build-implied gaps catch effects with no mechanism, side effects no observer sees, and models that disagree. A spec that survives this gate is a spec worth building. + +**Data is modeled before it is planned.** A dedicated `model-data-schema` state runs at plan entry: the Data Architect classifies the workload (OLTP / OLAP / hybrid), authors `data-model.md` as a binding contract, and traces every field to a stakeholder need. Downstream states — test stubs, source stubs, simulation — read it as a required input. No more "we built the contract surface, then discovered the schema was wrong." + +**Simplicity is a traced requirement.** Each interview funnel level asks a simplicity question — smallest surface, speculative vs grounded, load-bearing vs collapsible — and `consolidate-interview` drops speculative items before they become contracts. The `review-test-stubs` gate runs an inverted-traceability check (every test maps to a finding, or it goes) alongside a vacuous-assertion sweep that names five smells: hasattr-only, no-op helper, lower-bound-only, constant-satisfiable, tautology. A contract surface that survives this is neither over- nor under-engineered. + +**Replay is unambiguous.** HTTP adapters replay through `vcr.use_cassette()`; CLI subprocess tests use `pytester`; library-boundary adapters (ddgs, primp) use `monkeypatch`. The skill layer names the kind and the fixture — no agent picks the wrong replay mechanism again. + +--- + +## Quick start + +### New project from the copier template + +temple8 is a [copier](https://copier.readthedocs.io/) template. `copier copy` +renders `pyproject.toml` + a fresh `README.md`, creates the package and the +test skeleton, and hands you a new repo ready for the first +`flowr session init` — without inheriting temple8's own git history. + +```bash uv tool install copier copier copy gh:nullhack/temple8 my-project +cd my-project +curl -LsSf https://astral.sh/uv/install.sh | sh # skip if uv is already installed +uv sync --all-extras +opencode && @setup-project # personalise for your project +uv run task test && uv run task lint && uv run task static-check ``` Answer the questionnaire (project and package name, description, author, -version, repo URL, optional git reset, and which optional layers to keep). -Copier renders `pyproject.toml` + the README, creates the package and the test -skeleton, and hands you a fresh repo ready for the first `flowr session init`. - -The `project-instantiator` agent and its `instantiate-project` skill (in -`.opencode/`) guide the same flow end to end — gather the parameters, run the -copy, verify, and start the first pipeline session. They live in the template -and are excluded from instances. - -## Scope - -**In** — the methodology only: flow definitions, the agent/skill/knowledge -layer, document templates, CI, the conftest pending-marker hook, the copier -template, and the pyproject tooling. - -**Out** — everything an instance owns: an application package, tests, -migrations, cassettes, `docs/glossary.md`, `docs/state.md`. These live in a -project instantiated from this template, not in temple8 itself. - -## What an instance gets - -- `pyproject.toml` rendered with the project's name, package, and tooling. -- a fresh `README.md` from the instance template. -- `/__init__.py` and the `tests/{integration,e2e,cassettes,fixtures}/` skeleton. -- `.env.example` (the committed env contract). -- the whole methodology layer (`.opencode/`, `.flowr/`, `.templates/`) verbatim. -- a fresh git history (optional, default on). - -Optional layers an instance may keep or drop at instantiation: the `design/` -knowledge + asset templates (for projects with a UI surface) and `docs/research/` -(the source-card reference library behind the knowledge citations). - -## Where things live - -| Path | Holds | -|---|---| -| `copier.yml` | the instantiation questionnaire + tasks | -| `pyproject.toml.jinja`, `README.md.jinja` | the rendered instance files | -| `.flowr/flows/` | the six flow definitions | -| `.opencode/` | agents, skills, knowledge (methodology, requirements, software-craft, workflow, architecture, writing, design) | -| `.templates/` | document templates — glossary, state, research card, ADR, `.env.example`, social-card, logo | -| `.github/workflows/` | CI — ruff + flowr validate always on; pyright/stubtest/pytest guarded on package+tests | -| `docs/research/` | human-reference sources behind the knowledge citations | - -## Workflow - -The staged-contract pipeline runs discover → explore → plan → build → deliver → -shipped, driven one state at a time through flowr. See `AGENTS.md` for the -binding constraints, the driving loop, and the flowr commands. +version, repo URL, optional git reset, and which optional layers to keep — +design knowledge + asset templates, and the `docs/research/` reference +library). The `project-instantiator` agent and its `instantiate-project` skill +(in `.opencode/`) guide the same flow end to end — gather the parameters, run +the copy, verify, and start the first pipeline session. They live in the +template and are excluded from instances. + +### Clone the template directly + +```bash +git clone https://github.com/nullhack/temple8 +cd temple8 +curl -LsSf https://astral.sh/uv/install.sh | sh # skip if uv is already installed +uv sync --all-extras +opencode && @setup-project # personalise for your project +uv run task test && uv run task lint && uv run task static-check +``` + +### Existing project + +```bash +pip install agents-smith +smith clone # adds temple8's agents, flows, skills, and knowledge +``` + +--- + +## Commands + +```bash +uv run task test # full suite + coverage +uv run task test-fast # fast, no coverage (use during TDD loop) +uv run task test-build # full suite + HTML/coverage/hypothesis report +uv run task lint # ruff check (dev: bug-catchers) +uv run task lint-merge # merge: + SIM/RUF + ruff format +uv run task static-check # pyright type checking +uv run task stubtest # mypy.stubtest against the package stubs +uv run task validate-flows # flowr validate on every flow YAML +uv run task strip-docstrings # strip docstrings from a source .py (tdd select) +uv run task run # run the app +``` + +--- + +## The pipeline + +``` +discover → explore → plan → build → deliver → shipped +``` + +| Subflow | What happens | Entry state | +|---|---|---| +| discover | interview funnel → glossary of ubiquitous language | `interview-general` | +| explore | ground external services in recorded vcrpy cassettes | `select-external-target` | +| plan | data model → test stubs → review → test bodies → source stubs → simulate | `model-data-schema` | +| build | one contract per cycle: red → green → refactor → review → ship | `select-build-target` | +| deliver | squash-merge to `dev`, regenerate docstrings, whole-suite gates | `merge-to-dev` | + +`flowr` is the single router. Every state change runs through it — no improvised routing, no skipping states. The state's contract is binding: every input artifact must exist before work starts, and work writes only to the declared output artifacts. CI (`ruff` / `pyright` / `mypy.stubtest` / `pytest`) is the enforcement backstop for evidence the dispatched agent asserts. + +See `AGENTS.md` for the binding constraints and the driving loop. + +--- + +## FAQ + +### How is this different from Kiro? + +temple8 evolved over years of accumulated practice, not as a response to Kiro. Both identified the same pain points in AI-assisted development. The standards differ: Kiro uses EARS notation and property-based testing; temple8 uses BDD, TDD, and DDD with three-tier progressive review and a compiler-style spec simulation gate. Kiro is a cloud IDE on Bedrock. temple8 is a local project template with any LLM. MIT licensed, zero cost. + +### How is this different from Cursor or Copilot? + +Cursor and Copilot help write code. temple8 provides the process that decides what to write, in what order, and what review it passes before shipping. Think of them as the engine and temple8 as the map. Use both together. + +### How does this relate to Claude Code or opencode? + +Claude Code and opencode are general-purpose agent runners. temple8 gives them a process: YAML state machines, scoped agent roles, and evidence-based transitions. Without temple8, they follow prompts. With it, they follow a workflow. + +### Do I need to replace my existing tools? + +No. temple8 is a project template: flows, agent definitions, skills, and knowledge files you drop into any Python project. Keep your editor. Bring your own LLM via opencode or a compatible agent runner. Already have a Python project? Use [agents-smith](https://github.com/nullhack/agents-smith) to add temple8's agents, skills, and flows with one command: `smith clone`. + +### Is this only for software development? + +The default flows cover software development (discovery, exploration, data modeling, TDD cycles, review). Any repeatable process with steps and conditions can be expressed as a flowr state machine: ops runbooks, compliance audits, content pipelines, incident response. + +### What changed in 10.0? + +A new `model-data-schema` state runs at plan entry, producing `data-model.md` as a binding input to every downstream plan state. `simulate-contracts` is now a compiler: it walks the contract surface hop-by-hop, journals one observation per hop, runs a spec-diff, and surfaces build-implied gaps before any source `.py` is written. The `review-test-stubs` gate adds a vacuous-assertion sweep (five named smells) and an inverted-traceability (`scope-minimal`) check. The interview funnel asks a simplicity question at every level and drops speculative items before they become contracts. Replay is unambiguous: `vcr.use_cassette()` for HTTP, `pytester` for CLI, `monkeypatch` for library boundaries. + +--- + +## Documentation + +- **[Product Definition](https://nullhack.github.io/temple8/)**: product boundaries, users, and scope +- **[System Overview](https://nullhack.github.io/temple8/)**: architecture, domain model, module structure, and constraints +- **[Glossary](https://nullhack.github.io/temple8/)**: living domain glossary +- **`AGENTS.md`**: binding constraints and the state-driving loop +- **`.opencode/knowledge/`**: the methodology, requirements, software-craft, workflow, architecture, writing, and design reference layer + +--- + +## License + +MIT. See [LICENSE](LICENSE). + +**Author:** [@nullhack](https://github.com/nullhack) · [Documentation](https://nullhack.github.io/temple8) + + +[contributors-shield]: https://img.shields.io/github/contributors/nullhack/temple8.svg?style=for-the-badge +[contributors-url]: https://github.com/nullhack/temple8/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/nullhack/temple8.svg?style=for-the-badge +[forks-url]: https://github.com/nullhack/temple8/network/members +[stars-shield]: https://img.shields.io/github/stars/nullhack/temple8.svg?style=for-the-badge +[stars-url]: https://github.com/nullhack/temple8/stargazers +[issues-shield]: https://img.shields.io/github/issues/nullhack/temple8.svg?style=for-the-badge +[issues-url]: https://github.com/nullhack/temple8/issues +[license-shield]: https://img.shields.io/badge/license-MIT-green?style=for-the-badge +[license-url]: https://github.com/nullhack/temple8/blob/main/LICENSE diff --git a/docs/assets/banner.svg b/docs/assets/banner.svg new file mode 100644 index 00000000..d5e6ae03 --- /dev/null +++ b/docs/assets/banner.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TEMPLE·VIII + + TEMPLE·VIII + + + + + diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 00000000..040db175 --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pyproject.toml b/pyproject.toml index 4348abee..4ad5e3d3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "temple8" -version = "9.4.0" +version = "10.0.0" description = "Spec-driven agent orchestration template with YAML flow definitions, multi-agent dispatch, and BDD traceability" readme = "README.md" requires-python = ">=3.13" diff --git a/uv.lock b/uv.lock index c81f9233..8fa1862c 100644 --- a/uv.lock +++ b/uv.lock @@ -1103,7 +1103,7 @@ wheels = [ [[package]] name = "temple8" -version = "9.4.0" +version = "10.0.0" source = { virtual = "." } [package.optional-dependencies] From fdb7f1742e3661ec126f7003461d175da4f2c69c Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 7 Jul 2026 03:52:51 -0400 Subject: [PATCH 26/28] refactor: move conftest.py to tests/ for scoped test-only hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - conftest.py → tests/conftest.py (pending-marker hook is test-only; root placement was a template-portability holdover, not a pytest best practice; tests/ is created at copier instantiation so the hook survives) - instantiate-project skill: update skeleton verification to expect tests/conftest.py rather than root conftest.py - README: remove the 'What changed in 10.0?' section --- .opencode/skills/instantiate-project/SKILL.md | 2 +- README.md | 4 ---- conftest.py => tests/conftest.py | 0 3 files changed, 1 insertion(+), 5 deletions(-) rename conftest.py => tests/conftest.py (100%) diff --git a/.opencode/skills/instantiate-project/SKILL.md b/.opencode/skills/instantiate-project/SKILL.md index 5c49300c..8b9b3299 100644 --- a/.opencode/skills/instantiate-project/SKILL.md +++ b/.opencode/skills/instantiate-project/SKILL.md @@ -7,7 +7,7 @@ description: "Create a new project instance from the temple8 template via copier 1. Confirm the destination directory does not exist or is empty; IF `copier copy` would clobber existing work THEN stop and ask the user where to create the project. 2. Run `copier copy gh:nullhack/temple8 ` (or the local template path if offline). Answer the questionnaire: `project_name`, `package_name` (defaults from `project_name`), `description`, `repo_url`, `version`, `author_name`, `author_email`, `keep_design`, `keep_research`, `reset_git`. -3. `cd` into the new project and verify the skeleton: `/__init__.py` exists; `tests/{integration,e2e,cassettes,fixtures}/` exist; `pyproject.toml` and `README.md` are rendered (no `{{ }}` placeholders remain); `.opencode/`, `.flowr/`, `.templates/`, `AGENTS.md`, `conftest.py`, `.github/` are present and unchanged. +3. `cd` into the new project and verify the skeleton: `/__init__.py` exists; `tests/{integration,e2e,cassettes,fixtures}/` and `tests/conftest.py` exist; `pyproject.toml` and `README.md` are rendered (no `{{ }}` placeholders remain); `.opencode/`, `.flowr/`, `.templates/`, `AGENTS.md`, `.github/` are present and unchanged. 4. Run `uv sync --extra dev` to materialise the venv. 5. Verify the gates load: `bash -c 'for f in .flowr/flows/*.yaml; do uv run python -m flowr validate "$f"; done'` — all six must report `{valid: true}`; `uv run ruff check .` must pass; `uv run pytest --collect-only -q` must collect zero tests cleanly. 6. Initialise the first session: `uv run python -m flowr session init pipeline-flow --name default`; confirm it lands at `discovery-flow/interview-general`. diff --git a/README.md b/README.md index b824f625..2b4e645c 100644 --- a/README.md +++ b/README.md @@ -176,10 +176,6 @@ No. temple8 is a project template: flows, agent definitions, skills, and knowled The default flows cover software development (discovery, exploration, data modeling, TDD cycles, review). Any repeatable process with steps and conditions can be expressed as a flowr state machine: ops runbooks, compliance audits, content pipelines, incident response. -### What changed in 10.0? - -A new `model-data-schema` state runs at plan entry, producing `data-model.md` as a binding input to every downstream plan state. `simulate-contracts` is now a compiler: it walks the contract surface hop-by-hop, journals one observation per hop, runs a spec-diff, and surfaces build-implied gaps before any source `.py` is written. The `review-test-stubs` gate adds a vacuous-assertion sweep (five named smells) and an inverted-traceability (`scope-minimal`) check. The interview funnel asks a simplicity question at every level and drops speculative items before they become contracts. Replay is unambiguous: `vcr.use_cassette()` for HTTP, `pytester` for CLI, `monkeypatch` for library boundaries. - --- ## Documentation diff --git a/conftest.py b/tests/conftest.py similarity index 100% rename from conftest.py rename to tests/conftest.py From e1267bb63d43aa6526719fcfff5b2a73e0367e34 Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 7 Jul 2026 03:56:47 -0400 Subject: [PATCH 27/28] =?UTF-8?q?docs:=20rewrite=20README=20=E2=80=94=20te?= =?UTF-8?q?st-driven=20narrative,=20tighter=20prose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - tagline and intro reframed test-driven (tests are the contract) - 'What it does' trimmed from 7 verbose bullets to 5 tight ones; dropped the data-modeling/simplicity/replay essays (live in the skills/knowledge layer, not the README) - 'Anyone evaluating spec-driven development' → 'test-driven' - Kiro comparison updated to frame the contract simulation gate as walking the test surface, not 'spec simulation' - FAQ comparisons retained (Kiro, Cursor/Copilot, Claude Code/opencode, existing tools, scope) --- README.md | 73 ++++++++++++++++++++----------------------------------- 1 file changed, 27 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 2b4e645c..f29cc97a 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,15 @@ [![Python](https://img.shields.io/badge/python-%E2%89%A53.13-blue?style=for-the-badge)](https://www.python.org/downloads/) [![Version](https://img.shields.io/badge/version-10.0.0-5c3d1e?style=for-the-badge)](https://github.com/nullhack/temple8/releases) -**From spec to shipped: state-machine orchestration for spec-driven agent work. Any workflow. Any LLM. Zero lock-in.** +**Test-driven agent orchestration. Any workflow. Any LLM. Zero lock-in.** --- -You have tried to ship features with AI assistants. The agent writes code, you review it, and somehow the spec still drifts from the implementation. Tests pass but the feature doesn't match what stakeholders asked for. Architecture decisions vanish into commit messages nobody reads. The review cycle is a black box: either everything passes or nothing does, with no structured progression. And the spec itself is never tested — a contract surface that two implementations could satisfy, or that no implementation could, sails through review undetected. +You ship features with AI assistants. The agent writes code, you review it, the spec still drifts. Tests pass but the feature doesn't match what stakeholders asked for. The review cycle is a black box. -**temple8 replaces ad-hoc agent orchestration with state machines that route every step through the right agent with the right skills at the right time, and treats the contract surface itself as a compiler would: simulated end-to-end before any source exists.** - -Flow definitions in YAML declare what happens at each state: who owns it, what they may read, what they must produce, and which conditions gate the next transition. No agent guesses what to do next. No step is skipped. Artifacts are scoped to each state's input/output contract. The contract is *compiled* — simulated hop-by-hop against the data model and the requirements — so a spec that two implementations could satisfy, or that one cannot, is caught before a single source file is written. +**temple8 makes tests the contract and a state machine the router.** Test stubs are authored up front from the interview, simulated before any source exists, then built red → green → refactor one contract at a time. `flowr` routes every state change through the right agent with the right skills; CI (`ruff` / `pyright` / `mypy.stubtest` / `pytest`) is the enforcement backstop. --- @@ -32,15 +30,15 @@ Flow definitions in YAML declare what happens at each state: who owns it, what t ### Developers moving from vibe coding to agentic engineering -You have shipped code with AI assistants and hit the wall: the agent writes code, you review it, the spec drifts. Vibe coding works for prototypes. It breaks at scale. temple8 replaces "prompt and pray" with spec-driven development: BDD scenarios from interviews, title-based traceability from Example to test function, red-green-refactor cycles enforced by default, a compiler-style simulation gate that disconfirms specs before code, and three-tier review that catches what linters miss — including vacuous assertions that pass without asserting anything. +Vibe coding works for prototypes, breaks at scale. temple8 replaces "prompt and pray" with: BDD scenarios from interviews, title-based traceability from Example to test function, red-green-refactor enforced by default, a contract simulation gate that disconfirms the test surface before code, and three-tier review that catches what linters miss — including vacuous assertions that pass without asserting. ### Teams wanting structured agent orchestration without lock-in -Your team follows a real methodology: Scrum, Kanban, SAFe, or something custom. Multi-agent orchestration should adapt to it, not the other way around. temple8 flows are YAML state machines you define, extend, or replace. Named specialists per state. No subscription, no vendor account, no code leaving your infrastructure. MIT licensed. +Your team follows Scrum, Kanban, SAFe, or something custom. Orchestration should adapt to it, not the other way around. temple8 flows are YAML state machines you define, extend, or replace. Named specialists per state. No subscription, no vendor account, no code leaving your infrastructure. MIT licensed. -### Anyone evaluating spec-driven development +### Anyone evaluating test-driven development -Spec-driven development is gaining traction across AI coding tools. You want to try it without committing to a cloud IDE or a monthly subscription. temple8 is a project template: clone it, run it locally with any LLM, see if the process discipline works for your team. Already have a Python project? Use [agents-smith](https://github.com/nullhack/agents-smith) to add temple8's agentic capabilities with one command. +You want to try it without a cloud IDE or monthly subscription. temple8 is a project template: clone it, run it locally with any LLM, see if the discipline works for your team. Already have a Python project? Use [agents-smith](https://github.com/nullhack/agents-smith) to add temple8's capabilities with one command. --- @@ -52,21 +50,15 @@ flowr next → see which transitions pass given your evidence flowr transition → advance to the next state with evidence ``` -**State machines route the work.** YAML flows define the delivery pipeline: discovery, exploration, data modeling, planning, TDD cycles, review gates, delivery. Each state declares an owner, skills, input/output artifacts, and guard conditions. The engine validates transitions. The agent executes. - -**Workflows are configurable.** The default flows cover spec-driven software development. Replace or extend them for your team's process: Kanban, SAFe, ITIL, or any custom pipeline. If it is a state machine, flowr can express it. - -**Agents execute it.** Each state's `owner` dispatches to the right specialist — Product Owner, System Architect, Data Architect, Software Engineer, Reviewer, Release Engineer — loaded with the skills and knowledge the state names. Input/output contracts constrain scope. Evidence gates prevent premature transitions. +**Tests are the contract.** Test stubs (`.pyi`) are authored up front from the interview, marked `pending`, then simulated against the data model before any source exists. A test surface two implementations could satisfy — or none could — is caught here, not in review. -**Branch discipline is explicit.** Every state declares `git: main` or `git: feature`. Project-phase work commits to main. Feature work commits to a feature branch. No ambiguity about where changes belong. +**State machines route the work.** YAML flows declare each state's owner, skills, input/output artifacts, and guard conditions. `flowr` validates every transition; no step is skipped or improvised. -**The contract is compiled, not just validated.** Before any source `.py` exists, `simulate-contracts` walks the staged contract surface hop-by-hop — the way a compiler walks an AST — simulating how the real app would run against the data model and the requirements, and journaling one observation per hop. Spec-diff catches what two implementations could both satisfy. Build-implied gaps catch effects with no mechanism, side effects no observer sees, and models that disagree. A spec that survives this gate is a spec worth building. +**Agents are dispatched, not prompted.** Each state names its specialist — Product Owner, System Architect, Data Architect, Software Engineer, Reviewer, Release Engineer — and the skills/knowledge to load. Input/output contracts constrain scope; evidence gates prevent premature transitions. -**Data is modeled before it is planned.** A dedicated `model-data-schema` state runs at plan entry: the Data Architect classifies the workload (OLTP / OLAP / hybrid), authors `data-model.md` as a binding contract, and traces every field to a stakeholder need. Downstream states — test stubs, source stubs, simulation — read it as a required input. No more "we built the contract surface, then discovered the schema was wrong." +**Branch per state.** `git: main` for project-phase work, `git: feature` for feature work. No ambiguity about where changes belong. -**Simplicity is a traced requirement.** Each interview funnel level asks a simplicity question — smallest surface, speculative vs grounded, load-bearing vs collapsible — and `consolidate-interview` drops speculative items before they become contracts. The `review-test-stubs` gate runs an inverted-traceability check (every test maps to a finding, or it goes) alongside a vacuous-assertion sweep that names five smells: hasattr-only, no-op helper, lower-bound-only, constant-satisfiable, tautology. A contract surface that survives this is neither over- nor under-engineered. - -**Replay is unambiguous.** HTTP adapters replay through `vcr.use_cassette()`; CLI subprocess tests use `pytester`; library-boundary adapters (ddgs, primp) use `monkeypatch`. The skill layer names the kind and the fixture — no agent picks the wrong replay mechanism again. +**One contract per cycle.** Build runs red → green → refactor → review → ship, one pending test at a time, until the backlog is empty. --- @@ -74,10 +66,7 @@ flowr transition → advance to the next state with evidence ### New project from the copier template -temple8 is a [copier](https://copier.readthedocs.io/) template. `copier copy` -renders `pyproject.toml` + a fresh `README.md`, creates the package and the -test skeleton, and hands you a new repo ready for the first -`flowr session init` — without inheriting temple8's own git history. +temple8 is a [copier](https://copier.readthedocs.io/) template. `copier copy` renders `pyproject.toml` + a fresh `README.md`, creates the package and the test skeleton, and hands you a new repo ready for the first `flowr session init` — without inheriting temple8's own git history. ```bash uv tool install copier @@ -89,13 +78,7 @@ opencode && @setup-project # personalise for your project uv run task test && uv run task lint && uv run task static-check ``` -Answer the questionnaire (project and package name, description, author, -version, repo URL, optional git reset, and which optional layers to keep — -design knowledge + asset templates, and the `docs/research/` reference -library). The `project-instantiator` agent and its `instantiate-project` skill -(in `.opencode/`) guide the same flow end to end — gather the parameters, run -the copy, verify, and start the first pipeline session. They live in the -template and are excluded from instances. +Answer the questionnaire (project and package name, description, author, version, repo URL, optional git reset, and which optional layers to keep — design knowledge + asset templates, and the `docs/research/` reference library). The `project-instantiator` agent and its `instantiate-project` skill (in `.opencode/`) guide the same flow end to end. They live in the template and are excluded from instances. ### Clone the template directly @@ -120,16 +103,16 @@ smith clone # adds temple8's agents, flows, skills, ## Commands ```bash -uv run task test # full suite + coverage -uv run task test-fast # fast, no coverage (use during TDD loop) -uv run task test-build # full suite + HTML/coverage/hypothesis report -uv run task lint # ruff check (dev: bug-catchers) -uv run task lint-merge # merge: + SIM/RUF + ruff format -uv run task static-check # pyright type checking -uv run task stubtest # mypy.stubtest against the package stubs -uv run task validate-flows # flowr validate on every flow YAML +uv run task test # full suite + coverage +uv run task test-fast # fast, no coverage (use during TDD loop) +uv run task test-build # full suite + HTML/coverage/hypothesis report +uv run task lint # ruff check (dev: bug-catchers) +uv run task lint-merge # merge: + SIM/RUF + ruff format +uv run task static-check # pyright type checking +uv run task stubtest # mypy.stubtest against the package stubs +uv run task validate-flows # flowr validate on every flow YAML uv run task strip-docstrings # strip docstrings from a source .py (tdd select) -uv run task run # run the app +uv run task run # run the app ``` --- @@ -148,9 +131,7 @@ discover → explore → plan → build → deliver → shipped | build | one contract per cycle: red → green → refactor → review → ship | `select-build-target` | | deliver | squash-merge to `dev`, regenerate docstrings, whole-suite gates | `merge-to-dev` | -`flowr` is the single router. Every state change runs through it — no improvised routing, no skipping states. The state's contract is binding: every input artifact must exist before work starts, and work writes only to the declared output artifacts. CI (`ruff` / `pyright` / `mypy.stubtest` / `pytest`) is the enforcement backstop for evidence the dispatched agent asserts. - -See `AGENTS.md` for the binding constraints and the driving loop. +`flowr` is the single router. Every state change runs through it. The state's contract is binding: every input artifact must exist before work starts; work writes only to the declared output artifacts. See `AGENTS.md` for the binding constraints and the driving loop. --- @@ -158,15 +139,15 @@ See `AGENTS.md` for the binding constraints and the driving loop. ### How is this different from Kiro? -temple8 evolved over years of accumulated practice, not as a response to Kiro. Both identified the same pain points in AI-assisted development. The standards differ: Kiro uses EARS notation and property-based testing; temple8 uses BDD, TDD, and DDD with three-tier progressive review and a compiler-style spec simulation gate. Kiro is a cloud IDE on Bedrock. temple8 is a local project template with any LLM. MIT licensed, zero cost. +Both identified the same pain points in AI-assisted development. The standards differ: Kiro uses EARS notation and property-based testing; temple8 uses BDD, TDD, and DDD with three-tier progressive review and a contract simulation gate that walks the test surface hop-by-hop before any source exists. Kiro is a cloud IDE on Bedrock. temple8 is a local project template with any LLM. MIT licensed, zero cost. ### How is this different from Cursor or Copilot? -Cursor and Copilot help write code. temple8 provides the process that decides what to write, in what order, and what review it passes before shipping. Think of them as the engine and temple8 as the map. Use both together. +Cursor and Copilot help write code. temple8 decides what to write, in what order, and what review it passes before shipping. They are the engine; temple8 is the map. Use both together. ### How does this relate to Claude Code or opencode? -Claude Code and opencode are general-purpose agent runners. temple8 gives them a process: YAML state machines, scoped agent roles, and evidence-based transitions. Without temple8, they follow prompts. With it, they follow a workflow. +Claude Code and opencode are general-purpose agent runners. temple8 gives them a process: YAML state machines, scoped agent roles, evidence-based transitions. Without temple8, they follow prompts. With it, they follow a workflow. ### Do I need to replace my existing tools? From f8ffd51b2fb4bf44b6299501b59d5782762b35fe Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 7 Jul 2026 04:31:59 -0400 Subject: [PATCH 28/28] =?UTF-8?q?chore(release):=20prep=20v10.0.0=20?= =?UTF-8?q?=E2=80=94=20test-driven=20description,=20explicit=20build-syste?= =?UTF-8?q?m,=20release=20workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pyproject.toml description: spec-driven → test-driven (aligns README + About) - add [build-system] (setuptools>=68) per PEP 517; was implicit - [tool.setuptools] packages: ['app'] → [] (template ships no package; instances create app/ at copier time; wheel is metadata-only for PyPI discoverability, matching past release shape) - add .github/workflows/release.yml: on release.published, uv build + trusted-publishing to PyPI (id-token: write, pypa action, no token) + upload wheel/sdist to the release assets --- .github/workflows/release.yml | 52 +++++++++++++++++++++++++++++++++++ pyproject.toml | 8 ++++-- uv.lock | 2 +- 3 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..26093cc8 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,52 @@ +name: Release + +on: + release: + types: [published] + workflow_dispatch: + +permissions: + contents: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v3 + - run: uv python install 3.13 + - run: uv sync --extra dev + - run: uv build + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + if-no-files-found: error + + publish-pypi: + needs: build + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - uses: pypa/gh-action-pypi-publish@release/v1 + + upload-release-assets: + needs: build + runs-on: ubuntu-latest + permissions: + contents: write + if: github.event_name == 'release' + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - run: gh release upload "$GITHUB_REF_NAME" dist/* + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/pyproject.toml b/pyproject.toml index 4ad5e3d3..35c13f8b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,11 @@ +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + [project] name = "temple8" version = "10.0.0" -description = "Spec-driven agent orchestration template with YAML flow definitions, multi-agent dispatch, and BDD traceability" +description = "Test-driven agent orchestration template with YAML flow definitions, staged test contracts, and BDD traceability" readme = "README.md" requires-python = ">=3.13" license = { file = "LICENSE" } @@ -42,7 +46,7 @@ default_flow = "pipeline-flow" default_session = "default" [tool.setuptools] -packages = ["app"] +packages = [] [tool.ruff.lint] ignore = [] diff --git a/uv.lock b/uv.lock index 8fa1862c..c985e2db 100644 --- a/uv.lock +++ b/uv.lock @@ -1104,7 +1104,7 @@ wheels = [ [[package]] name = "temple8" version = "10.0.0" -source = { virtual = "." } +source = { editable = "." } [package.optional-dependencies] dev = [