From b781cdc40d7111e41b5df6cb734c4f3eac3a4c2b Mon Sep 17 00:00:00 2001 From: nullhack Date: Wed, 6 May 2026 12:00:13 -0400 Subject: [PATCH 1/4] =?UTF-8?q?v8.2.1=20Rigorous=20Euclid=20=E2=80=94=20AI?= =?UTF-8?q?=20writing=20markers,=20flowr=201.0.0,=20em=20dash=20cleanup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Release v8.2.1 (Rigorous Euclid): AI writing marker taxonomy knowledge file (6-tier, evidence-based), repo-wide em dash cleanup (~930 replacements across ~120 files), Tier 1/2/6 AI marker word fixes (leveraging, ensures, significantly, paramount), flowr 1.0.0 specification adoption (~= operator removed, when forms, conformance levels, reserved keys registry), 5 AI research notes, research file for flowr 1.0.0 spec. --- .flowr/flows/architecture-flow.yaml | 28 +- .flowr/flows/development-flow.yaml | 5 +- .flowr/flows/discovery-flow.yaml | 14 +- .flowr/flows/document-dependencies.yaml | 201 ++++++++ .flowr/flows/feature-development-flow.yaml | 4 +- .flowr/flows/main-flow.yaml | 6 +- .flowr/flows/planning-flow.yaml | 3 +- .flowr/flows/review-gate-flow.yaml | 5 +- .flowr/sessions/doc-audit.yaml | 9 + .flowr/viz/app.js | 4 +- .flowr/viz/generate-flowviz-data.py | 2 +- .opencode/agents/design-agent.md | 2 +- .opencode/agents/domain-expert.md | 2 +- .opencode/agents/product-owner.md | 2 +- .opencode/agents/reviewer.md | 2 +- .opencode/agents/setup-agent.md | 2 +- .opencode/agents/software-engineer.md | 2 +- .opencode/agents/system-architect.md | 2 +- .../knowledge/agent-design/principles.md | 24 +- .opencode/knowledge/architecture/adr.md | 16 +- .../knowledge/architecture/assessment.md | 16 +- .../knowledge/architecture/contract-design.md | 14 +- .../architecture/quality-attributes.md | 14 +- .../knowledge/architecture/reconciliation.md | 18 +- .../architecture/technical-design.md | 18 +- .opencode/knowledge/design/color-systems.md | 24 +- .opencode/knowledge/design/identity-design.md | 12 +- .opencode/knowledge/design/project-assets.md | 30 +- .opencode/knowledge/design/visual-harmony.md | 18 +- .../domain-modeling/context-mapping.md | 14 +- .../domain-modeling/event-storming.md | 24 +- .../knowledge/knowledge-design/principles.md | 26 +- .../knowledge/requirements/decomposition.md | 18 +- .../requirements/feature-discovery.md | 24 +- .opencode/knowledge/requirements/gherkin.md | 48 +- .../requirements/interview-techniques.md | 30 +- .opencode/knowledge/requirements/invest.md | 54 +- .opencode/knowledge/requirements/moscow.md | 23 +- .../knowledge/requirements/post-mortem.md | 16 +- .../knowledge/requirements/pre-mortem.md | 50 +- .../requirements/ubiquitous-language.md | 16 +- .opencode/knowledge/requirements/wsjf.md | 22 +- .../knowledge/skill-design/principles.md | 10 +- .../knowledge/software-craft/code-review.md | 41 +- .../software-craft/design-patterns.md | 28 +- .../software-craft/git-conventions.md | 18 +- .../software-craft/object-calisthenics.md | 52 +- .../software-craft/refactoring-techniques.md | 40 +- .../knowledge/software-craft/refactoring.md | 36 +- .../software-craft/smell-catalogue.md | 20 +- .opencode/knowledge/software-craft/solid.md | 34 +- .../knowledge/software-craft/stub-design.md | 38 +- .opencode/knowledge/software-craft/tdd.md | 52 +- .../knowledge/software-craft/test-design.md | 28 +- .../knowledge/software-craft/versioning.md | 16 +- .../knowledge/workflow/flowr-operations.md | 26 +- .opencode/knowledge/workflow/flowr-spec.md | 92 ++-- .../workflow/todo-anchor-protocol.md | 20 +- .../knowledge/writing/ai-language-markers.md | 149 ++++++ .opencode/skills/accept-feature/SKILL.md | 4 +- .opencode/skills/analyze-root-cause/SKILL.md | 2 +- .opencode/skills/break-down-feature/SKILL.md | 4 +- .../skills/commit-implementation/SKILL.md | 2 +- .opencode/skills/confirm-baseline/SKILL.md | 2 +- .opencode/skills/create-py-stubs/SKILL.md | 4 +- .opencode/skills/define-done/SKILL.md | 4 +- .../define-ubiquitous-language/SKILL.md | 2 +- .opencode/skills/design-assets/SKILL.md | 10 +- .opencode/skills/design-colors/SKILL.md | 4 +- .../skills/design-technical-solution/SKILL.md | 2 +- .opencode/skills/discover-features/SKILL.md | 4 +- .opencode/skills/draft-adr/SKILL.md | 4 +- .opencode/skills/implement-minimum/SKILL.md | 4 +- .opencode/skills/model-domain/SKILL.md | 4 +- .opencode/skills/refactor/SKILL.md | 4 +- .opencode/skills/review-architecture/SKILL.md | 2 +- .opencode/skills/review-conventions/SKILL.md | 8 +- .opencode/skills/review-design/SKILL.md | 16 +- .opencode/skills/review-structure/SKILL.md | 12 +- .opencode/skills/select-feature/SKILL.md | 4 +- .opencode/skills/setup-apply/SKILL.md | 4 +- .opencode/skills/setup-assess/SKILL.md | 4 +- .opencode/skills/setup-configure/SKILL.md | 12 +- .opencode/skills/structure-project/SKILL.md | 4 +- .opencode/skills/verify-traceability/SKILL.md | 2 +- .opencode/skills/write-bdd-features/SKILL.md | 8 +- .opencode/skills/write-test/SKILL.md | 6 +- .templates/docs/spec/domain_model.md.template | 56 +-- .../docs/spec/event_storming.md.template | 47 ++ .templates/docs/spec/system.md.template | 114 ----- .../docs/spec/technical_design.md.template | 14 +- AGENTS.md | 58 +-- CHANGELOG.md | 37 +- README.md | 24 +- docs/audit/document-landscape-audit.md | 461 ++++++++++++++++++ docs/branding/branding.md | 30 +- ..._20260501_missing-feature-test-template.md | 4 +- .../PM_20260501_reviewer-fixing-code.md | 12 +- .../ai_writing_markers_community.md | 51 ++ .../artificial-intelligence/liu_et_al_2023.md | 2 +- .../pangram_labs_ngrams.md | 46 ++ .../scientometrics_delve_2024.md | 46 ++ .../textvisualization_corpus.md | 48 ++ .../writehuman_2026.md | 49 ++ .../design/accessibility/w3c_wcag21_2018.md | 6 +- docs/research/design/visual/airey_2010.md | 8 +- docs/research/design/visual/albers_1963.md | 12 +- docs/research/design/visual/arnheim_1954.md | 6 +- docs/research/design/visual/biederman_1987.md | 6 +- docs/research/design/visual/hicks_2011.md | 6 +- docs/research/design/visual/itten_1961.md | 8 +- docs/research/design/visual/kare_1984.md | 10 +- docs/research/design/visual/lupton_2010.md | 12 +- .../design/visual/muller_brockmann_1981.md | 8 +- docs/research/design/visual/rand_1985.md | 10 +- .../research/design/visual/wertheimer_1923.md | 6 +- .../documentation/procida_2021.md | 2 +- .../domain-modeling/brandolini_2012.md | 2 +- .../domain-modeling/evans_2003.md | 2 +- .../domain-modeling/vernon_2013.md | 2 +- .../cognitive/craik_lockhart_1972.md | 12 +- .../cognitive/fisher_geiselman_1987.md | 6 +- .../psychology/cognitive/flanagan_1954.md | 8 +- .../psychology/cognitive/gollwitzer_1999.md | 10 +- .../cognitive/hattie_timperley_2007.md | 12 +- .../psychology/cognitive/kahneman_2011.md | 6 +- .../psychology/cognitive/klein_1998.md | 10 +- .../cognitive/mcdaniel_einstein_2000.md | 6 +- .../psychology/cognitive/miller_1956.md | 8 +- .../cognitive/reynolds_gutman_1988.md | 8 +- .../cognitive/tversky_kahneman_1974.md | 6 +- .../psychology/social/cialdini_2001.md | 8 +- .../psychology/social/mellers_et_al_2001.md | 8 +- .../psychology/social/rogers_farson_1957.md | 6 +- .../psychology/social/tetlock_1985.md | 6 +- .../architecture/bass_et_al_2021.md | 14 +- .../architecture/boehm_1991.md | 8 +- .../architecture/brown_2018.md | 12 +- .../architecture/cockburn_2005.md | 6 +- .../architecture/conway_1968.md | 8 +- .../architecture/fielding_2000.md | 6 +- .../architecture/fowler_2003.md | 8 +- .../architecture/hohpe_woolf_2003.md | 6 +- .../kazman_klein_clements_2000.md | 6 +- .../architecture/kruchten_1995.md | 8 +- .../architecture/martin_2012_clean.md | 12 +- .../architecture/nygard_2011.md | 10 +- .../architecture/parnas_1972.md | 6 +- .../architecture/skelton_pais_2019.md | 10 +- .../process/beck_1999_yagni.md | 2 +- .../process/beyer_et_al_2016.md | 2 +- .../process/calver_2020.md | 2 +- .../process/clegg_barker_1994.md | 2 +- .../process/fagan_1976.md | 2 +- .../process/nullhack_flowr_0.4.0.md | 59 --- .../process/nullhack_flowr_1.0.0.md | 63 +++ .../process/preston-werner_2013.md | 2 +- .../procedural_checklists_synthesis.md | 14 +- .../process/reinertsen_2009.md | 2 +- .../software-engineering/quality/bay_2008.md | 6 +- .../software-engineering/quality/beck_2002.md | 4 +- .../quality/boehm_1981.md | 16 +- .../quality/demillo_lipton_sayward_1978.md | 2 +- .../quality/feathers_2004.md | 6 +- .../quality/fowler_1999.md | 6 +- .../quality/freeman_pryce_2009.md | 2 +- .../quality/gamma_et_al_1994.md | 6 +- .../quality/google_testing_2013.md | 2 +- .../quality/maciver_2016.md | 4 +- .../quality/martin_2000_solid.md | 8 +- .../quality/martin_2017_first_class_tests.md | 2 +- .../quality/meszaros_2007.md | 8 +- .../quality/north_2006.md | 2 +- .../quality/shvets_2014.md | 6 +- .../requirements/christel_kang_1992.md | 2 +- .../requirements/cohn_2004.md | 8 +- .../requirements/kano_et_al_1984.md | 2 +- .../requirements/patton_2014.md | 6 +- .../requirements/wake_2003.md | 2 +- .../requirements/wynne_2015.md | 2 +- pyproject.toml | 4 +- 181 files changed, 2173 insertions(+), 1234 deletions(-) create mode 100644 .flowr/flows/document-dependencies.yaml create mode 100644 .flowr/sessions/doc-audit.yaml create mode 100644 .opencode/knowledge/writing/ai-language-markers.md create mode 100644 .templates/docs/spec/event_storming.md.template delete mode 100644 .templates/docs/spec/system.md.template create mode 100644 docs/audit/document-landscape-audit.md create mode 100644 docs/research/computer-science/artificial-intelligence/ai_writing_markers_community.md create mode 100644 docs/research/computer-science/artificial-intelligence/pangram_labs_ngrams.md create mode 100644 docs/research/computer-science/artificial-intelligence/scientometrics_delve_2024.md create mode 100644 docs/research/computer-science/artificial-intelligence/textvisualization_corpus.md create mode 100644 docs/research/computer-science/artificial-intelligence/writehuman_2026.md delete mode 100644 docs/research/software-engineering/process/nullhack_flowr_0.4.0.md create mode 100644 docs/research/software-engineering/process/nullhack_flowr_1.0.0.md diff --git a/.flowr/flows/architecture-flow.yaml b/.flowr/flows/architecture-flow.yaml index 5a830c9c..2058d41c 100644 --- a/.flowr/flows/architecture-flow.yaml +++ b/.flowr/flows/architecture-flow.yaml @@ -1,5 +1,5 @@ flow: architecture-flow -version: 5.0.0 +version: 6.0.0 exits: - complete - needs_discovery @@ -15,21 +15,18 @@ states: in: - product_definition.md - domain_model.md - - system.md - - technical_design.md - - context_map.md + - "technical_design.md" # optional + - "context_map.md" # optional out: - product_definition.md: - deployment - quality_attributes conditions: architecture_complete: - system_md: ==exists technical_design_md: ==exists context_map_md: ==exists deployment_matches_codebase: ==verified architecture_exists: - system_md: ==exists technical_design_md: ==exists context_map_md: ==exists no_architecture_exists: @@ -74,7 +71,7 @@ states: - id: technical-design attrs: - description: "SA designs the technical solution — architectural style, stack, module structure, API/event contracts, interface definitions — and updates the system overview" + description: "SA designs the technical solution — architectural style, stack, module structure, API/event contracts, interface definitions" owner: SA git: main skills: @@ -83,8 +80,8 @@ states: - context_map.md - domain_model.md - glossary.md - - system.md - product_definition.md + - "technical_design.md" # optional out: - technical_design.md: - architectural_style @@ -97,18 +94,13 @@ states: - c4_diagrams - dependencies - configuration_keys - - system.md: - - context - - container - - module_structure - - delivery next: done: review-signoff needs_decisions: adr-draft - id: adr-draft attrs: - description: "SA documents architecturally significant decisions as ADRs and records key decisions and active constraints in system.md" + description: "SA documents architecturally significant decisions as ADRs and records key decisions and active constraints in technical_design.md" owner: SA git: main skills: @@ -119,9 +111,8 @@ states: - domain_model.md - product_definition.md - glossary.md - - system.md out: - - system.md: + - technical_design.md: - key_decisions - active_constraints - adr/.md @@ -138,8 +129,7 @@ states: in: - context_map.md - technical_design.md - - system.md - - adr/*.md + - "adr/*.md" # optional - product_definition.md - domain_model.md - glossary.md @@ -157,4 +147,4 @@ states: - architecture_approved - committed_to_main_locally inconsistent: architecture-assessment - needs_discovery: needs_discovery \ No newline at end of file + needs_discovery: needs_discovery diff --git a/.flowr/flows/development-flow.yaml b/.flowr/flows/development-flow.yaml index 6f9131ee..375bd44c 100644 --- a/.flowr/flows/development-flow.yaml +++ b/.flowr/flows/development-flow.yaml @@ -1,5 +1,5 @@ flow: development-flow -version: 5.0.0 +version: 6.0.0 params: [feature_name] exits: - done @@ -19,7 +19,6 @@ states: - domain_model.md - glossary.md - context_map.md - - adr/*.md - product_definition.md out: - git_branch @@ -53,7 +52,7 @@ states: description: "R independently verifies implementation across three tiers — design, structure, and conventions — before commit" git: feature flow: review-gate-flow - flow-version: "^3" + flow-version: "^4" next: pass: commit fail: tdd-cycle diff --git a/.flowr/flows/discovery-flow.yaml b/.flowr/flows/discovery-flow.yaml index 464ccb59..c6791474 100644 --- a/.flowr/flows/discovery-flow.yaml +++ b/.flowr/flows/discovery-flow.yaml @@ -1,5 +1,5 @@ flow: discovery-flow -version: 5.0.0 +version: 6.0.0 exits: - complete @@ -12,7 +12,7 @@ states: skills: - conduct-interview in: - - interview-notes/*.md + - "interview-notes/*.md" # optional out: - interview-notes/.md: - pain_points @@ -34,7 +34,7 @@ states: in: - interview-notes/*.md out: - - domain_model.md: + - event_storming.md: - event_map - context_candidates - aggregate_candidates @@ -51,7 +51,8 @@ states: - define-ubiquitous-language in: - interview-notes/*.md - - domain_model.md + - event_storming.md + - "domain_model.md" # optional out: - glossary.md next: @@ -67,7 +68,7 @@ states: - model-domain in: - glossary.md - - domain_model.md + - event_storming.md out: - domain_model.md: - bounded_contexts @@ -116,8 +117,7 @@ states: - product_definition.md - domain_model.md - glossary.md - - interview-notes/*.md - - technical_design.md + - "technical_design.md" # optional out: - features/.feature: - title diff --git a/.flowr/flows/document-dependencies.yaml b/.flowr/flows/document-dependencies.yaml new file mode 100644 index 00000000..f0c962c2 --- /dev/null +++ b/.flowr/flows/document-dependencies.yaml @@ -0,0 +1,201 @@ +flow: document-dependencies +version: 6.0.0 +exits: [standalone] + +states: + - id: interview-notes + attrs: + description: "Raw stakeholder research — pain points, goals, terms, quality attributes" + role: raw-source + audience: business + produced_by: "discovery → stakeholder-interview" + observation: "Only read by synthesis states (domain-model, glossary). Downstream states read synthesized documents instead of raw notes." + sections: + - "General (Q&A)" + - "Feature: (Q&A)" + - "Quality Attributes" + - "Pain Points Identified" + - "Business Goals Identified" + - "Terms to Define" + - "Action Items" + next: + standalone: standalone + + - id: domain-model + attrs: + description: "The WHAT — bounded contexts, entities, relationships, aggregate boundaries, and the WHY for each" + role: specification + audience: "business, architect, developer" + produced_by: "discovery → domain-modeling" + observation: "Absorbed system.md's rationale columns. Why Separate and Why Grouped capture architectural reasoning that previously lived in a separate document. Event storming intermediate sections live in event-storming.md — not here." + sections: + - "Summary" + - "Bounded Contexts (Context, Responsibility, Key Entities, Integration Points, Why Separate)" + - "Entities" + - "Relationships" + - "Aggregate Boundaries (Aggregate, Root Entity, Invariants, Bounded Context, Why Grouped)" + - "Changes" + next: + "← Event Map, Context Candidates, Aggregate Candidates": event-storming + + - id: event-storming + attrs: + description: "Workshop output — domain events, commands, read models, context/aggregate candidates" + role: raw-source + audience: "business, architect" + produced_by: "discovery → event-storming" + observation: "Ephemeral workshop file kept as separate document. Not part of domain_model.md. Preserved in git for traceability but not consumed downstream after domain-modeling completes." + sections: + - "Domain Events" + - "Commands" + - "Read Models" + - "Context Candidates" + - "Aggregate Candidates" + next: + standalone: standalone + + - id: glossary + attrs: + description: "Shared language — term definitions, aliases, examples. Universally read for naming consistency." + role: specification + audience: "business, architect, developer" + produced_by: "discovery → language-definition" + sections: + - "Term entries (append-only: Term, Definition, Aliases, Example, Source)" + next: + "← Terms to Define": interview-notes + "← Bounded Contexts, Entities, Context Candidates": domain-model + "← Domain Events, Commands": event-storming + + - id: product-definition + attrs: + description: "The WHY & WHO — scope, users, delivery order, quality attributes, DoD" + role: specification + audience: "business, architect, developer" + produced_by: "discovery → scope-boundary, architecture → architecture-assessment, planning → definition-of-done" + sections: + - "What IS / What IS NOT" + - "Why" + - "Users" + - "Quality Attributes" + - "Out of Scope" + - "Delivery Order" + - "Project Conventions (DoD, Deployment, Branch Strategy)" + - "Scope Changes" + next: + "← Summary, Bounded Contexts → What IS, Users, Delivery Order": domain-model + + - id: context-map + attrs: + description: "DDD strategic design — context relationships, integration patterns, ACLs" + role: specification + audience: architect + produced_by: "architecture → context-mapping" + sections: + - "Context Relationships" + - "Context Map Diagram" + - "Integration Points" + - "Anti-Corruption Layers" + - "Changes" + next: + "← Bounded Contexts, Integration Points → Context Relationships, Integration, ACLs": domain-model + "← Quality Attributes, Deployment → integration patterns (sync/async)": product-definition + + - id: technical-design + attrs: + description: "The HOW — architecture, stack, API/event contracts, interfaces, modules, constraints, key decisions" + role: specification + audience: "architect, developer" + produced_by: "architecture → technical-design" + observation: "Absorbed system.md's ADR summaries (Active Constraints, Key Decisions). Now the single architect reference — no separate summary document needed." + sections: + - "Feature" + - "Architectural Style" + - "Quality Attributes" + - "Stack" + - "Module Structure" + - "API Contracts" + - "Event Contracts" + - "Interface Definitions" + - "C4 Diagrams" + - "Dependencies" + - "Configuration Keys" + - "Active Constraints [from ADRs]" + - "Key Decisions [from ADRs]" + - "Changes" + next: + "← Context Relationships, Integration Points, ACLs → API/Event Contracts, Interfaces": context-map + "← Bounded Contexts, Entities, Relationships → Module Structure, API Contracts": domain-model + "← Quality Attributes, Deployment → Stack, Dependencies, QA mapping": product-definition + + - id: adr + attrs: + description: "Decision records — context, alternatives, rationale, consequences, risk" + role: specification + audience: "architect, developer" + produced_by: "architecture → adr-draft" + observation: "Read by review-signoff and design-review (optional). All other states read technical-design's Active Constraints + Key Decisions instead of raw ADRs." + sections: + - "Status" + - "Context" + - "Interview" + - "Decision" + - "Reason" + - "Alternatives Considered" + - "Consequences" + - "Risk Assessment" + next: + "← Architectural Style, Stack, Module Structure, QA → Context, Interview, Risk": technical-design + "← Context Relationships → Context": context-map + "← Bounded Contexts, Aggregate Boundaries → Context": domain-model + "← Quality Attributes, Scope → Context, Risk": product-definition + + - id: features + attrs: + description: "The BEHAVIOR — per-feature rules, BDD examples, constraints" + role: specification + audience: "business, developer" + produced_by: "discovery → feature-discovery, planning → feature-breakdown, planning → feature-examples" + sections: + - "Title" + - "Description" + - "Rules (Business) [superseded by Rules]" + - "Constraints" + - "Questions" + - "Rules (refined, INVEST-validated)" + - "Examples (Given/When/Then with @id tags)" + - "Changes" + next: + "← Delivery Order, Quality Attributes, What IS/IS NOT → priority, Constraints, scope": product-definition + "← Entities, Relationships, Aggregate Boundaries → feature scope, boundaries": domain-model + "← API Contracts, Interface Definitions → feature scope": technical-design + "← Integration Points, ACLs → project skeleton structure": context-map + + - id: branding + attrs: + description: "Brand identity — personality, visual, wording, release naming" + role: specification + audience: business + produced_by: "branding → setup-branding, branding → design-colors" + sections: + - "Identity" + - "Visual (Logo, Banner)" + - "Release Naming" + - "Wording" + next: + standalone: standalone + + - id: post-mortem + attrs: + description: "Failure records — root cause, missed gate, fix, restart check" + role: operational + audience: developer + produced_by: "post-mortem → document-findings, extract-lessons, action-items" + sections: + - "Failed At" + - "Root Cause" + - "Missed Gate" + - "Fix" + - "Restart Check" + next: + standalone: standalone diff --git a/.flowr/flows/feature-development-flow.yaml b/.flowr/flows/feature-development-flow.yaml index d9c2fd44..0b1f8ec4 100644 --- a/.flowr/flows/feature-development-flow.yaml +++ b/.flowr/flows/feature-development-flow.yaml @@ -13,7 +13,7 @@ states: description: "Plan feature breakdown, BDD scenarios, and development readiness" git: main flow: planning-flow - flow-version: "^6" + flow-version: "^7" next: complete: development needs_architecture: needs_architecture @@ -24,7 +24,7 @@ states: description: "Implement the feature through TDD cycles, review, and commit" git: feature flow: development-flow - flow-version: "^5" + flow-version: "^6" next: done: delivery needs_planning: planning diff --git a/.flowr/flows/main-flow.yaml b/.flowr/flows/main-flow.yaml index fd01a88f..d7d8fe76 100644 --- a/.flowr/flows/main-flow.yaml +++ b/.flowr/flows/main-flow.yaml @@ -1,5 +1,5 @@ flow: main-flow -version: 8.0.0 +version: 9.0.0 exits: [completed, cancelled] states: @@ -8,7 +8,7 @@ states: description: "Understand the domain, define scope, and establish ubiquitous language through stakeholder interviews and domain modeling" git: main flow: discovery-flow - flow-version: "^4" + flow-version: "^6" next: complete: architecture @@ -17,7 +17,7 @@ states: description: "Design technical architecture, context boundaries, and API contracts for the entire project" git: main flow: architecture-flow - flow-version: "^5" + flow-version: "^6" next: complete: feature-development needs_discovery: discovery diff --git a/.flowr/flows/planning-flow.yaml b/.flowr/flows/planning-flow.yaml index 96417198..0e210edc 100644 --- a/.flowr/flows/planning-flow.yaml +++ b/.flowr/flows/planning-flow.yaml @@ -1,5 +1,5 @@ flow: planning-flow -version: 6.0.0 +version: 7.0.0 params: [feature_name] exits: - complete @@ -34,7 +34,6 @@ states: - features/.feature - product_definition.md - technical_design.md - - interview-notes/*.md out: - features/.feature: - rules diff --git a/.flowr/flows/review-gate-flow.yaml b/.flowr/flows/review-gate-flow.yaml index ad026c03..2d5dfe24 100644 --- a/.flowr/flows/review-gate-flow.yaml +++ b/.flowr/flows/review-gate-flow.yaml @@ -1,5 +1,5 @@ flow: review-gate-flow -version: 3.0.0 +version: 4.0.0 params: [feature_name] exits: - pass @@ -18,9 +18,8 @@ states: - glossary.md - technical_design.md - context_map.md - - system.md - product_definition.md - - adr/*.md + - "adr/*.md" # optional - refactored_source out: - design_review_evidence diff --git a/.flowr/sessions/doc-audit.yaml b/.flowr/sessions/doc-audit.yaml new file mode 100644 index 00000000..50320a1f --- /dev/null +++ b/.flowr/sessions/doc-audit.yaml @@ -0,0 +1,9 @@ +created_at: '2026-05-06T09:26:21.074902+00:00' +flow: architecture-flow +name: doc-audit +params: {} +stack: +- flow: main-flow + state: architecture +state: architecture-assessment +updated_at: '2026-05-06T10:25:28.454349+00:00' diff --git a/.flowr/viz/app.js b/.flowr/viz/app.js index da5152ac..873ea5ed 100644 --- a/.flowr/viz/app.js +++ b/.flowr/viz/app.js @@ -300,11 +300,13 @@ const labelMap = { description: "Description", owner: "Owner", + in: "In", + out: "Out", input_artifacts: "In", edited_artifacts: "Edit", output_artifacts: "Out", }; - const ordered = ["description", "owner", "input_artifacts", "edited_artifacts", "output_artifacts"]; + const ordered = ["description", "owner", "in", "out", "input_artifacts", "edited_artifacts", "output_artifacts"]; const rest = Object.keys(d.attrs).filter((k) => !ordered.includes(k)); const allKeys = [...ordered, ...rest]; for (const key of allKeys) { diff --git a/.flowr/viz/generate-flowviz-data.py b/.flowr/viz/generate-flowviz-data.py index 258a3c5b..22c9d43f 100755 --- a/.flowr/viz/generate-flowviz-data.py +++ b/.flowr/viz/generate-flowviz-data.py @@ -54,7 +54,7 @@ def _flatten_attrs(attrs: dict | None) -> dict | None: return attrs flat = {} for key, val in attrs.items(): - if key in ("input_artifacts", "edited_artifacts", "output_artifacts"): + if key in ("input_artifacts", "edited_artifacts", "output_artifacts", "in", "out"): flat[key] = _flatten_artifacts(val) else: flat[key] = val diff --git a/.opencode/agents/design-agent.md b/.opencode/agents/design-agent.md index d680cd9b..18183fc0 100644 --- a/.opencode/agents/design-agent.md +++ b/.opencode/agents/design-agent.md @@ -1,5 +1,5 @@ --- -description: "Design Agent — creates and maintains brand identity, visual assets, and colour systems" +description: "Design Agent: creates and maintains brand identity, visual assets, and colour systems" mode: subagent temperature: 0.4 --- diff --git a/.opencode/agents/domain-expert.md b/.opencode/agents/domain-expert.md index 2dcddc4a..a3b93ab8 100644 --- a/.opencode/agents/domain-expert.md +++ b/.opencode/agents/domain-expert.md @@ -1,5 +1,5 @@ --- -description: "Domain Expert — facilitates discovery and models the domain" +description: "Domain Expert: facilitates discovery and models the domain" mode: subagent temperature: 0.3 --- diff --git a/.opencode/agents/product-owner.md b/.opencode/agents/product-owner.md index 03cea681..62727873 100644 --- a/.opencode/agents/product-owner.md +++ b/.opencode/agents/product-owner.md @@ -1,5 +1,5 @@ --- -description: "Product Owner — owns scope, requirements, and acceptance" +description: "Product Owner: owns scope, requirements, and acceptance" mode: subagent temperature: 0.4 --- diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index f58475dd..227e1323 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -1,5 +1,5 @@ --- -description: "Reviewer — independently verifies architecture and implementation" +description: "Reviewer: independently verifies architecture and implementation" mode: subagent temperature: 0.3 --- diff --git a/.opencode/agents/setup-agent.md b/.opencode/agents/setup-agent.md index 170c9218..ec644cda 100644 --- a/.opencode/agents/setup-agent.md +++ b/.opencode/agents/setup-agent.md @@ -1,5 +1,5 @@ --- -description: "Setup Agent — transforms templates into new projects" +description: "Setup Agent: transforms templates into new projects" mode: subagent temperature: 0.3 --- diff --git a/.opencode/agents/software-engineer.md b/.opencode/agents/software-engineer.md index 99c49720..db9d463c 100644 --- a/.opencode/agents/software-engineer.md +++ b/.opencode/agents/software-engineer.md @@ -1,5 +1,5 @@ --- -description: "Software Engineer — implements, tests, and ships production code" +description: "Software Engineer: implements, tests, and ships production code" mode: subagent temperature: 0.3 --- diff --git a/.opencode/agents/system-architect.md b/.opencode/agents/system-architect.md index 97b6cccf..50d639cc 100644 --- a/.opencode/agents/system-architect.md +++ b/.opencode/agents/system-architect.md @@ -1,5 +1,5 @@ --- -description: "System Architect — designs technical architecture and reviews implementation" +description: "System Architect: designs technical architecture and reviews implementation" mode: subagent temperature: 0.3 --- diff --git a/.opencode/knowledge/agent-design/principles.md b/.opencode/knowledge/agent-design/principles.md index b6083958..85748989 100644 --- a/.opencode/knowledge/agent-design/principles.md +++ b/.opencode/knowledge/agent-design/principles.md @@ -11,17 +11,17 @@ last-updated: 2026-04-29 - 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. +- 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 +- **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 | Concern | File | Purpose | Loaded When | |---|---|---|---| @@ -34,7 +34,7 @@ last-updated: 2026-04-29 **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. +**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. @@ -61,12 +61,12 @@ That is the entire agent. No skill lists, no ownership tables, no IF-THEN trigge ### 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 +- **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 diff --git a/.opencode/knowledge/architecture/adr.md b/.opencode/knowledge/architecture/adr.md index 2bda578c..48732493 100644 --- a/.opencode/knowledge/architecture/adr.md +++ b/.opencode/knowledge/architecture/adr.md @@ -8,23 +8,23 @@ last-updated: 2026-04-29 ## Key Takeaways -- ADRs document architecturally significant decisions — decisions that are hard to change and affect multiple components (Nygard, 2011). +- 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, Decision, Reason, Alternatives, 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 `@id` criteria it addresses. +- 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 `@id` 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. +**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), Decision (the choice made), Reason (why this choice over alternatives), Alternatives (other options considered and why they were rejected), Consequences (what changes because of this decision, both positive and negative). +**ADR Structure**: Every ADR contains (Nygard, 2011): Status (Proposed, Accepted, Deprecated, Superseded), Context (the forces at play, the problem being solved), Decision (the choice made), Reason (why this choice over alternatives), Alternatives (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. +**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 `@id` criteria 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, leveraging accountability to an unknown audience (Tetlock, 1985) to produce more rigorous decisions. +**ADR Consistency**: Every ADR must be consistent with the feature requirements it addresses. During review, check that each ADR aligns with the `@id` criteria 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. +**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 diff --git a/.opencode/knowledge/architecture/assessment.md b/.opencode/knowledge/architecture/assessment.md index d2716d88..6dc6dede 100644 --- a/.opencode/knowledge/architecture/assessment.md +++ b/.opencode/knowledge/architecture/assessment.md @@ -8,27 +8,27 @@ last-updated: 2026-04-29 ## 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 system.md, technical_design.md, and context_map.md all contain meaningful content aligned with the current domain. +- 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 technical_design.md and context_map.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. +- 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. +**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 three documents contain meaningful, aligned content: system.md (current state snapshot), technical_design.md (technical decisions), and context_map.md (bounded context relationships). Empty or placeholder content does not count. If all three exist and are coherent, the architect evaluates whether the existing architecture covers the new feature or needs updating. +**Architecture Existence Check**: Architecture is considered to exist when two documents contain meaningful, aligned content: technical_design.md (technical decisions, active constraints, key decisions) and context_map.md (bounded context relationships). 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. +**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. +**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: +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) diff --git a/.opencode/knowledge/architecture/contract-design.md b/.opencode/knowledge/architecture/contract-design.md index 20e3c695..f9a920aa 100644 --- a/.opencode/knowledge/architecture/contract-design.md +++ b/.opencode/knowledge/architecture/contract-design.md @@ -8,20 +8,20 @@ last-updated: 2026-04-29 ## 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. +- 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). +- 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. +**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. +**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). +**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. +**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 diff --git a/.opencode/knowledge/architecture/quality-attributes.md b/.opencode/knowledge/architecture/quality-attributes.md index 79e62edd..3c9cebbb 100644 --- a/.opencode/knowledge/architecture/quality-attributes.md +++ b/.opencode/knowledge/architecture/quality-attributes.md @@ -8,20 +8,20 @@ last-updated: 2026-04-29 ## Key Takeaways -- Quality attributes — not functional requirements — drive architectural decisions (Bass, Clements & Kazman, 2021). +- 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. +- 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 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. +**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. +**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. +**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 diff --git a/.opencode/knowledge/architecture/reconciliation.md b/.opencode/knowledge/architecture/reconciliation.md index e25865a3..5cdbede5 100644 --- a/.opencode/knowledge/architecture/reconciliation.md +++ b/.opencode/knowledge/architecture/reconciliation.md @@ -8,18 +8,18 @@ last-updated: 2026-04-29 ## 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: system↔glossary, system↔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 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_model↔glossary, domain_model↔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. Leveraging 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. +**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. +**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. +**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 @@ -27,8 +27,8 @@ last-updated: 2026-04-29 | # | Check | Verify | Mismatch Signal | |---|---|---|---| -| 1 | system ↔ glossary | Every glossary term matches how it is used in system.md Domain Model | A term defined in the glossary is used with a different meaning in the domain model | -| 2 | system ↔ feature | Every entity, action, and relationship in system.md Domain Model matches feature requirements | An entity appears in the domain model but not in any feature, or vice versa | +| 1 | domain_model ↔ glossary | Every glossary term matches how it is used in domain_model.md | A term defined in the glossary is used with a different meaning in the domain model | +| 2 | domain_model ↔ feature | Every entity, action, and relationship in domain_model.md matches feature requirements | An entity appears in the domain model but not in any feature, or vice versa | | 3 | ADRs ↔ feature | Every ADR aligns with feature requirements; each ADR references specific `@id` 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 | @@ -38,7 +38,7 @@ last-updated: 2026-04-29 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 system.md, technical_design.md, or the ADR. If the requirements are wrong, update the feature file or product definition. +2. **Determine which side changes**: If the architecture is wrong, update domain_model.md, technical_design.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. diff --git a/.opencode/knowledge/architecture/technical-design.md b/.opencode/knowledge/architecture/technical-design.md index eb4869cb..202a1f26 100644 --- a/.opencode/knowledge/architecture/technical-design.md +++ b/.opencode/knowledge/architecture/technical-design.md @@ -8,20 +8,20 @@ last-updated: 2026-04-29 ## Key Takeaways -- Architectural style must be selected based on quality attributes and deployment constraints — not personal preference. +- 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. +- 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: Monolith (single deployment, simple ops, low latency between modules), Microservices (independent deployment, team autonomy, high operational complexity), Event-driven (loose coupling, eventual consistency, async workflows), Serverless (pay-per-use, auto-scaling, cold starts), Hexagonal/Ports & Adapters (testability, domain isolation, delivery-mechanism independence). +**Architectural Styles**: Common styles and when to choose them: Monolith (single deployment, simple ops, low latency between modules), Microservices (independent deployment, team autonomy, high operational complexity), Event-driven (loose coupling, eventual consistency, async workflows), Serverless (pay-per-use, auto-scaling, cold starts), Hexagonal/Ports & Adapters (testability, domain isolation, delivery-mechanism independence). -**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. +**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** — Organize by bounded context first (Evans, 2003), then by layer (domain, application, infrastructure). Domain layer has zero infrastructure imports. Application layer orchestrates use cases. Infrastructure layer implements external concerns. The dependency arrow always points inward: infrastructure → application → domain (Clean Architecture — Martin, 2012; Hexagonal Architecture — Cockburn, 2005). +**Module Structure**: Organize by bounded context first (Evans, 2003), then by layer (domain, application, infrastructure). Domain layer has zero infrastructure imports. Application layer orchestrates use cases. Infrastructure layer implements external concerns. The dependency arrow always points inward: infrastructure → application → domain (Clean Architecture, Martin, 2012; Hexagonal Architecture, Cockburn, 2005). -**Contract-First Design** — Define the boundaries before the implementation: API contracts (request/response shapes, error codes, authentication), Event contracts (event names, payload schemas, ordering guarantees), Interface definitions (Protocol/abstract classes that the domain defines and infrastructure implements). +**Contract-First Design**: Define the boundaries before the implementation: API contracts (request/response shapes, error codes, authentication), Event contracts (event names, payload schemas, ordering guarantees), Interface definitions (Protocol/abstract classes that the domain defines and infrastructure implements). ## Content @@ -39,8 +39,8 @@ Hybrid approaches are valid: a monolith with hexagonal internals, or microservic ### C4 Diagram Guidelines -- Context diagram: always include — shows the system boundary and external actors -- Container diagram: always include — shows deployable units and tech choices +- 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 diff --git a/.opencode/knowledge/design/color-systems.md b/.opencode/knowledge/design/color-systems.md index 5032b31e..3e499365 100644 --- a/.opencode/knowledge/design/color-systems.md +++ b/.opencode/knowledge/design/color-systems.md @@ -12,13 +12,13 @@ last-updated: 2026-04-30 - 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). +- 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 the entire mark in black on white, then white on black. If it does not work in monochrome, colour will not save it. Only after the shape holds identity in one colour should a second colour be introduced — and only as an accent, never carrying meaning that must be read. +**Monochrome-First Process**: Design the entire mark in black on white, then white on black. If it does not work in monochrome, colour will not save it. Only after the shape holds identity in one colour should a second colour be introduced, and only as an accent, never carrying meaning that must be read. **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) @@ -55,13 +55,13 @@ For 2-colour brand marks, use complementary or split-complementary. Analogous pa **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 paramount. +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. +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). +**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). @@ -111,13 +111,13 @@ A thin gold line on a navy field reads as "balanced" because the yellow's visual 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 +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 diff --git a/.opencode/knowledge/design/identity-design.md b/.opencode/knowledge/design/identity-design.md index be68c492..1ac6fe69 100644 --- a/.opencode/knowledge/design/identity-design.md +++ b/.opencode/knowledge/design/identity-design.md @@ -10,23 +10,23 @@ last-updated: 2026-04-30 - 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. +- 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`. +**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). +**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. +**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). +**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 diff --git a/.opencode/knowledge/design/project-assets.md b/.opencode/knowledge/design/project-assets.md index 3cf0dfb4..ea75de23 100644 --- a/.opencode/knowledge/design/project-assets.md +++ b/.opencode/knowledge/design/project-assets.md @@ -19,17 +19,17 @@ last-updated: 2026-04-30 ## 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. +**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. +**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. +**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 `