# INITKOA CONTEXT PACK repository: Rejean-McCormick/Konnaxion source_commit: a209a9976d5e4271889c63df40701ae3de2b78fd source_mode: git working_tree_markdown: clean working_tree_selected: clean selection_mode: markdown wiki_source_commit: acca199c8f4667ff03ac3e953f4bc45a9763ebf8 wiki_working_tree_markdown: clean policy_version: 2026-09-10.13 repo_files: 225 wiki_files: 16 source_files: 241 included_files: 122 excluded_files: 119 duplicate_files: 57 content_bytes: 1748961 authority_counts: {"reference":122} content_role_counts: {"knowledge":106,"navigation":16} generated_at: 2026-09-10T13:04:08-04:00 files: 122 content_sha256: fab3f84271d081d0a42606278d3d4dd975445ed605152c7b70a87624cd0f9707 ================================================================================================ FILE INDEX ================================================================================================ 001. [reference] [navigation] wiki/CertifiKation.md | bytes=946 | sha256=7f05825c00c1637aca55b20a1670d0d4b4530c75c1a1071f46c193ae05f76aae 002. [reference] [navigation] wiki/EkoH.md | bytes=2009 | sha256=c9f37ca75e07d970bda4917373446a07a62fca6c86b4b8a1696f8d53532ac4fe 003. [reference] [navigation] wiki/Glossary.md | bytes=2392 | sha256=c85c403f9fc891452fcec07271de2c7afbec728ee4eab2bb684ff8787ea8472e 004. [reference] [navigation] wiki/Home.md | bytes=2715 | sha256=e3627b808a1c4100126cfad965c60b2ceaac2d69292e3a48e0f4dda91e4f342d 005. [reference] [navigation] wiki/Implementation-Alignment.md | bytes=3203 | sha256=a52f33bf48da3a4237e212118aca2bb4929b425e339ea35601bc989268dee2d6 006. [reference] [navigation] wiki/Knowledge.md | bytes=945 | sha256=0730dd4e36baeb03c2a17b1810d1f0cbca7e75773c72c51ae52ef2d92d800cc3 007. [reference] [navigation] wiki/Konnaxion-Technical-Architecture-&-Services.md | bytes=5349 | sha256=d3953c1429182faf510a7e18246d1a34dd98a251844ccdc5581e821b2e6188dc 008. [reference] [navigation] wiki/Konservation.md | bytes=859 | sha256=64255b9c670da3b6dac86674870a18df208627a3598c79fe097f17df6bc0da0d 009. [reference] [navigation] wiki/Konstruct.md | bytes=857 | sha256=73f1a81e467595ebcd040bb52fe41a8b6f097cfb9d17e35d9c0877d90757a129 010. [reference] [navigation] wiki/Konsultations.md | bytes=1386 | sha256=9ddae0a14418c0b48891c1ec31c3d3cda976645abf09620843735e514d30b0db 011. [reference] [navigation] wiki/Kontact.md | bytes=786 | sha256=69ebd975e5bc96d7e7d2a305b6943c0b51659b9256a38fb347ba609e2b6f0cee 012. [reference] [navigation] wiki/Kontrol.md | bytes=671 | sha256=77c2df1b8dc7edc479b75b4fe682b6fe675bb7a7b34b7fd2fe3bb6c7b91901a1 013. [reference] [navigation] wiki/Korum.md | bytes=1496 | sha256=0ede27c038b633ebaf4093b1808de075462b2fe6835c608ad025780af8fdac0e 014. [reference] [navigation] wiki/Smart-Vote.md | bytes=1901 | sha256=a018384fb077e9c6fec23ba5127c9878dac8b6b05a195cf4c47afe866d410713 015. [reference] [navigation] wiki/Stockage.md | bytes=1013 | sha256=b871781be7f0c120748524bf83997bf0ce327125428f76b2d1f7e3dac62235e0 016. [reference] [navigation] wiki/TeamBuilder.md | bytes=705 | sha256=5844cb8450a89de3cf05913dadb8e2ef1a484a192adfa64b464d84413d59a3e0 017. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Konnaxion_User_Workflows.md | bytes=2887 | sha256=a6ac49c9193a9a0dd0712b05480bc0ec9cf9a1fe93a3c7f68d309a8c6d87a039 018. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/status/2026-08-28-technical-maturity-assessment.md | bytes=15898 | sha256=0cbdf32a387dff582bc1840193eedaa3ba2c370e2ab50cf873a97b2520185cfb 019. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/status/ETHIKOS_EKOH_SMARTVOTE_DELIVERY_WORKFLOW.md | bytes=4901 | sha256=92f2989dd33424a24c7cdff95ef6b2a227748d473ee661e627a6ffd8fb3d4cc7 020. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH - System Overview.md | bytes=1728 | sha256=bb1d5b7bc1eed33e8b0c04421076ee28a01dc3ac35dd71763b0c646a68add9d1 021. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Data Model.md | bytes=1565 | sha256=7ee22efbcd42297f264ecb5fe0ce36d43e96b733cdb745ff81c3cab4be016298 022. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md | bytes=2286 | sha256=619b1bcab623d2d5fdd9df15732e1a8551e6558d0d1c8f072f531107eec2b6c6 023. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-module-file-architecture.md | bytes=2865 | sha256=f721021486ac9291891d4e7acc46e026dae7ccd701930f1474be1299b8ffb002 024. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-canonical-db-schema-v1-1.md | bytes=20054 | sha256=43020b08a0e55a0bced19874130139fc6c4a611cd81eb16f50e1aa013bf7adc2 025. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-definitive-module-documentation-set-v1-0.md | bytes=68542 | sha256=8d07cfc6e0d73e842eaf1cb7c33590add0a9d5bcb633edc734a93bc1e40a0038 026. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md | bytes=5295 | sha256=b1dafcb4ce3ecb9028f31595e55f37bcb25a08b5d768b5d2766e802e48c8b25b 027. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md | bytes=8214 | sha256=507fcbee41c3ca3378444bec3ae5b7aff675b06acdaff9433f793f169f947dc9 028. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/Smart Vote - Reading Contract.md | bytes=2187 | sha256=29a63181e2846021a683b3fb1e5af1e7d2befca975cc09df87c6bd0c2b749af2 029. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-consultation-simulations.md | bytes=36173 | sha256=47a82d05bf25240f9bb17d253a6b38995da301827236a7e0ff46034f2a46fe8b 030. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-empower-ux-naming-guidelines.md | bytes=3954 | sha256=24b01e6ba4a2cfbd9133e516a4c1e580993cd838ff84ee0140b944e18236f1a7 031. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md | bytes=6707 | sha256=dfaedc9eeb51777217b3d37c7c61cf9280e35f1e26bb165d4c78767b744e612c 032. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos-kintsugi-upgrade-plan-v1.md | bytes=15374 | sha256=7a1638851b7c66cb13bbe1aba969c8b6977d60fe81386832bd09c112b1445d5a 033. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md | bytes=27130 | sha256=1039f75e4838cb5df7c7fbdc9cca3c3cccc7f87d09323d3aafc064b692c30c4f 034. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md | bytes=27913 | sha256=ac923db7e5d5c03f95b36ac6eb0b89e7e4e05f3cc1aab9dda1b4cf358d65aff9 035. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md | bytes=28486 | sha256=3118237094656ffce34d3fa8e90437de2ffa3421221b5cf7a6ef78ef4049a4eb 036. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md | bytes=38639 | sha256=5d1c4984dca835a688f131c6c4baf4888b9f38ed5d0bdd6482431a075b2cb99a 037. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md | bytes=38416 | sha256=9d42166580537ff6684169fe12983e3aae2237133ef3ac5e0bd2707de1be3b99 038. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/05_CURRENT_STATE_BASELINE.md | bytes=29320 | sha256=a6b7d6c6495a1b32203ee08bd44b5bbb4a2792e55d61e08f63e928796a8a3251 039. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md | bytes=34246 | sha256=b451799a5f8ed8eb0ea1d5e8be4dbccf1bd611f2fa098e0ad0c31f7600950d89 040. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md | bytes=41133 | sha256=092bfe82ef9f4bcbb31bb731fe298acbb79630835226a894738038b68ec78861 041. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md | bytes=47559 | sha256=b83853c2b000e3f8b8b1b5b5add01a3bc6f9ce45cede69b3bdeabf2f345e400a 042. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md | bytes=34332 | sha256=88d6a04ada7a672966a3839da4568f9d64fb265582cb134f5d4eb2bd229518ab 043. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/10_FIRST_PASS_INTEGRATION_MATRIX.md | bytes=46751 | sha256=70020466ed2f9d8b1a4c1a675e05c90545ab9593bfe5e40de6cdac1b429d27c3 044. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/11_MIMIC_VS_ANNEX_RULEBOOK.md | bytes=27995 | sha256=90d3fe2b3c4d349720e216199bb5369fa941bdfa3750d38e6b9277ff0cf7b1f1 045. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/12_CANONICAL_OBJECTS_AND_EVENTS.md | bytes=53037 | sha256=b11753cb48def4c1fe0dd5f02e31fbdd71918e25c9309f7fe1fcd23268e29a93 046. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md | bytes=41408 | sha256=143346d2169401863b9f611aac2e11f9871edb2c0ba48e4b4207381730d0ad0a 047. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md | bytes=33303 | sha256=6d5b2e5f0266b6c9598a01a109a30206a438dd236438cfd1bf09e477cd6938ca 048. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md | bytes=43515 | sha256=0d8cb40757b0a194f95e3d93852291a1b15b34c91a3b98e30c2e7c8a0db682f6 049. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md | bytes=28262 | sha256=08158e3ee2a0fa1296a97ff5a8d440d379fb6cd1a499f3bfb46f52324ccf1185 050. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md | bytes=23385 | sha256=0830745c08d03d93bad817386d6929de20f08462e8ddeb46e3bc792d374562c3 051. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md | bytes=33979 | sha256=390468f1e477900f215148a1fdb5ecd403564ac5699cb757a18067329e955968 052. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/19_OSS_CODE_READING_PLAN.md | bytes=36614 | sha256=8d145766c927b6eb571a231d7d90aebb37f4fa2dc06cfb395b3c3f8bd328c392 053. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/20_AI_GENERATION_GUARDRAILS.md | bytes=36195 | sha256=b7894326ff28ca723c2e2b251d76e0d823d6b267ee6b5d2ea091f5ef806bd4f8 054. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md | bytes=37786 | sha256=c73b8f8fb2524ca9e6c7cd6ac2cbdf3e6e870db7a722fcd5e6ff280d7e8a5cd7 055. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/22_IMPLEMENTATION_BACKLOG_TEMPLATE.md | bytes=43991 | sha256=77491d44f9b1a9b91b952c39c7abd9d3961cfed8d2e28b1e803947f2126d0208 056. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md | bytes=39133 | sha256=3980fbe85df409e89d98b3190fae8dc5038b04078e145ebeef4170a3b0f906f2 057. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md | bytes=36049 | sha256=4c389f3135100a6fc2ff84d3a535052a3f61bdc9f4ef8ce5e0b30687bc3eead9 058. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md | bytes=30121 | sha256=ec3cc9296943ce7ebfb4cffc17f92206d1dda4cea7340f52064ed910602e3020 059. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md | bytes=9136 | sha256=c7df0e8bc0735da99e97b1b309b9703cb1e81c8d84b6e5e865fc920e0519c3ba 060. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md | bytes=10084 | sha256=56dc6c857b13327770310f358b14b4b1b6a640db564a9a57e9869025877f84ed 061. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md | bytes=16056 | sha256=1b375d93d2d1c8012a62ef2e539699505bed3201a197bc44f847be697efd3027 062. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/Konnaxion-kintsugi-and-kompendio-open-source-integration-map-v1.md | bytes=4284 | sha256=6bf94a0e689fce381fbcf9f0842218247add1c2cb6cc0024fefbb7f7ab74ee46 063. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md | bytes=18352 | sha256=bebcd4a16c40907bb0c9816973e07f9718ee0e416b46248550479391f6ecda91 064. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md | bytes=8254 | sha256=a0aa14b54d11363de282743f327ddfbb02d8ab37daea760f9a1df66fa6ae6621 065. [reference] [knowledge] _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/SmartVote-EkoH-kintsugi-upgrade-v1.md | bytes=7459 | sha256=1f436c903a7b029bddd7dff0d63794c2997732465e2167f1f613b3d2cc5adb2b 066. [reference] [knowledge] _BUG_HARVEST_REVIEW/LevelUpDiag/README.md | bytes=3838 | sha256=4c5868fff56fa849545f3ee1a9d208e2717d3c7409e066ec07b09a518d6f825b 067. [reference] [knowledge] backend/konnaxion/ethikos_20260903_131935_Dump/00_START_HERE.instructions.md | bytes=2624 | sha256=87a6cc1dccbc35fdf27fc36d62ed3ccd820c4e0abcc29cd54094ad403278b53d 068. [reference] [knowledge] backend/locale/README.md | bytes=1627 | sha256=c0a3e3896516b0c5526551fc06b6a3c58cd5cf9e1b810b2e848d68f6cd89e72f 069. [reference] [knowledge] backend/README.md | bytes=3630 | sha256=dac04f29e1863559e19c57765fa2230912e30176a7c9ce25f55ea8bbccf7c9f0 070. [reference] [knowledge] docs/demo-scenarios/ethikos/ETHIKOS_DEMO_IMPORTER.md | bytes=20852 | sha256=9b3d3e879682659f09e21addd9858230dd0351f3eafae411dfaccdbeee11baaa 071. [reference] [knowledge] docs/demo-scenarios/ethikos/README.md | bytes=1434 | sha256=14af8597e9102e540a89cb922767e2c14ff751dbbf508d606d8c500b5b981105 072. [reference] [knowledge] docs/KONNAXION_UPGRADE_TO_DO(credentialAnalyser).md | bytes=16778 | sha256=c5f1ffb360552bbef12c4faa39e0dc8e5a93fd86746ee72aa1dc728aa4aa4008 073. [reference] [knowledge] docs/Konnaxion_UserWorkflow_Documentation_v0_1.md | bytes=38519 | sha256=d112abc7fe7192defe4e74f0461937aef76997c3cce2d2de71ff21232d51fedc 074. [reference] [knowledge] docs/README.md | bytes=1901 | sha256=afda7638e8f10ca93e5baa571a6937c2216b7a654057a0974fcbae0dc66f9b55 075. [reference] [knowledge] docs/status/2026-08-27-technical-maturity-assessment.md | bytes=5821 | sha256=3980af330b06e0df63b8a651da3f35af7dc6f83a97ae53078fddb6d2572742e8 076. [reference] [knowledge] docs/status/2026-09-05-bug-harvest-mass-audit.md | bytes=6784 | sha256=3db4745bf1e9ec8dd5ec500ad9b757049933383a0e8a4af03fd911ef1ed2511f 077. [reference] [knowledge] docs/status/2026-09-05-technical-maturity-assessment.md | bytes=11017 | sha256=3a560acd67b239b8be733073baaa00c73f85053bcb56960af52245ef6b75f230 078. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-real-findings.md | bytes=1457 | sha256=4b67cc1693cade313e7411e978c5b99d56b3ec72c0a38c3afd4fd2b8962d4ede 079. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-wave2a-mass-update.md | bytes=2583 | sha256=dfac143cf63a689cb9fa007738787d5c69963cbe49c469ee460e7f9c20df7be3 080. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-wave2b-mass-update.md | bytes=2265 | sha256=f146b18d9395495d98176cf57e29be8aefbc60cba66402efb750f20ec425fcbd 081. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-wave2c.md | bytes=1421 | sha256=f5eacaeaa3b356ae53b5122b94528fd19c83a1a9034a63a8776b44691ee02a91 082. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-wave2d.md | bytes=1228 | sha256=cd53dacd26b812db5e42f7a9780c21169a889cdfdb1be2afa1743b42ad22d718 083. [reference] [knowledge] docs/status/2026-09-06-bug-harvest-wave2e-context-isolation.md | bytes=1056 | sha256=5b810dc788b2627d9580cef88c0851a0f3ed058df82f9625c17ce01667f87785 084. [reference] [knowledge] docs/status/2026-09-06-technical-status-report-aligned.md | bytes=16358 | sha256=9a7627210d1829e5cff0bfd050a15bdd28170050827ab72b84b168dcb229786b 085. [reference] [knowledge] docs/status/2026-09-06-technical-status-report-wave2-closed.md | bytes=22414 | sha256=8fc597b65f67dc9c759a8901527e264c7c7c4769676bc489ba4eacd7943ab79b 086. [reference] [knowledge] docs/status/2026-09-08-technical-maturity-assessment.md | bytes=15716 | sha256=5b5da75e2fad5c1775cd2e969c1ae252dd43625185a2d6a9fd5fb9ceffebfe29 087. [reference] [knowledge] docs/status/README.md | bytes=1659 | sha256=26aa7b6a22545f9ee17797ece94223e584ce887eb2774d66ed5630d1e20875a4 088. [reference] [knowledge] docs/Technical-Reference/BOUNDARIES_AND_OWNERSHIP.md | bytes=5750 | sha256=16e1687c8efe23b88ca49c28e76b67fef97b85847b659e562d687f3dba956182 089. [reference] [knowledge] docs/Technical-Reference/CODE_ALIGNMENT_NOTES.md | bytes=7070 | sha256=58cc85463fce8c19b3f14b019b3e2b15e1625480efaa123a98943f735ab87dca 090. [reference] [knowledge] docs/Technical-Reference/DEV_DOCKER_CHEATSHEET.md | bytes=6250 | sha256=fa25e913da4b5fd029e462d7b0d0a45a29aa9458e92bd2ec9a289ef2a24fad2a 091. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Database Schema Reference (Custom Tables).md | bytes=20225 | sha256=d7cd538a5f97c104635848378fcb64c62d5a3f440a85c7a8481c393f1779cc37 092. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Database Schema Reference.md | bytes=4698 | sha256=7fc886985ca3a70c61f6e1f35dae3ec678b91f0070b8e7721dc66b137cb8bbb7 093. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Documentation Index.md | bytes=1422 | sha256=bf4fb4433c43b55442ae1aead746b69d4edd56178cd3e81afde7155d0b364983 094. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Full-Stack Technical Specification.md | bytes=12495 | sha256=d476204db3043cd1036c38e8b5761f321d04883410829471957f5bb1b9bcfdeb 095. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Insights UI Reference.md | bytes=25777 | sha256=e9fb72cb4bec884a301cc392bd12a7d417cb8df05d4081decf5cabef393883b3 096. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 - Site Navigation Map.md | bytes=4714 | sha256=08da5ac8ab74c81bb3eb990f9c67cc6c321a88640f79803678eb269049c6de37 097. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Full-Stack Technical Specification.md | bytes=15909 | sha256=9a67097a9f40e31cadaf4392f04e938e09d8740b2b7e3fb543a6dd8545f7a420 098. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Functional Code-Name Inventory (Services & Hooks).md | bytes=14248 | sha256=bf59813f623f7172292f2ff19988830446247a975d9dc5063a6a5de33cdb0fa8 099. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Global Parameter Reference.md | bytes=8119 | sha256=5e3fb000bd1692b5a7b587ba207ae42f890df2b2ec9d598aa4b91ebc4621d9a9 100. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Insights Module Config Parameters.md | bytes=11014 | sha256=c3719b824a95ebe8edfdaad6cffbf1bfdb9f629462fd6a232aabc4721b43f474 101. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Insights Module UI Spec (Reporting & Analytics Frontend).md | bytes=25784 | sha256=32a4a26f9b48de6c45354412ee62c19cf1ac1966f88345029461b0c40fae17c0 102. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion v14 – Site Navigation Map (Top-Level Routes).md | bytes=8297 | sha256=c5982e1ba1b43a364aae1b596fe4e05dd2a770913d4d7084cd0a3f106a76869e 103. [reference] [knowledge] docs/Technical-Reference/DocV14/Konnaxion  v14 - Documentation INDEX.docx.md | bytes=5319 | sha256=5c7fc4bf11461a75ccf4ce14fecbc98955943066ee352457e4ed3c8631c50e24 104. [reference] [knowledge] docs/Technical-Reference/GLOSSARY.md | bytes=4438 | sha256=d1fac795507201143ad7354eb2f19d6c1b69b64641e3faef3b68541dcba53d1b 105. [reference] [knowledge] docs/Technical-Reference/HowToNest-wrap-shell.md | bytes=12233 | sha256=de14a3778f86768bf11cf478b961df287529c349ac5d2302e2bdf82be19903d6 106. [reference] [knowledge] docs/Technical-Reference/Konnaxion_Frontend_Deployment_Runbook.md | bytes=4310 | sha256=b7d9a4f6b166a2b623edd8281e1748c074c07d6367be8d8e71240d47abe5fe1c 107. [reference] [knowledge] docs/Technical-Reference/namecheap-vps.md | bytes=6413 | sha256=a607b62c281c801fb28eeaf9a96b18a10276c341883c07c7b52330d7cee97861 108. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/CertifiKation (Skills & Certification) — sub‑module under KonnectED.md | bytes=4816 | sha256=13b57e8f28ae99e0cf81cf206d39b2df135228dcf10f893b5cf92664863c5751 109. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/EkoH (Reputation & Expertise) — first sub‑module under Kollective Intelligence.md | bytes=4821 | sha256=ea74104a4cad1fdba9142a3b156d8eab6c7c3b33f44e5119b4cffca75a6df0cd 110. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Knowledge (Collaborative Learning Library) — sub‑module under KonnectED.md | bytes=4457 | sha256=d31bdf7b591cab7408f9112d149d2deddf9fe1a5aa7a2dc3fd17a7bad9ffcdcd 111. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Konservation (Creative Content & Cultural Preservation) — sub‑module under Kreative.md | bytes=5664 | sha256=8e659b5a1b8023676fefe830c48e5a312446797cdd4f2a0442fb8572f70730e1 112. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Konstruct (Project Collaboration Spaces) — first sub‑module under keenKonnect.md | bytes=5401 | sha256=ceb6e1e452c27bf61b9fe8a4a77431aabef8eafc1ae96cf46174e938e32cda63 113. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Konsultations (Public Consultations & Feedback) — sub‑module under ethiKos.md | bytes=4664 | sha256=ebb0219cb85e6e9dbe566b32239be0df3ef104b75971c7317d621c4811ab2f36 114. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Kontact (Collaboration & Networking) — sub‑module under Kreative.md | bytes=4628 | sha256=cf3b050bc4b419a986505dab954a53de7130301638abb7acd7aa3d5cd0b7193f 115. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Korum (Structured Debates) — sub‑module under ethiKos.md | bytes=4503 | sha256=61ae3dc9ba9a84a0b0334fb7ea4255af53c59c1c628134fca037cdfaaa573417 116. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Smart Vote (Weighted Voting System) — second sub‑module under Kollective Intelligence.md | bytes=4299 | sha256=903fe4ccb3692289fc87b21039dfb4e52adf5b46f43dd6c2271d339bbc0e8dff 117. [reference] [knowledge] docs/Technical-Reference/sub-modules_description/Stockage (Secure Repository & Versioned Storage) — second sub‑module under keenKonnect.md | bytes=5014 | sha256=202621aacc3a8d0dd78e3305d922cdd0dbbf1cf30a676be6ca911bcb9c95bee3 118. [reference] [knowledge] docs/Technical-Reference/UpdateBackendAndMigrateAndDocker.md | bytes=2015 | sha256=4b96c448ec8242bf561cf6832415a8efa51a5703013daa27218691ac50ad8726 119. [reference] [knowledge] frontend/app/ethikos_20260903_132014_Dump/00_START_HERE.instructions.md | bytes=2792 | sha256=16682ce56457cf5a9a190d1045558de40e7218ece27bde2c2cb3f49c2a449bff 120. [reference] [knowledge] frontend/README.md | bytes=6139 | sha256=98131c561b9e7650a5e3e7779b1a79478563fc5e74249ea7ac1a8d1331a0c9ce 121. [reference] [knowledge] README.md | bytes=10017 | sha256=a90f1f2903709a31b4521234ab30e5c0ed38cb8cf397529ef62c0f7d164bf230 122. [reference] [knowledge] seed-data/ethikos/canada_quebec_public_debates_2026_inventory.md | bytes=56078 | sha256=943f8cf9e1fdf2f9dadf41c53a71216854115f08716166b0672df6e6a52d6e3b ================================================================================================ EXCLUDED FILES ================================================================================================ - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_144016/files/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_144016/files/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_144016/files/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_145523/files/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_145523/files/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_145523/files/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_145523/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_145523/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_150909/files/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_150909/files/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_150909/files/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_150909/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_150909/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_153654/files/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_153654/files/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_153654/files/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_153654/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v3_20260819_153654/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/seed-data/ethikos/canada_quebec_public_debates_2026_inventory.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_1_walkthrough_access_20260820_133822/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/seed-data/ethikos/canada_quebec_public_debates_2026_inventory.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_2_walkthrough_access_20260820_135057/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/README_PUSH.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/seed-data/ethikos/canada_quebec_public_debates_2026_inventory.md (global:.kx_deploy_backups/**) - [historical] .kx_deploy_backups/ethikos_ekoh_v4_1_walkthrough_access_20260820_131813/files/VALIDATION_REPORT.md (global:.kx_deploy_backups/**) - [duplicate] _BUG_HARVEST_SOURCE/docs/Konnaxion_User_Workflows.md (same content as _BUG_HARVEST_REVIEW/docs/Konnaxion_User_Workflows.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/status/2026-08-28-technical-maturity-assessment.md (same content as _BUG_HARVEST_REVIEW/docs/status/2026-08-28-technical-maturity-assessment.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md) - [duplicate] _BUG_HARVEST_SOURCE/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md) - [duplicate] docs/Konnaxion_User_Workflows.md (same content as _BUG_HARVEST_REVIEW/docs/Konnaxion_User_Workflows.md) - [duplicate] docs/status/2026-08-28-technical-maturity-assessment.md (same content as _BUG_HARVEST_REVIEW/docs/status/2026-08-28-technical-maturity-assessment.md) - [duplicate] docs/status/ETHIKOS_EKOH_SMARTVOTE_DELIVERY_WORKFLOW.md (same content as _BUG_HARVEST_REVIEW/docs/status/ETHIKOS_EKOH_SMARTVOTE_DELIVERY_WORKFLOW.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/EkoH - System Overview.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH - System Overview.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Data Model.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Data Model.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/ekoh-module-file-architecture.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-module-file-architecture.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-canonical-db-schema-v1-1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-canonical-db-schema-v1-1.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-definitive-module-documentation-set-v1-0.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-definitive-module-documentation-set-v1-0.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/Smart Vote - Reading Contract.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/Smart Vote - Reading Contract.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/smart-vote-consultation-simulations.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-consultation-simulations.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/smart-vote-empower-ux-naming-guidelines.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-empower-ux-naming-guidelines.md) - [duplicate] docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos-kintsugi-upgrade-plan-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos-kintsugi-upgrade-plan-v1.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/05_CURRENT_STATE_BASELINE.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/05_CURRENT_STATE_BASELINE.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/10_FIRST_PASS_INTEGRATION_MATRIX.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/10_FIRST_PASS_INTEGRATION_MATRIX.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/11_MIMIC_VS_ANNEX_RULEBOOK.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/11_MIMIC_VS_ANNEX_RULEBOOK.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/12_CANONICAL_OBJECTS_AND_EVENTS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/12_CANONICAL_OBJECTS_AND_EVENTS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/19_OSS_CODE_READING_PLAN.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/19_OSS_CODE_READING_PLAN.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/20_AI_GENERATION_GUARDRAILS.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/20_AI_GENERATION_GUARDRAILS.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/22_IMPLEMENTATION_BACKLOG_TEMPLATE.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/22_IMPLEMENTATION_BACKLOG_TEMPLATE.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/Konnaxion-kintsugi-and-kompendio-open-source-integration-map-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/Konnaxion-kintsugi-and-kompendio-open-source-integration-map-v1.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md) - [duplicate] docs/Technical-Reference/Kintsugi_Kompendio/SmartVote-EkoH-kintsugi-upgrade-v1.md (same content as _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/SmartVote-EkoH-kintsugi-upgrade-v1.md) ================================================================================================ FILE: wiki/CertifiKation.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 7f05825c00c1637aca55b20a1670d0d4b4530c75c1a1071f46c193ae05f76aae CONTENT_BYTES: 946 ================================================================================================ # CertifiKation — KonnectED Certification Capability CertifiKation is the certification/credential capability inside **KonnectED**. It is not a separate ecosystem system. Canonical backend: ```text backend/konnaxion/konnected/ ``` ## Current model families - `CertificationPath`; - `Evaluation`; - `PeerValidation`; - `Portfolio`; - `InteropMapping`. ## Responsibilities - define certification/learning paths; - record evaluation attempts/results; - support peer validation; - maintain user portfolio evidence; - map internal certification concepts to external systems when required. ## Current UI Certification surfaces live under: ```text /konnected/certifications/* ``` including programs, exam preparation/registration and result dashboards. ## Ownership Certification state remains KonnectED-owned. An external attestation or interoperability mapping can be referenced without becoming a second source of certification truth. ================================================================================================ FILE: wiki/EkoH.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: c9f37ca75e07d970bda4917373446a07a62fca6c86b4b8a1696f8d53532ac4fe CONTENT_BYTES: 2009 ================================================================================================ # EkoH — Expertise, Ethics and Rating Access EkoH is a Konnaxion **domain/service boundary**, not a global reputation authority and not a voting engine. Canonical backend: ```text backend/konnaxion/ekoh/ ``` ## Current data model - `ExpertiseCategory` — hierarchical expertise taxonomy; - `UserExpertiseScore` — user/domain expertise score; - `UserEthicsScore` — governed ethics/reliability context; - `ScoreConfiguration` — scoring configuration; - `ScoreHistory` — score-change trace; - `ConfidentialitySetting` — identity privacy; - `RatingVisibilitySetting` — rating visibility policy; - `RatingAccessScope` — hierarchical disclosure scope; - `RatingScopeSubject` — subject membership in a scope; - `RatingAccessGrant` — viewer grant; - `ContextAnalysisLog` — contextual analysis record. ## Expertise semantics Expertise is **domain-bounded**. A high score in one category is not universal authority in another category. The multidimensional scoring path normalizes evidence axes and stores bounded domain scores. Lack of expertise is neutral rather than negative merit. ## Context analysis The current contextual-analysis path is deliberately **non-authoritative**: analysis can be recorded without silently modifying `UserExpertiseScore`. ## Privacy and disclosure Rating visibility is decided server-side. The current access resolver applies a deterministic order including self, staff, scoped grants, public policy and deny behavior. Identity confidentiality and rating visibility are separate policies. ## Smart Vote relationship ```text EkoH context ↓ explicit consultation/lens context ↓ Smart Vote reading ``` EkoH may influence a declared advisory reading. It does not own the source vote/stance and does not assign a universal personal voting power. ## K-Port K-Port is an **EkoH evidence application/gateway**. It can normalize/qualify evidence entering the EkoH boundary; it is not a peer system of Konnaxion and does not own EkoH scores. ================================================================================================ FILE: wiki/Glossary.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: c85c403f9fc891452fcec07271de2c7afbec728ee4eab2bb684ff8787ea8472e CONTENT_BYTES: 2392 ================================================================================================ # Konnaxion Glossary ## Konnaxion An **ecosystem system** in the kOA Digital Ecosystem and a **platform** in its own scope. When hosted by kOA-Linux, it can be described as an **integrated subsystem from the kOA-Linux scope**. That host-relative term does not transfer Konnaxion domain authority. ## Module `module` is a convenient product/UI word, not a precise architecture category. When the category matters, use: ```text module → domain → application → service → component → gateway → interface surface ``` Examples: - Konnaxion — ecosystem system/platform. - EkoH — Konnaxion domain/service boundary. - Smart Vote — Konnaxion reading/aggregation boundary. - K-Port — EkoH evidence application/gateway, not a peer of Konnaxion. - kOA Spaces — subsystem of kOA-Linux, not a Konnaxion owner. ## Source fact Authoritative state owned by the domain that captured it. Examples: - an `EthikosStance`; - a formal consultation ballot. ## Baseline A direct declared aggregation/view of source facts without a contextual Smart Vote lens silently replacing it. ## Reading A derived interpretation of source facts under an explicit lens. ```text Reading = f(SourceFacts, LensDeclaration, SnapshotContext?) ``` ## Lens A declared method and contextual policy used to compute a reading. A lens is not truth and does not own source facts. ## EkoH snapshot The identifiable EkoH contextual inputs used by a reading. A durable/replayable published reading requires those inputs to be recoverable, not merely hashed. ## Korum Logical structured-deliberation sub-domain inside ethiKos. It is implemented primarily in `konnaxion.ethikos`, not as a separate Django app. ## Konsultations Logical consultation/intake/formal-decision source boundary. It is not identical to an Orgo Task or to a Smart Vote reading. ## EkoH Konnaxion domain for expertise taxonomy/scores, ethics/reliability context, privacy and rating access. ## Smart Vote Konnaxion domain for declared derived readings and related aggregation/lens semantics. ## Kollective Intelligence A product/navigation umbrella and compatibility area. It is **not the canonical backend owner** of EkoH or Smart Vote state. ## Gateway A controlled boundary that validates, normalizes, qualifies or routes data. A gateway does not become owner of the destination domain merely by controlling passage. ================================================================================================ FILE: wiki/Home.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: e3627b808a1c4100126cfad965c60b2ceaac2d69292e3a48e0f4dda91e4f342d CONTENT_BYTES: 2715 ================================================================================================ # Konnaxion Konnaxion is an **ecosystem system** in the **kOA Digital Ecosystem** and a **platform** in its own product scope. It coordinates civic deliberation, consultation, contextual expertise, learning, collaboration, creative work, administration and related application surfaces. Konnaxion keeps authority over its own domain state even when it is deployed as a subsystem under kOA-Linux. ## Core architecture rule > **Single Truth, Multiple Readings.** A source fact remains owned by the domain that captured it. A derived reading can interpret that source under an explicit lens, but it does not rewrite the source. ```text source fact ↓ baseline ↓ optional lens + contextual snapshot ↓ derived reading ``` ## Main Konnaxion areas ### Civic / ethiKos - **Korum** — structured deliberation: topics, stances, arguments, evidence, argument impact, participation roles and visibility. - **Konsultations** — consultation/intake/formal decision source boundary. - **Smart Vote** — derived readings and contextual aggregation. - **EkoH** — expertise, ethics/reliability context, privacy and rating access. ### Learning and credentials - **Knowledge** — knowledge resources and learning-library capabilities in KonnectED. - **CertifiKation** — certification paths, evaluations, peer validation, portfolios and interoperability in KonnectED. ### Collaboration and creation - **Konstruct** — project collaboration capabilities implemented in keenKonnect. - **Stockage** — project/document repository capabilities implemented in keenKonnect. - **Kontact** — networking/opportunity UI surface. - **Konservation** — creative/cultural archive and preservation capabilities implemented in Kreative. - **TeamBuilder** — problem/team formation and builder sessions. ### Administration - **Kontrol** — Konnaxion administration, moderation, users/roles, audit and configuration views. ## Architecture pages - [[Konnaxion – Technical Architecture & Services|Konnaxion-#U2013-Technical-Architecture-&-Services]] - [[Glossary]] - [[Implementation Alignment|Implementation-Alignment]] ## Civic pages - [[Korum]] - [[Konsultations]] - [[EkoH]] - [[Smart Vote|Smart-Vote]] ## Learning/collaboration pages - [[Knowledge]] - [[CertifiKation]] - [[Konstruct]] - [[Stockage]] - [[Kontact]] - [[Konservation]] - [[TeamBuilder]] - [[Kontrol]] ## External ecosystem systems Orgo, Kristal, SemantiK Architect and kOA-Linux are **separate ecosystem systems**, not Konnaxion modules. No active Orgo, Kristal or SemantiK Architect adapter is present in the supplied Konnaxion code snapshot. Future integration must use explicit contracts rather than shared internal tables. ================================================================================================ FILE: wiki/Implementation-Alignment.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: a52f33bf48da3a4237e212118aca2bb4929b425e339ea35601bc989268dee2d6 CONTENT_BYTES: 3203 ================================================================================================ # Konnaxion — Implementation Alignment This page lists the current code areas that should change so implementation and architecture use the same ownership model. It is a technical reference, not a project-management log. ## 1. EkoH expertise taxonomy `EthikosTopic.expertise_category` currently references a compatibility taxonomy under `kollective_intelligence`. New canonical references should use `ekoh.ExpertiseCategory`, with the required data/schema migration. ## 2. `kollective_intelligence` compatibility paths The codebase still contains the `konnaxion.kollective_intelligence` package and compatibility vote APIs. New EkoH and Smart Vote functionality should use: ```text konnaxion.ekoh konnaxion.smart_vote ``` rather than creating new canonical state in the compatibility package. ## 3. Konsensus vote API Current Konsensus frontend code still uses the compatibility `kollective/votes/` route and can submit `weighted_value`. Target rule: ```text source ballot ≠ derived reading weight ``` The client should submit source participation only. Smart Vote should calculate a contextual reading separately. ## 4. Smart Vote persisted weighted values The current Smart Vote ballot path persists `Vote.weighted_value` and aggregates `VoteResult.sum_weighted_value`. This path must be reconciled with the reading architecture so the source ballot and the derived contextual interpretation are not one authoritative object. ## 5. Preserve the ethiKos reading path `smart_vote/services/reading_service.py` already follows the correct direction: - reads ethiKos source stances; - uses explicit `SourceConsultationBinding`; - keeps baseline separate; - hashes the lens; - hashes EkoH contextual inputs; - supports advisory-only exclusions without deleting source participation; - filters participant detail through EkoH rating access. Do not collapse this behavior back into ballot-level weighted state. ## 6. Durable reading snapshots The current `snapshot_ref` identifies the EkoH inputs used for an on-demand reading. If a reading is treated as durable/published/replayable, add recoverable snapshot/materialized-reading storage so those exact inputs can be retrieved. ## 7. Consultation relevance validation Validate the full `ConsultationRelevance` vector according to the lens policy: non-negative values plus the declared normalization/sum rule. ## 8. Remove global voting-power UI semantics The current EkoH UI contains a `current-voting-weight` page that presents a person's global Smart Vote influence. Replace this with domain expertise or consultation-specific reading context. There is no universal personal Smart Vote weight in the aligned model. ## 9. Analytics/Pulse source typing Do not mix ethiKos stances, Smart Vote source ballots and Smart Vote derived readings into one untyped participation source. Analytics should declare which source/event type it is counting. ## 10. External ecosystem adapters No active Konnaxion adapter is present for Orgo, Kristal or SemantiK Architect in the supplied snapshot. Add dedicated boundary/adapters only when a concrete use case is implemented; do not import their internal persistence models into Konnaxion. ================================================================================================ FILE: wiki/Knowledge.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 0730dd4e36baeb03c2a17b1810d1f0cbca7e75773c72c51ae52ef2d92d800cc3 CONTENT_BYTES: 945 ================================================================================================ # Knowledge — KonnectED Learning Resources Knowledge is a **capability inside KonnectED**, not an independent ecosystem system. Canonical backend: ```text backend/konnaxion/konnected/ ``` ## Current models - `KnowledgeResource`; - `KnowledgeRecommendation`; - `LearningProgress`; - `OfflinePackage`. KonnectED also contains certification, portfolio, mentorship, co-creation and forum capabilities. ## Current UI Current route families include: ```text /konnected/knowledge/contribute /konnected/learning-library/* /konnected/learning-paths/* ``` ## Offline packages A KonnectED `OfflinePackage` is a Konnaxion learning/content package. It must not be called a Kristal Runtime Pack unless an explicit Kristal integration contract adopts that semantics. ## Ownership KonnectED owns the learning-resource/progress state. Search or recommendation surfaces are projections/capabilities over that state, not alternate sources of truth. ================================================================================================ FILE: wiki/Konnaxion-Technical-Architecture-&-Services.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: d3953c1429182faf510a7e18246d1a34dd98a251844ccdc5581e821b2e6188dc CONTENT_BYTES: 5349 ================================================================================================ # Konnaxion – Technical Architecture & Services ## 1. System identity Konnaxion is a shared full-stack ecosystem system/platform. Current implementation stack: - Next.js + React + TypeScript frontend; - Django + Django REST Framework backend; - PostgreSQL; - Celery + Redis for asynchronous execution; - OpenAPI/drf-spectacular for API description. ## 2. Responsibility map ```text Konnaxion │ ├── shared platform │ ├── users/auth │ ├── moderation/audit │ ├── navigation/search │ └── shared frontend/runtime infrastructure │ ├── ethiKos civic domain │ ├── Korum │ └── Konsultations │ ├── contextual intelligence │ ├── EkoH │ └── Smart Vote │ ├── keenKonnect ├── KonnectED ├── Kreative ├── TeamBuilder ├── Kontrol ├── Konsensus UI └── Reports / Insights ``` Logical responsibility does not require a separate Django app for every named product area. ## 3. Global invariants 1. One authoritative owner per state. 2. No direct cross-domain database write as an integration mechanism. 3. Source facts and derived readings remain distinct. 4. EkoH context does not become a civic vote. 5. Smart Vote does not silently replace the baseline. 6. UI/reporting does not acquire ownership of the data it presents. 7. External ecosystem systems integrate through explicit contracts. ## 4. ethiKos / Korum Canonical backend package: ```text backend/konnaxion/ethikos/ ``` Implemented source objects include: - `EthikosCategory`; - `EthikosTopic`; - `EthikosStance`; - `EthikosArgument`; - `ArgumentSource`; - `ArgumentImpactVote`; - `ArgumentSuggestion`; - `DiscussionParticipantRole`; - `DiscussionVisibilitySetting`. Korum is the logical structured-deliberation capability over these ethiKos-owned records. ## 5. EkoH Canonical backend package: ```text backend/konnaxion/ekoh/ ``` Implemented state includes: - `ExpertiseCategory`; - `UserExpertiseScore`; - `UserEthicsScore`; - `ScoreConfiguration`; - `ScoreHistory`; - `ConfidentialitySetting`; - `RatingVisibilitySetting`; - `RatingAccessScope`; - `RatingScopeSubject`; - `RatingAccessGrant`; - `ContextAnalysisLog`. EkoH expertise is domain-bounded. Its contextual-analysis service records non-authoritative analysis rather than silently mutating expertise scores. Rating disclosure is resolved server-side by the EkoH rating-access service. ## 6. Smart Vote Canonical backend package: ```text backend/konnaxion/smart_vote/ ``` Important current objects: - `Consultation`; - `ConsultationRelevance`; - `SourceConsultationBinding`; - `VoteModality`; - `Vote`; - `VoteResult`; - `VoteLedger`. Current API entry points: ```text POST /api/v1/smart-vote/cast/ GET /api/v1/smart-vote/readings/ethikos-topic// ``` The ethiKos reading path is the canonical architecture pattern to preserve: ```text EthikosTopic / EthikosStance ↓ read only SourceConsultationBinding ↓ ConsultationRelevance + EkoH context ↓ Smart Vote reading ↓ baseline + advisory reading ``` ## 7. keenKonnect Canonical backend package: ```text backend/konnaxion/keenkonnect/ ``` Current model families: - `Project`; - `ProjectResource`; - `ProjectMessage`; - `ProjectTask`; - `ProjectTeam`; - `ProjectRating`; - `Tag`. ## 8. KonnectED Canonical backend package: ```text backend/konnaxion/konnected/ ``` Current model families include certification paths/evaluations, peer validation, portfolio/interoperability, knowledge resources/recommendations, learning progress, offline packages, mentorship, co-creation and forums. ## 9. Kreative Canonical backend package: ```text backend/konnaxion/kreative/ ``` Current model families include artworks, galleries, collaboration sessions, traditions, virtual exhibitions, digital archives/documents, AI catalogue entries and cultural partners. ## 10. TeamBuilder Canonical backend package: ```text backend/konnaxion/teambuilder/ ``` Current core state: - `Problem`; - `ProblemChangeEvent`; - `BuilderSession`; - `Team`; - `TeamMember`. ## 11. Kontrol Canonical backend package: ```text backend/konnaxion/kontrol/ ``` Current state includes `AuditLog`, `ModerationTicket` and `KonsensusConfig`, plus administrative/reporting views. ## 12. Frontend route families Current App Router families include: ```text /ethikos/* /ekoh/* /keenkonnect/* /konnected/* /kreative/* /konsensus/* /kontrol/* /reports/* /teambuilder/* /search ``` A route is a presentation surface, not an ownership declaration. ## 13. External boundaries ### Orgo No active adapter is present in the current snapshot. Future integration must use command/query/event/artifact/receipt semantics. `Orgo Case ≠ EthikosTopic` and `Orgo Task ≠ Konnaxion consultation`. ### Kristal No active adapter is present. If Konnaxion consumes Kristal artifacts, it must preserve Kristal epistemic semantics and must not take ownership of kOA-Linux local Runtime Pack activation. ### SemantiK Architect No active adapter is present. A future integration is a generation/presentation boundary; Architect does not own Konnaxion source state. ### kOA-Linux When Konnaxion is deployed under kOA-Linux, kOA-Linux owns host/platform responsibilities while Konnaxion retains domain authority. ================================================================================================ FILE: wiki/Konservation.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 64255b9c670da3b6dac86674870a18df208627a3598c79fe097f17df6bc0da0d CONTENT_BYTES: 859 ================================================================================================ # Konservation — Kreative Preservation and Archives Konservation is the cultural-preservation/archive capability inside **Kreative**. It is a product capability, not a separate ecosystem system. Canonical backend: ```text backend/konnaxion/kreative/ ``` ## Current preservation/creative models - `KreativeArtwork`; - `Gallery`; - `CollabSession`; - `TraditionEntry`; - `VirtualExhibition`; - `DigitalArchive`; - `ArchiveDocument`; - `AICatalogueEntry`; - `CulturalPartner`; - `Tag`. ## Current UI Relevant surfaces include: ```text /kreative/traditions-archive /kreative/community-showcases/* /kreative/creative-hub/* /kreative/collaborative-spaces/* ``` ## Ownership Archive/catalogue/presentation metadata remains Kreative-owned. AI catalogue assistance or external storage does not silently become the source authority for the cultural object. ================================================================================================ FILE: wiki/Konstruct.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 73f1a81e467595ebcd040bb52fe41a8b6f097cfb9d17e35d9c0877d90757a129 CONTENT_BYTES: 857 ================================================================================================ # Konstruct — keenKonnect Project Collaboration Konstruct is the project-collaboration capability implemented in **keenKonnect**. It is a product capability, not a separate backend owner. Canonical backend: ```text backend/konnaxion/keenkonnect/ ``` ## Current core models - `Project`; - `ProjectResource`; - `ProjectMessage`; - `ProjectTask`; - `ProjectTeam`; - `ProjectRating`; - `Tag`. ## Current UI Project/workspace surfaces include: ```text /keenkonnect/projects/* /keenkonnect/workspaces/* /keenkonnect/ai-team-matching/* ``` ## Task terminology `ProjectTask` is a keenKonnect/Konnaxion project object. It is **not an Orgo Task** unless a future explicit integration contract maps a particular workflow use case. ## EkoH relationship keenKonnect can display or consume declared EkoH context, but EkoH does not become the project owner. ================================================================================================ FILE: wiki/Konsultations.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 9ddae0a14418c0b48891c1ec31c3d3cda976645abf09620843735e514d30b0db CONTENT_BYTES: 1386 ================================================================================================ # Konsultations — Consultation and Formal Participation Konsultations is Konnaxion's logical consultation/intake/formal-participation boundary. The current snapshot contains a dedicated frontend `konsultations` module and ethiKos demo-import structures for consultations and consultation votes. The architecture rule is more important than physical placement: **formal source participation must remain distinct from Smart Vote derived readings and from Korum topic stances.** ## Responsibilities Konsultations covers product capabilities such as: - consultation intake and listing; - consultation detail; - suggestions; - formal participation/vote capture where the protocol calls for it; - result presentation; - impact/accountability timeline. ## Source ownership A formal consultation ballot is a source fact of its consultation protocol. ```text consultation ballot ≠ EthikosStance ≠ Smart Vote reading ≠ Orgo Task ``` ## Smart Vote relationship A consultation can be bound to Smart Vote through an explicit source/consultation mapping. Smart Vote may calculate a contextual reading, but the reading does not overwrite the source ballot. ## Orgo relationship No active Orgo adapter is implemented in the current Konnaxion snapshot. A future workflow integration must treat Orgo Case/Task as external workflow objects, not as aliases for Konnaxion consultations. ================================================================================================ FILE: wiki/Kontact.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 69ebd975e5bc96d7e7d2a305b6943c0b51659b9256a38fb347ba609e2b6f0cee CONTENT_BYTES: 786 ================================================================================================ # Kontact — Networking and Opportunities Surface Kontact is a **Konnaxion application/interface capability**, not a separate ecosystem system. The current snapshot contains a frontend module under: ```text frontend/modules/kontact/ ``` with profile/opportunity UI including: - `ProfileCard`; - `OpportunityList`; - `ConnectCenter`; - `PublicProfile`; - profile/opportunity hooks. ## Architecture rule Kontact is a presentation/interaction surface. It must use the authoritative Konnaxion owner for profile, opportunity, project or EkoH data rather than creating a parallel backend truth simply because the UI groups those concepts. If a dedicated backend capability is added later, its ownership must be declared explicitly rather than inferred from the frontend module name. ================================================================================================ FILE: wiki/Kontrol.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 77c2df1b8dc7edc479b75b4fe682b6fe675bb7a7b34b7fd2fe3bb6c7b91901a1 CONTENT_BYTES: 671 ================================================================================================ # Kontrol — Administration and Moderation Kontrol is Konnaxion's administrative application surface. Canonical backend: ```text backend/konnaxion/kontrol/ ``` ## Current state - `AuditLog`; - `ModerationTicket`; - `KonsensusConfig`. The backend also exposes administration/reporting views for usage, performance and Smart Vote reporting. ## Current UI ```text /kontrol/dashboard /kontrol/audit-log /kontrol/moderation/* /kontrol/users/all /kontrol/roles /kontrol/konsensus ``` ## Ownership rule Kontrol may present and administrate multiple Konnaxion domains, but the existence of an admin screen does not transfer the underlying domain ownership to Kontrol. ================================================================================================ FILE: wiki/Korum.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 0ede27c038b633ebaf4093b1808de075462b2fe6835c608ad025780af8fdac0e CONTENT_BYTES: 1496 ================================================================================================ # Korum — Structured Deliberation Korum is the logical structured-deliberation capability inside the ethiKos domain. It is implemented primarily in `konnaxion.ethikos`; it is not a separate source-of-truth database. ## Current source state - `EthikosTopic` — deliberation topic; - `EthikosStance` — user's topic-level stance; - `EthikosArgument` — argument/reply node; - `ArgumentSource` — evidence/source material attached to an argument; - `ArgumentImpactVote` — argument-level impact evaluation; - `ArgumentSuggestion` — proposed contribution/change; - `DiscussionParticipantRole` — participant role; - `DiscussionVisibilitySetting` — visibility policy. ## Important separations ```text ArgumentImpactVote ≠ EthikosStance EthikosStance ≠ Smart Vote reading EthikosArgument ≠ Orgo Task EthikosTopic ≠ Orgo Case ``` Topic stance and argument impact represent different participation semantics. ## API ownership The current API is under the ethiKos boundary (`/api/ethikos/*`) with compatibility UI-facing aliases under `/api/deliberate/*` where present. Those aliases do not create another owner. ## UI The main current deliberation surface is under: ```text /ethikos/deliberate/* ``` including topic views, guidelines and elite/read-only variants. ## Smart Vote relationship Korum source state can be an input to a Smart Vote reading. Smart Vote reads the source and returns a separate reading; it does not rewrite `EthikosStance` or the argument graph. ================================================================================================ FILE: wiki/Smart-Vote.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: a018384fb077e9c6fec23ba5127c9878dac8b6b05a195cf4c47afe866d410713 CONTENT_BYTES: 1901 ================================================================================================ # Smart Vote — Contextual Readings Smart Vote owns **declared derived readings**, lens semantics and related aggregation. It does not own the source facts it interprets. Canonical backend: ```text backend/konnaxion/smart_vote/ ``` ## Core rule ```text source participation ≠ baseline ≠ contextual reading ``` For ethiKos: ```text EthikosTopic + EthikosStance ↓ source facts baseline aggregation ↓ SourceConsultationBinding ConsultationRelevance EkoH context ↓ Smart Vote advisory reading ``` ## Current API ```text POST /api/v1/smart-vote/cast/ GET /api/v1/smart-vote/readings/ethikos-topic// ``` The reading endpoint exposes a baseline and a separate `ekoh_weighted_v1` reading when a binding exists. ## Current reading metadata The reading service produces, among other fields: - `reading_key`; - `lens_hash`; - `snapshot_ref`; - `computed_at`; - result payload; - participant-level trace/detail when allowed by rating-access policy. ## Contextual weight A Smart Vote weight is specific to the declared consultation/lens/context. It is **not a permanent global voting power attached to the user**. ## Advisory exclusions A declared advisory exclusion can set a participant's reading weight to zero while leaving the source stance in the baseline. This preserves source history and makes the advisory transformation explicit. ## Reproducibility The current service hashes the EkoH input snapshot used for a reading. If a reading is treated as durable/published/replayable, the corresponding inputs must also be recoverable; a hash alone identifies data but does not store it. ## Implementation alignment The older ballot path still contains `Vote.weighted_value` and `VoteResult.sum_weighted_value`. These should not become the architecture model for source participation. See [[Implementation Alignment|Implementation-Alignment]]. ================================================================================================ FILE: wiki/Stockage.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: b871781be7f0c120748524bf83997bf0ce327125428f76b2d1f7e3dac62235e0 CONTENT_BYTES: 1013 ================================================================================================ # Stockage — keenKonnect Knowledge and Project Resources Stockage is the project/document repository capability inside **keenKonnect**. It is not a separate system or database owner. Current physical owner: ```text backend/konnaxion/keenkonnect/ ``` ## Current core objects - `ProjectResource` — resource/document reference attached to a project; - `Project` — project/workspace context; - `ProjectTeam` — membership/role context; - `Tag` — classification. ## Current UI The current product exposes knowledge/document surfaces under: ```text /keenkonnect/knowledge/browse-repository /keenkonnect/knowledge/document-management /keenkonnect/knowledge/search-filter-documents /keenkonnect/knowledge/upload-new-document ``` ## Ownership A search index, preview, cache or document browser remains a projection over the resource owner. It does not become a second source of project/document truth. Do not invent versioning/ACL persistence tables unless they exist in the code/schema being updated. ================================================================================================ FILE: wiki/TeamBuilder.md AUTHORITY: reference CONTENT_ROLE: navigation CONTENT_SHA256: 5844cb8450a89de3cf05913dadb8e2ef1a484a192adfa64b464d84413d59a3e0 CONTENT_BYTES: 705 ================================================================================================ # TeamBuilder — Problem and Team Formation TeamBuilder is a Konnaxion application/domain capability for problem framing, builder sessions and team formation. Canonical backend: ```text backend/konnaxion/teambuilder/ ``` ## Current core models - `Problem`; - `ProblemChangeEvent`; - `BuilderSession`; - `Team`; - `TeamMember`. ## Current UI ```text /teambuilder /teambuilder/create /teambuilder/problems/* /teambuilder/[sessionId] /teambuilder/humans/* ``` ## Orgo boundary A TeamBuilder `Problem`, `BuilderSession` or team is not an Orgo Case/Task by identity. A future integration may create Orgo-governed work through an explicit boundary, but the Konnaxion objects keep their own semantics. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Konnaxion_User_Workflows.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: a6ac49c9193a9a0dd0712b05480bc0ec9cf9a1fe93a3c7f68d309a8c6d87a039 CONTENT_BYTES: 2887 ================================================================================================ # Konnaxion — User Workflows ## 1. Scope These workflows describe current Konnaxion product surfaces without treating every UI area as an independent architecture system. ## 2. Shared entry ```text user → Konnaxion frontend → authenticated/public context → product surface → Konnaxion API/service owner → result ``` Shared navigation/search/auth may cross product surfaces, but domain mutations remain owned by their backend domain. ## 3. ethiKos — deliberate ```text open topic → read source/context → inspect argument graph → add argument/reply/source when authorized → optional stance update → moderated/audited ethiKos state ``` Topic stance and argument-level impact are separate interactions. ## 4. ethiKos — decision result ```text source stances → baseline aggregation → display baseline → optional Smart Vote reading request → display declared advisory reading separately ``` If no Smart Vote reading exists, the UI displays no derived reading rather than inventing one. ## 5. EkoH profile ```text viewer requests profile → identity confidentiality policy → rating-access policy → allowed EkoH fields → profile response ``` The viewer does not receive private rating detail merely because identity is visible. ## 6. Smart Vote contextual reading ```text source topic → explicit SourceConsultationBinding → consultation relevance vector → EkoH context → lens hash + input snapshot identity → baseline + advisory reading ``` A contextual reading weight is specific to the consultation/lens. It is not a global property of the person. ## 7. keenKonnect ```text browse/create project → project workspace → teams/resources/tasks/messages → domain services → project state ``` EkoH context may be displayed for people but does not own the project. ## 8. KonnectED ```text browse learning resource/path → consume/contribute/evaluate → peer validation or certification workflow when applicable → portfolio/progress state ``` ## 9. Kreative ```text browse/create creative work → gallery/collaboration/archive/tradition surface → owner service mutation → updated creative domain state ``` ## 10. TeamBuilder ```text select/create problem → builder session → teams/members → problem/team state updates ``` TeamBuilder objects are Konnaxion objects; they are not Orgo Case/Task objects. ## 11. Kontrol ```text admin enters Kontrol → authorization → moderation/users/roles/audit/config surface → underlying Konnaxion owner service → result ``` Kontrol is an administrative UI, not a replacement owner for every domain it displays. ## 12. External system workflows No concrete Orgo/Kristal/SemantiK Architect workflow is implemented in the current Konnaxion snapshot. When added, the UI/backend must call an explicit adapter and preserve both systems' ownership boundaries. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/status/2026-08-28-technical-maturity-assessment.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 0cbdf32a387dff582bc1840193eedaa3ba2c370e2ab50cf873a97b2520185cfb CONTENT_BYTES: 15898 ================================================================================================ # Konnaxion Technical Maturity Assessment **Assessment date:** 2026-08-28 **Previous assessment:** 2026-08-27 **Current status:** Advanced Functional Beta — Integration and Release Hardening **Estimated engineering maturity:** ~85% **Estimated Release Candidate readiness:** ~68–72% > This assessment is a technical maturity checkpoint. It is not a Release Candidate declaration. Percentages are engineering estimates based on validated implementation and qualification evidence, not mathematical completion metrics. ## Executive summary Konnaxion has materially advanced since the 2026-08-27 assessment. The strongest change is not additional feature breadth but **qualification depth**. During the latest campaign, the backend was validated against a fresh unique PostgreSQL test database, the principal ethiKos → EkoH → Smart Vote workflow passed strict browser automation, authenticated write paths passed, broad frontend route coverage reached 112 of 114 routes, and production/security configuration was inspected and hardened. The platform is therefore no longer best described simply as a broad functional beta with uneven evidence. Its core deliberation and advisory path now has substantial end-to-end evidence, and backend correctness is considerably stronger than in the previous assessment. The most accurate current classification is: **Advanced Functional Beta — Integration and Release Hardening** Konnaxion is still **not a Release Candidate**. The remaining gap is increasingly concentrated in release engineering and platform-wide qualification rather than the core ethiKos/EkoH/Smart Vote product path. ## Maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 88–92% | | Backend implementation | 88–92% | | Frontend implementation | 82–87% | | ethiKos | 92–95% | | EkoH | 92–95% | | Smart Vote | 90–94% | | TeamBuilder | 70–75% | | Kontrol | 65–72% | | KonnectED | 62–68% | | keenKonnect | 58–65% | | Kreative | 45–55% | | Automated testing | 78–84% | | End-to-end user workflows | 85–90% | | Application security maturity | 78–84% | | Deployment and packaging | 72–78% | | CI and release qualification | 52–60% | | Backup / restore qualification | 45–55% | | Overall engineering maturity | ~85% | | RC readiness | ~68–72% | ## Qualification evidence completed ### 1. Backend full-suite qualification A clean backend campaign was completed against a fresh unique PostgreSQL test database. **Validated result:** - **137 tests passed** - **0 failures** - fresh schema creation succeeded - Django system checks passed - migrations are viable on a fresh database - previous TeamBuilder routing and backend test defects were corrected - no backend rerun is currently required unless backend code changes This closes the previous blocker to reach zero backend test failures for the currently collected backend suite. ### 2. Backend routing normalization The TeamBuilder REST routing was normalized around the canonical API router. Validated changes included: - TeamBuilder resources registered in `backend/config/api_router.py`; - redundant TeamBuilder include removed from `config/urls.py`; - local TeamBuilder router removed from the canonical path; - reverse names aligned to the central `api:*` namespace; - Django checks remained clean after routing normalization. ### 3. Frontend type safety TypeScript qualification is green. Validated multiple times: ```text pnpm run typecheck tsc --noEmit ``` **Result: PASS** The latest final qualification run again produced `[PASS] Typecheck`. ### 4. Frontend production build A complete production build had previously passed with: - Next.js 15.3.1; - successful optimized production build; - **115 / 115 static pages generated**. During the final 2026-08-28 post-hardening rerun, the build was blocked before compilation by a Windows filesystem error: ```text EPERM: operation not permitted, open '.next\trace' ``` This is currently classified as a **local build-artifact/process locking issue**, not a demonstrated product regression. However, because the build did not complete after the latest production-configuration overlay, a fresh post-overlay production-build pass remains desirable before pre-RC. ### 5. Broad frontend route smoke A broad real-browser route campaign validated: - **112 passed** - **2 timed out** - **114 total routes** - pass rate: **98.25%** The only unresolved route-smoke boundaries were: ```text /konnected/community-discussions/moderation /teambuilder/create ``` The rest of the surveyed route surface rendered successfully. ### 6. Strict public ethiKos → EkoH → Smart Vote workflow The principal public Wave 1 workflow is formally green. Validated browser path: ```text Canada deliberation → narrative → Réjean EkoH drawer → King Klown / Trump emergent question → DEMO FICTION source disclosure → conflict disclosure → recusal → Smart Vote readings ``` Verified Smart Vote assertions included: - baseline: **7 source stances** - advisory: **6 participants** - declared recusals: **1** - King Klown advisory status: **Recused** - King Klown advisory weight: **0.00×** Final strict result: ```text 1 passed (57.6s) Wave 1 exit code: 0 ``` A prior 90-second global timeout was demonstrated to be a harness budget issue rather than a failed product assertion. ### 7. Authenticated ethiKos write workflow The authenticated workflow is green. An initial failure was traced to a stale test assumption: the seeded consultation existed and was open, but pagination placed it outside page 1. The product API returned the seeded topic correctly, and the test was corrected to search before asserting visibility. Final authenticated result: ```text Running 2 tests using 1 worker 2 passed (25.9s) Authenticated workflow exit code: 0 ``` This validates both authentication and authenticated write-flow integration for the tested ethiKos path. ### 8. Breadcrumb defect correction A real frontend defect was identified and corrected in the ethiKos insights path. The header generated duplicate breadcrumb React keys because a synthetic ethiKos root and the current Overview page resolved to the same normalized path. The correction normalized paths, deduplicated semantically, retained the current/last breadcrumb, and avoided an index-key workaround. Validation after the correction showed: - typecheck PASS; - duplicate key count: 0; - page errors: 0. A subsequent styled-components hydration mismatch disappeared after clearing `.next` and restarting the frontend, and was classified as stale Turbopack/HMR state rather than a remaining product defect. ### 9. Production/security configuration qualification A dedicated read-only production/security gate was executed without Docker, migrations, restore operations, or secret disclosure. The initial inspection produced: ```text PASS: 40 WARN: 6 FAIL: 4 ``` The four failures were: - missing production `FRONTEND_BASE_URL`; - production hostname absent from `ALLOWED_HOSTS`; - frontend base resolving to localhost; - OpenAPI advertising `konnaxion.local`. These findings were aligned with project deployment documentation and corrected. The subsequent production/security rerun validated: - `DEBUG=False`; - `ALLOWED_HOSTS` contains `konnaxion.com`; - `ALLOWED_HOSTS` contains `www.konnaxion.com`; - `FRONTEND_BASE_URL=https://konnaxion.com`; - OpenAPI advertises `https://konnaxion.com`; - `SECURE_SSL_REDIRECT=True`; - secure session cookie; - secure CSRF cookie; - HttpOnly session cookie; - HttpOnly CSRF cookie; - `X_FRAME_OPTIONS=DENY`; - `SECURE_CONTENT_TYPE_NOSNIFF=True`; - HSTS enabled; - `manage.py check --deploy` PASS. The final production/security subprocess reported: ```text Django production failures: 0 [PASS] Django production/security gate ``` ### 10. Flower exposure hardening The production deployment configuration previously exposed Flower through port 5555. The deployment alignment removed the public exposure. Validated: ```text [PASS] Traefik does not expose Flower :5555 [PASS] Compose does not publish 5555:5555 ``` ### 11. Backup / restore surface inspection Konnaxion contains real PostgreSQL maintenance scripts for backup, backup listing, restore and backup removal. The backup implementation was verified to use `pg_dump + gzip`. The restore implementation was correctly identified as destructive: ```text drop database → create database → restore ``` This is useful operational infrastructure, but **existence of scripts is not equivalent to restore qualification**. A real restore drill against an isolated disposable database is still required before stronger release-readiness claims can be made. ## Remaining warnings and technical debt ### OpenAPI / drf-spectacular `manage.py check --deploy` passes, but currently emits **23 drf-spectacular issues**. They include unresolved serializer type hints, duplicate schema component names, duplicate operation IDs, APIViews where serializers cannot be inferred, and an untyped path parameter. These do not currently fail Django deployment checks, but they reduce OpenAPI quality and should be cleaned up before a polished public API contract is declared stable. ### Next.js API fallback The latest final gate still detected `localhost:8000` inside `frontend/next.config.ts`. Therefore the production API fallback cleanup is **not yet fully closed** and remains an explicit release-hardening item. ### Frontend lint gate The production Next configuration still allows ESLint failures to be ignored during build. This is **release-tooling debt**, not a demonstrated runtime defect. Before RC, lint should become a reliable mandatory gate. ### Jest The Jest gate remains tooling-degraded because the current configuration path previously encountered malformed or incompatible TypeScript configuration parsing before meaningful tests executed. This is not evidence of a product defect, but it means the frontend unit-test gate is not currently release-grade. ### Playwright component tests The component-test gate previously reported no tests found and a reporter/output configuration collision. Component testing therefore remains incomplete as a release gate. ### Test orchestration scripts Inspection of the existing frontend scripts showed that the aggregate qualification tooling is not yet trustworthy as a single release command. Known issues include: - `50-all.ps1` chaining currently broken/degraded gates; - `40-backend-tests.ps1` assuming a backend path inconsistent with the actual repository layout. The tests themselves can be run successfully, but the release orchestration should be repaired before RC. ### PowerShell interactive block behavior Several manually pasted PowerShell scripts produced `else: The term 'else' is not recognized` because an interactive shell executed the preceding `if` block before the separately pasted `else`. This does **not** invalidate the underlying test commands or PASS results. ## Module interpretation ### ethiKos — 92–95% ethiKos now has backend models/APIs/migrations, real seeded workflow data, public deliberation workflow, source and conflict disclosures, recusal behavior, authenticated write-path coverage, and strict Playwright E2E validation. ### EkoH — 92–95% EkoH remains one of the most mature functional areas, with strict workflow integration, contextual expertise presentation, advisory participation, and recusal-aware downstream reading behavior. ### Smart Vote — 90–94% Smart Vote has strong integration evidence across baseline readings, advisory readings, weighting, recusal, source stance counts and participant counts. ### TeamBuilder — 70–75% TeamBuilder benefited from backend routing normalization and participates in the full backend green test suite. However, `/teambuilder/create` remains one of the two broad route-smoke timeouts. ### KonnectED — 62–68% KonnectED is implemented across multiple routes and backend models, but `/konnected/community-discussions/moderation` remains the other unresolved route-smoke timeout. ### Kontrol / keenKonnect / Kreative These remain implemented but less deeply qualified than the ethiKos/EkoH/Smart Vote core. The maturity limitation is primarily **evidence depth**, not necessarily absence of code. ## Progress against the previous pre-RC blockers The 2026-08-27 assessment listed ten major requirements. ### 1. Define exact Version 1 release scope **Still open.** ### 2. Complete or explicitly defer unfinished product surfaces **Still open.** ### 3. Reach zero backend test failures **Completed for the currently collected backend suite.** Validated: **137 passed, 0 failed**. ### 4. Make typecheck, lint, and production build mandatory **Partially completed.** - typecheck: green; - production build: previously green, latest rerun blocked by `.next\trace` EPERM; - lint: not yet a mandatory reliable release gate. ### 5. Expand automated testing to poorly covered modules **Improved, still open.** ### 6. Convert major Playwright workflows into mandatory release gates **Substantially improved.** The public strict Wave 1 and authenticated workflow are now strong candidates for mandatory release gates. ### 7. Test clean installation and migration paths **Partially completed.** Fresh backend test schema creation and migrations are validated, but a complete clean deployment/install procedure is not yet qualified. ### 8. Test backup and restore **Not completed.** Scripts exist and were inspected, but no isolated end-to-end restore drill has been completed. ### 9. Qualify deployment reproducibility **Partially completed.** Production settings and deployment configuration are more consistent and security-checked, but full reproducible deployment remains unproven. ### 10. Establish a versioned and repeatable release process **Still open.** ## Main blockers before pre-RC 1. define the exact Version 1 release scope; 2. explicitly complete or defer secondary product surfaces; 3. rerun the production frontend build after clearing the local `.next` lock; 4. remove or explicitly constrain the remaining `localhost:8000` production fallback; 5. repair Jest and Playwright component-test gates; 6. make lint a reliable mandatory release gate; 7. repair the aggregate release/test orchestration scripts; 8. resolve or disposition the two remaining route-smoke timeouts; 9. execute backup → isolated restore → application validation; 10. qualify deployment reproducibility from a clean target; 11. reduce OpenAPI/drf-spectacular schema warnings; 12. establish the versioned repeatable release process. ## Release interpretation Konnaxion has crossed an important threshold. The core product path is no longer merely implemented; it is now backed by meaningful automated integration evidence. The remaining release gap is concentrated in breadth of platform qualification, release automation, deployment reproducibility, backup/restore evidence, tooling cleanup and final scope control. Current estimate: > **Engineering maturity: ~85%** > **Release Candidate readiness: ~68–72%** ## Recommended public status **Advanced Functional Beta — Integration and Release Hardening** Suggested short description: > Konnaxion has reached an advanced functional beta with substantially strengthened integration evidence. The backend test suite passes on a fresh database, the principal ethiKos → EkoH → Smart Vote workflow is validated end to end, authenticated write paths are green, and production/security configuration has been hardened. Remaining work is concentrated in release automation, secondary-surface qualification, reproducible deployment, backup/restore drills, OpenAPI cleanup, and final release-scope control. This is not yet a Release Candidate. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/status/ETHIKOS_EKOH_SMARTVOTE_DELIVERY_WORKFLOW.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 92f2989dd33424a24c7cdff95ef6b2a227748d473ee661e627a6ffd8fb3d4cc7 CONTENT_BYTES: 4901 ================================================================================================ # ethiKos / EkoH / Smart Vote — Delivery Workflow ## Purpose This is the release-acceptance golden path for the currently demonstrable Konnaxion civic-decision slice. It does **not** replace the existing smoke and technical workflows. It composes the already-green behaviors into one delivery proof while preserving their test isolation. ## Architectural invariants proved - ethiKos owns the source deliberation state. - EkoH supplies contextual/domain expertise and disclosure context. - Smart Vote reads the source state and returns a separate declared advisory reading. - The public baseline remains visible and distinct from the advisory reading. - A declared recusal remains in the source baseline while receiving advisory weight `0.00×`. - Authentication is real and a user can write a canonical ethiKos stance. - Public Decide writes the canonical stance rather than a client-authored derived weight. - No legacy Kialo/Kintsugi/Korum API-owner route drift is accepted. - No unexpected 4xx/5xx, page error, or runtime/build error is accepted. ## Why the workflow uses two seeded topics The cinematic topic is intentionally deterministic. Its baseline/readings assert seven source stances, six advisory participants, and one declared recusal. The delivery workflow therefore treats it as **read-only**. A separate seeded workflow topic (`Should public datasets require consent receipts?`) is used for the authenticated write proof. Its stance is upserted, so repeated delivery runs do not grow duplicate stance rows. This preserves the cinematic Smart Vote evidence while still proving real authenticated participation. ## Automated path 1. Authenticate through the existing `auth.setup.ts` flow. 2. Verify `/api/users/me/`. 3. Open Deliberate · Elite. 4. Open the Canada/US cinematic topic. 5. Verify the structured argument thread and moderation scene. 6. Open Réjean's EkoH context and verify contextual/domain expertise. 7. Open the emergent AI-access governance question. 8. Verify conflict evidence and voluntary recusal. 9. Open Smart Vote readings and verify: - 7 source stances; - 6 advisory participants; - 1 declared recusal; - King Klown advisory weight `0.00×`; - the contextual-expertise principle. 10. Verify the Smart Vote API exposes: - baseline; - a declared reading; - `reading_key`; - `lens_hash`; - `snapshot_ref`. 11. Open the separate authenticated participation topic. 12. Change and save the user's topic stance through the real UI. 13. Open Decide · Public, select Agree, and cast the vote through the real UI. 14. Open and verify the delivery surfaces: - Decide · Results; - Voting methodology; - EkoH trust/profile; - Impact tracker; - Pulse · Overview; - Ethikos overview/Insights. 15. Write machine-readable delivery evidence. ## Commands Headless acceptance gate: ```powershell cd C:\mycode\Konnaxion\Konnaxion\frontend pnpm run delivery:ethikos ``` Visible demonstration: ```powershell cd C:\mycode\Konnaxion\Konnaxion .\RUN_ETHIKOS_DELIVERY_WORKFLOW.ps1 -Headed ``` Open the last HTML report: ```powershell cd C:\mycode\Konnaxion\Konnaxion\frontend pnpm run delivery:ethikos:report ``` ## Required local runtime - Django: `http://localhost:8000` - Next.js: `http://localhost:3000` - the standard `ethikos_seed_user` test account, unless overridden by environment variables; - the Kintsugi Wave 1 / Canada-Québec demonstration seed; - the authenticated workflow seed topic. Do not mix `localhost` and `127.0.0.1` between frontend and backend for this acceptance run. The test fails early with a clear message when their cookie hostnames differ. ## Environment overrides Optional: ```text BACKEND_BASE_URL SMOKE_BASE_URL PLAYWRIGHT_AUTH_STATE ETHIKOS_TEST_USERNAME ETHIKOS_TEST_EMAIL ETHIKOS_TEST_PASSWORD ETHIKOS_DELIVERY_CINEMATIC_TOPIC_TITLE ETHIKOS_DELIVERY_CINEMATIC_TOPIC_ID ETHIKOS_DELIVERY_WRITE_TOPIC_TITLE ETHIKOS_DELIVERY_WRITE_TOPIC_ID ``` ## Evidence output The test creates: ```text frontend/artifacts/ethikos-delivery-workflow/ ``` including screenshots and: ```text delivery-evidence.json ``` The JSON records the authenticated user, both topic IDs, Smart Vote reading identity/hash/snapshot information, visited routes, write proof, and runtime findings. The Playwright HTML report is written to: ```text frontend/artifacts/playwright-delivery-html/ ``` ## Success criterion The delivery gate is green only when: - auth succeeds; - the cinematic topic and its EkoH/Smart Vote evidence are present; - real stance/vote writes succeed; - the delivery surfaces load without runtime findings; - Smart Vote exposes a real declared reading with lens and EkoH snapshot identity. Expected console summary is two passed tests because Playwright reports the auth setup dependency and the single delivery acceptance spec separately: ```text 2 passed ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH - System Overview.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: bb1d5b7bc1eed33e8b0c04421076ee28a01dc3ac35dd71763b0c646a68add9d1 CONTENT_BYTES: 1728 ================================================================================================ # EkoH — System Overview ## Purpose EkoH is Konnaxion's contextual expertise, ethics/reliability and rating-access domain. It answers questions such as: - what expertise domains are demonstrated by a participant; - what evidence/rules produced a score; - what rating detail a viewer is allowed to see; - what contextual snapshot may be used by a declared Smart Vote reading. EkoH does **not** decide civic outcomes and does not own source ballots or ethiKos stances. ## Canonical backend ```text backend/konnaxion/ekoh/ ``` Canonical model families: - expertise taxonomy; - per-user/domain expertise score; - ethics/reliability context; - score configuration/history; - confidentiality; - rating visibility/access scopes/grants; - contextual analysis log. ## Expertise Expertise is domain-bounded. A score in one domain does not create universal authority in another. The current scoring service normalizes evidence axes to `0..1` and computes a domain score. Absence of expertise is neutral, not negative merit. ## Context analysis The current code correctly treats AI-assisted contextual analysis as a proposal/analysis record. It does not directly mutate authoritative expertise scores. ## Privacy and rating access Identity confidentiality and rating visibility are separate. `resolve_rating_access()` is the current server-side disclosure authority and resolves: 1. self; 2. staff; 3. scoped access grants; 4. public policy; 5. deny. ## Relationship to Smart Vote ```text EkoH context ↓ explicit snapshot / current contextual input ↓ Smart Vote lens ↓ derived reading ``` EkoH supplies context. Smart Vote owns the reading. The source civic domain owns the source participation event. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Data Model.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 7ee22efbcd42297f264ecb5fe0ce36d43e96b733cdb745ff81c3cab4be016298 CONTENT_BYTES: 1565 ================================================================================================ # EkoH and Smart Vote — Data Model ## Canonical EkoH models ```text ExpertiseCategory UserExpertiseScore UserEthicsScore ScoreConfiguration ScoreHistory ConfidentialitySetting RatingVisibilitySetting RatingAccessScope RatingScopeSubject RatingAccessGrant ContextAnalysisLog ``` ## Canonical Smart Vote context models ```text Consultation ConsultationRelevance SourceConsultationBinding ``` ## Current Smart Vote ballot/aggregate models ```text VoteModality Vote VoteResult VoteLedger ``` These physical models exist in the current code. Their use must obey the architecture rule that source participation and derived weighting are distinct. `weighted_value` and weighted aggregate state are not a substitute for a versioned reading contract. ## Binding `SourceConsultationBinding` uses: ```text source_type source_id source_key consultation metadata_json ``` For ethiKos: ```text source_type = "ethikos_topic" source_id = string form of EthikosTopic primary key ``` This preserves source ownership and avoids title-based matching. ## Relevance `ConsultationRelevance` binds a Smart Vote consultation to an EkoH `ExpertiseCategory` with a weight and optional criteria metadata. Input validation should ensure the relevance vector is non-negative and normalized according to the declared lens policy. ## Reading A reading is not currently represented by a dedicated persisted model in the inspected code; the ethiKos reading endpoint computes it on demand. Durable publication/replay requires persistent or recoverable inputs/reading artifacts. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 619b1bcab623d2d5fdd9df15732e1a8551e6558d0d1c8f072f531107eec2b6c6 CONTENT_BYTES: 2286 ================================================================================================ # EkoH and Smart Vote — Technical Specification ## 1. Ownership ```text ethiKos / consultation owner source participation facts EkoH expertise / ethics / access context Smart Vote lens + derived reading ``` These responsibilities remain separate even when their tables share a PostgreSQL search-path scope. ## 2. EkoH code Primary packages: ```text backend/konnaxion/ekoh/models/ backend/konnaxion/ekoh/services/ backend/konnaxion/ekoh/views/ ``` Important services: - `multidimensional_scoring.py` — domain score computation; - `contextual_analysis.py` — non-authoritative analysis intake; - `rating_access.py` — disclosure policy authority. ## 3. Smart Vote code Primary packages: ```text backend/konnaxion/smart_vote/models/ backend/konnaxion/smart_vote/services/ backend/konnaxion/smart_vote/views/ backend/konnaxion/smart_vote/tasks/ ``` Important reading path: - `SourceConsultationBinding` explicitly binds a source object to a Smart Vote consultation; - `ConsultationRelevance` defines relevant EkoH domains; - `reading_service.py` reads ethiKos stances and EkoH context; - `EthikosTopicReadingView` exposes the derived reading. ## 4. Current strong alignment The following existing behaviors should remain: - ethiKos stances are read-only inputs to the reading service; - a source binding is explicit rather than guessed by title; - lens identity is content-hashed; - EkoH input identity is hashed into `snapshot_ref`; - baseline and advisory result are separate; - advisory exclusions do not delete source stances; - participant details are filtered by server-side rating access; - contextual AI analysis does not silently mutate expertise scores. ## 5. Remaining implementation alignment The older Smart Vote ballot/aggregation path still stores `weighted_value` directly on `Vote` and aggregates it into `VoteResult`. That path must be reconciled with the reading architecture so that a source ballot and a derived reading are not the same stored object. The UI must not present a global `Smart Vote Weight`. Smart Vote influence is contextual to an explicit consultation/lens; implementation exceptions are listed in `../CODE_ALIGNMENT_NOTES.md`. See `../CODE_ALIGNMENT_NOTES.md` for exact paths. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-module-file-architecture.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: f721021486ac9291891d4e7acc46e026dae7ccd701930f1474be1299b8ffb002 CONTENT_BYTES: 2865 ================================================================================================ F**ile architecture for the EkoH module alone** (everything lives under `modules/ekoh-smartvote/ekoh/`): ekoh/ \# Django app root (namespace: konnaxion.ekoh) ├── \_\_init\_\_.py ├── apps.py \# EkohConfig – sets default schema search\_path ├── models/ \# One file per logical group │ ├── \_\_init\_\_.py │ ├── taxonomy.py \# ExpertiseCategory (UNESCO codes) │ ├── scores.py \# UserExpertiseScore, UserEthicsScore │ ├── config.py \# ScoreConfiguration (weights) │ ├── privacy.py \# ConfidentialitySetting │ ├── audit.py \# ContextAnalysisLog, ScoreHistory │ └── signals.py \# cross-model hooks ├── migrations/ │ ├── 0001\_initial.py \# creates schema ekoh\_smartvote \+ tables │ ├── 0002\_unesco\_fixture.py │ └── 0003\_partition\_helpers.py ├── serializers/ \# DRF serializers split by concern │ ├── \_\_init\_\_.py │ ├── profile.py │ ├── score\_admin.py │ └── audit.py ├── views/ │ ├── \_\_init\_\_.py │ ├── profile.py \# /ekoh/profile/:uid (GET) │ ├── admin.py \# /ekoh/score/recalc (POST) │ └── bulk\_ingest.py \# /ekoh/score/bulk ├── urls.py \# router for the three viewsets ├── services/ \# pure-logic (no Django imports) │ ├── \_\_init\_\_.py │ ├── multidimensional\_scoring.py │ ├── contextual\_analysis.py │ ├── ethics\_evaluator.py │ └── taxonomy\_loader.py ├── tasks/ │ ├── \_\_init\_\_.py │ ├── recalc.py \# Celery task ekoh\_score\_recalc │ ├── contextual.py \# contextual\_analysis\_batch │ └── emerging\_expert.py ├── fixtures/ │ └── isced\_f\_2013.json ├── admin.py \# Django admin registrations ├── tests/ \# pytest; 90 % coverage target │ ├── \_\_init\_\_.py │ ├── test\_models.py │ ├── test\_services.py │ └── test\_api.py └── README.md \# stand-alone quick-start for Ekoh app Key points: * **Self-contained:** no imports from Konnaxion core; only depends on `auth_user` table. * **Schema isolation:** every migration opens with `schema_editor.execute("SET search_path TO ekoh_smartvote,public")`. * **Pip-installable:** `pyproject.toml` at `modules/ekoh-smartvote/` exposes `konnaxion.ekoh` as a namespace package. * **Dev seed:** `manage.py loaddata fixtures/isced_f_2013.json` loads the domain taxonomy. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-canonical-db-schema-v1-1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 43020b08a0e55a0bced19874130139fc6c4a611cd81eb16f50e1aa013bf7adc2 CONTENT_BYTES: 20054 ================================================================================================ title: 01-db\_schema version: v1.1 updated: 2025-08-08 \--- \# Canonical Database Schema — EkoH & Smart Vote This file is the single source of truth for \*\*all\*\* tables, keys, partitions, indexes, ENUMs, and RLS policies used by the EkoH reputation engine and Smart Vote weighted-voting system. \*PostgreSQL 15 · schema name \*\*\`ekoh\_smartvote\`\*\* · extensions \`ltree\`, \`pgcrypto\`\* \--- \#\# 0 Overview & Conventions \* \*\*Shared cluster, own schema\*\* – all objects live in \`ekoh\_smartvote\`; Django sets \`search\_path \= ekoh\_smartvote,public\`. \* \*\*Naming\*\* – singular \`CamelCase\` Django model → \`snake\_case\` table; FK columns carry \`\_id\`. \* \*\*Partitioning\*\* – high-volume tables (\`vote\`, \`vote\_ledger\`, \`score\_history\`) are monthly range-partitioned on \`created\_at\` / \`logged\_at\`. \* \*\*Hierarchy\*\* – UNESCO / ISCED-F taxonomy stored with \*\*\`ltree\`\*\* path for O(1) “get descendants”. \* \*\*Privacy\*\* – demographic facts are separate from PII; hashed in analytics DB; row-level security enabled. \--- \#\# 1 Expertise Catalogue | Table | Key columns | Notes | |-------|-------------|-------| | \*\*\`expertise\_category\`\*\* | \`code\` VARCHAR(16) UNIQUE, \`parent\_id\`, \`depth\`, \`path\` LTREE | Holds the full hierarchy (26 broad \+ 143 detailed ISCED-F codes). GIST index on \`path\`; BTREE on \`(depth, code)\`. | | \*\*\`user\_expertise\_score\`\*\* | \`user\_id\`, \`category\_id\`, \`weighted\_score\` | Composite \`UNIQUE\`; partial index for leaderboard: \`(category\_id, weighted\_score DESC) WHERE weighted\_score \> 0\`. | | \*\*\`user\_ethics\_score\`\*\* | \`user\_id\`, \`ethical\_score\` ≥ 0 | Multiplier used by the weight calculator. | \--- \#\# 2 Consultations & Relevance Vectors | Table | Key columns | Description | |-------|-------------|-------------| | \*\*\`consultation\`\*\* | \`id\` UUID PK, \`title\`, \`opens\_at\`, \`closes\_at\` | A question / proposal open for voting. | | \*\*\`consultation\_relevance\`\*\* | \`consultation\_id\`, \`category\_id\`, \`weight\` 0–1 | Defines the relevance vector \*\*R\c,d\\*\*; JSONB column \`criteria\_json\` stores free-text rationale. BRIN index on \`(consultation\_id)\`. | \--- \#\# 3 Voting Core | Table | Key columns | Extras | |-------|-------------|--------| | \*\*\`vote\_modality\`\*\* | \`name\` (enum) | Seeded rows: approval, ranking, rating, preferential, budget\_split. | | \*\*\`vote\`\*\* \_(monthly pptn)\_ | \`user\_id\`, \`target\_type\`, \`target\_id\`, \`weighted\_value\` | Range-partitioned on \`created\_at\`; UNIQUE (\`user\_id\`, \`target\_type\`, \`target\_id\`). | | \*\*\`vote\_result\`\*\* | 1-row per target | Updated by aggregator service via UPSERT. | | \*\*\`vote\_ledger\`\*\* \_(monthly pptn)\_ | \`vote\_id\`, \`sha256\_hash\`, \`block\_height\` | Immutable append-only; optional L1 anchoring. | \--- \#\# 4 Score Configuration & Audit | Table | Purpose | |-------|---------| | \*\*\`score\_configuration\`\*\* | Tunable coefficients (RAW\_WEIGHT\_\*, caps). | | \*\*\`context\_analysis\_log\`\*\* | Explainable-AI adjustments (input \+ deltas). | | \*\*\`score\_history\`\*\* \_(monthly pptn)\_ | Immutable audit of every merit change. | \--- \#\# 5 Privacy & Demographics | Table | Purpose | |-------|---------| | \*\*\`confidentiality\_setting\`\*\* | User privacy level (\`public\`, \`pseudonym\`, \`anonymous\`). | | \*\*\`demographic\_attribute\`\*\* | Lookup (gender\_identity, faith\_tradition, etc.). | | \*\*\`demographic\_choice\`\*\* | Allowed values per attribute. | | \*\*\`user\_demographic\`\*\* | Junction table (multi-select safe). \*\*RLS enabled\*\*. | Analytics DB stores only salted SHA-256 user hashes; cohorts \< 10 rows suppressed. \--- \#\# 6 Integration & Integrity | Table | Purpose | |-------|---------| | \*\*\`integration\_mapping\`\*\* | Cross-module glue (e.g. Ethikos → vote target). | | \*\*\`integrity\_event\`\*\* | Logs Sybil, ring, spam anomalies (enum). | \--- \#\# 7 Partition template helper Monthly partitions auto-created via the PL/pgSQL block in \*Annex C\* of this doc. Detach \+ archive jobs run Sundays 04:00 UTC (\`purge\_old\_partitions\` DAG). \--- \#\# 8 Indexes & Performance Cheatsheet | Pattern | Index / tactic | |---------|----------------| | Top experts per domain | \`idx\_score\_top\` partial index | | All descendants of a domain | \`expertise\_category.path @\> subpath\` (GIST) | | Tally votes for a target | \`idx\_vote\_target\` (BTREE) | | Nightly score rebuild | Batch in \`user\_id\` order; autovacuum friendly | | Look-ups in relevance vector | \`consultation\_relevance\` cached JSON for hot path | | Ledger write speed | Append-only, clustered on \`ledger\_id\` | \--- \#\# 9 ERD (text) auth\_user──┬──── confidentiality\_setting ├──── user\_ethics\_score ├──── user\_expertise\_score ─┐ │ └─ score\_history (pptn) └──── user\_demographic expertise\_category (ltree) │ └──\< user\_expertise\_score │ consultation ───\< consultation\_relevance vote\_modality ───\< vote (pptn) ───\> vote\_result │ └──\< vote\_ledger (pptn) integration\_mapping integrity\_event context\_analysis\_log \--- \#\# 10 Change-control checklist 1\. \*\*Add column / table\*\* → update DDL, ERD, and \*02-parameter\_reference.md\* if tunables change. 2\. \*\*Partition window change\*\* → edit helper block \+ Airflow DAG cron. 3\. \*\*New ENUM value\*\* → append to ENUM type and update API docs. \--- \#\#\# Appendix B – Initial data load \* \`fixtures/isced\_f\_2013.json\` populated via Django \`loaddata\`. \* Default \`vote\_modality\` rows inserted by migration \*\*0001\_initial.py\*\*. \* Demo seed (\`DJANGO\_ENV=dev\`) adds 3 test users, 20 example votes. \--- \_This version supersedes v1.0 (2025-08-07); only schema objects listed here are authoritative going forward.\_ --- **Where to paste:** add this entire block at the end of the doc (start on a new page or under the “Database” annex heading). It now completely covers structure, partitioning, performance indexes, privacy, and change-control—so DBAs, devs, and data-analysts can all work from one definitive reference. Below is a **complete PostgreSQL 15 DDL bundle** that reproduces the entire EkoH \+ Smart Vote data model exactly as specified. Copy-paste into a psql session; it is idempotent (runs safely if objects already exist). /\* ─────────────────────────────────────────────── 0\. PREPARATION (schema \+ extensions) ───────────────────────────────────────────── \*/ CREATE SCHEMA IF NOT EXISTS ekoh\_smartvote; SET search\_path \= ekoh\_smartvote,public; CREATE EXTENSION IF NOT EXISTS ltree; \-- hierarchy paths CREATE EXTENSION IF NOT EXISTS pgcrypto;-- for salted hashes (analytics) /\* ─────────────────────────────────────────────── 1\. EXPERTISE CATALOGUE ───────────────────────────────────────────── \*/ CREATE TABLE expertise\_category ( id SERIAL PRIMARY KEY, code VARCHAR(16) UNIQUE NOT NULL, name VARCHAR(128) NOT NULL, parent\_id INT REFERENCES expertise\_category(id), depth SMALLINT NOT NULL, path LTREE NOT NULL ); CREATE INDEX idx\_cat\_path ON expertise\_category USING GIST (path); CREATE INDEX idx\_cat\_depth ON expertise\_category (depth, code); /\* ─────────────────────────────────────────────── 2\. USER SCORES & ETHICS ───────────────────────────────────────────── \*/ CREATE TABLE user\_expertise\_score ( id BIGSERIAL PRIMARY KEY, user\_id INT NOT NULL, \-- FK → auth\_user.id (in public) category\_id INT NOT NULL REFERENCES expertise\_category(id), raw\_score NUMERIC(12,4) NOT NULL, weighted\_score NUMERIC(12,4) NOT NULL, UNIQUE (user\_id, category\_id) ); CREATE INDEX idx\_score\_top ON user\_expertise\_score (category\_id, weighted\_score DESC) WHERE weighted\_score \> 0; CREATE TABLE user\_ethics\_score ( user\_id INT PRIMARY KEY, ethical\_score NUMERIC(5,3) NOT NULL CHECK (ethical\_score \>= 0), FOREIGN KEY (user\_id) REFERENCES auth\_user(id) ); /\* ─────────────────────────────────────────────── 3\. SCORE CONFIG & AUDIT ───────────────────────────────────────────── \*/ CREATE TABLE score\_configuration ( id SERIAL PRIMARY KEY, weight\_name VARCHAR(64) NOT NULL, weight\_value NUMERIC(6,3) NOT NULL, field VARCHAR(64) ); CREATE TABLE context\_analysis\_log ( id BIGSERIAL PRIMARY KEY, entity\_type VARCHAR(64) NOT NULL, entity\_id UUID NOT NULL, field VARCHAR(64), input\_metadata JSONB, adjustments\_applied JSONB, created\_at TIMESTAMP DEFAULT now() ); CREATE TABLE confidentiality\_setting ( user\_id INT PRIMARY KEY REFERENCES auth\_user(id), level ekoh\_privacy\_level\_enum NOT NULL ); CREATE TABLE score\_history ( id BIGSERIAL PRIMARY KEY, merit\_score\_id BIGINT REFERENCES user\_expertise\_score(id), old\_value NUMERIC(12,4), new\_value NUMERIC(12,4), change\_reason TEXT, changed\_at TIMESTAMP DEFAULT now() ) PARTITION BY RANGE (changed\_at); \-- monthly partitions example CREATE TABLE score\_history\_2025\_08 PARTITION OF score\_history FOR VALUES FROM ('2025-08-01') TO ('2025-09-01'); /\* ─────────────────────────────────────────────── 4\. DEMOGRAPHIC SELF-DECLARATION ───────────────────────────────────────────── \*/ CREATE TABLE demographic\_attribute ( id SERIAL PRIMARY KEY, code VARCHAR(64) UNIQUE NOT NULL, label VARCHAR(128) NOT NULL, multi\_select BOOLEAN DEFAULT FALSE ); CREATE TABLE demographic\_choice ( id SERIAL PRIMARY KEY, attribute\_id INT REFERENCES demographic\_attribute(id), value\_code VARCHAR(64) NOT NULL, display\_order SMALLINT, UNIQUE (attribute\_id, value\_code) ); CREATE TABLE user\_demographic ( user\_id INT NOT NULL REFERENCES auth\_user(id), attribute\_id INT NOT NULL REFERENCES demographic\_attribute(id), choice\_id INT NOT NULL REFERENCES demographic\_choice(id), confidence SMALLINT, PRIMARY KEY (user\_id, attribute\_id, choice\_id) ); /\* ─────────────────────────────────────────────── 5\. CONSULTATIONS & RELEVANCE VECTORS ───────────────────────────────────────────── \*/ CREATE TABLE consultation ( id UUID PRIMARY KEY, title VARCHAR(256) NOT NULL, opens\_at TIMESTAMP, closes\_at TIMESTAMP ); CREATE TABLE consultation\_relevance ( consultation\_id UUID REFERENCES consultation(id) ON DELETE CASCADE, category\_id INT REFERENCES expertise\_category(id), weight NUMERIC(5,4) CHECK (weight \>= 0 AND weight \<= 1), criteria\_json JSONB, PRIMARY KEY (consultation\_id, category\_id) ); CREATE INDEX idx\_consult\_relevance ON consultation\_relevance (consultation\_id); /\* ─────────────────────────────────────────────── 6\. VOTING CORE ───────────────────────────────────────────── \*/ CREATE TABLE vote\_modality ( id SERIAL PRIMARY KEY, name vote\_modality\_name\_enum UNIQUE NOT NULL, parameters JSONB ); \-- partitioned by month for write speed CREATE TABLE vote ( id BIGSERIAL, user\_id INT REFERENCES auth\_user(id), target\_type VARCHAR(64) NOT NULL, target\_id UUID NOT NULL, modality\_id INT REFERENCES vote\_modality(id), raw\_value NUMERIC(12,4) NOT NULL, weighted\_value NUMERIC(12,4) NOT NULL, created\_at TIMESTAMP DEFAULT now(), PRIMARY KEY (id, created\_at) ) PARTITION BY RANGE (created\_at); \-- example partition CREATE TABLE vote\_2025\_08 PARTITION OF vote FOR VALUES FROM ('2025-08-01') TO ('2025-09-01'); CREATE UNIQUE INDEX vote\_no\_duplicates ON vote (user\_id, target\_type, target\_id); CREATE TABLE vote\_result ( id BIGSERIAL PRIMARY KEY, target\_type VARCHAR(64) NOT NULL, target\_id UUID NOT NULL, sum\_weighted\_value NUMERIC(20,4) NOT NULL, vote\_count INT NOT NULL, UNIQUE (target\_type, target\_id) ); CREATE TABLE vote\_ledger ( ledger\_id BIGSERIAL PRIMARY KEY, vote\_id BIGINT REFERENCES vote(id), sha256\_hash BYTEA NOT NULL, block\_height BIGINT, logged\_at TIMESTAMP DEFAULT now() ) PARTITION BY RANGE (logged\_at); CREATE TABLE vote\_ledger\_2025\_08 PARTITION OF vote\_ledger FOR VALUES FROM ('2025-08-01') TO ('2025-09-01'); /\* ─────────────────────────────────────────────── 7\. INTEGRATION MAPPING ───────────────────────────────────────────── \*/ CREATE TABLE integration\_mapping ( id SERIAL PRIMARY KEY, module\_name VARCHAR(64) NOT NULL, context\_type VARCHAR(64) NOT NULL, mapping\_details JSONB ); /\* ─────────────────────────────────────────────── 8\. INTEGRITY & ANOMALY LOGS ───────────────────────────────────────────── \*/ CREATE TYPE ekoh\_integrity\_event\_enum AS ENUM ('sybil','ring','rapid\_growth','spam'); CREATE TABLE integrity\_event ( id BIGSERIAL PRIMARY KEY, user\_id INT REFERENCES auth\_user(id), event\_type ekoh\_integrity\_event\_enum NOT NULL, score JSONB, handled BOOLEAN DEFAULT FALSE, created\_at TIMESTAMP DEFAULT now() ); /\* ─────────────────────────────────────────────── 9\. ROW-LEVEL SECURITY FOR DEMOGRAPHICS ───────────────────────────────────────────── \*/ ALTER TABLE user\_demographic ENABLE ROW LEVEL SECURITY; CREATE POLICY demo\_public ON user\_demographic FOR SELECT USING (true); \-- refine with privacy level logic in app layer /\* ─────────────────────────────────────────────── 10\. BASE INDEX SUMMARY ───────────────────────────────────────────── \*/ CREATE INDEX idx\_vote\_target ON vote (target\_type, target\_id); CREATE INDEX idx\_result\_target ON vote\_result (target\_type, target\_id); CREATE INDEX idx\_integrity\_type ON integrity\_event (event\_type, handled); **Partition template helper** \-- Run monthly via cron: DO $$ DECLARE first\_day DATE := date\_trunc('month', now()); next\_month DATE := first\_day \+ INTERVAL '1 month'; tbl TEXT; BEGIN \-- vote tbl := format('vote\_%s', to\_char(first\_day,'YYYY\_MM')); EXECUTE format('CREATE TABLE IF NOT EXISTS %I PARTITION OF vote FOR VALUES FROM (%L) TO (%L)', tbl, first\_day, next\_month); \-- vote\_ledger tbl := format('vote\_ledger\_%s', to\_char(first\_day,'YYYY\_MM')); EXECUTE format('CREATE TABLE IF NOT EXISTS %I PARTITION OF vote\_ledger FOR VALUES FROM (%L) TO (%L)', tbl, first\_day, next\_month); \-- score\_history tbl := format('score\_history\_%s', to\_char(first\_day,'YYYY\_MM')); EXECUTE format('CREATE TABLE IF NOT EXISTS %I PARTITION OF score\_history FOR VALUES FROM (%L) TO (%L)', tbl, first\_day, next\_month); END $$; --- ### **How to load the UNESCO taxonomy** psql \-f path/to/ddl.sql psql \-c "\\copy ekoh\_smartvote.expertise\_category(code,name,parent\_id,depth,path) FROM 'isced\_f\_2013.csv' CSV HEADER" *Or via Django fixture (`manage.py loaddata fixtures/isced_f_2013.json`).* --- Once this DDL is executed, the EkoH \+ Smart Vote module is **schema-complete, index-tuned and partition-ready**, matching every table and constraint referenced in the spec and annex. **Yes, the DDL bundle is fully aligned with Konnaxion v14—by design it’s *additive* only, never conflicting.** | Alignment check | Result | Reason it’s safe | | ----- | ----- | ----- | | **Schema name** | Uses its own schema `ekoh_smartvote`; Konnaxion core stays in `public` (and `konnaxion_core` if present). | Guarantees no table-name collisions. | | **Core FK links** | Only foreign‐keys to `public.auth_user`. No FK touches any other v14 core table. | Matches v14’s pattern for module tables. | | **ENUM literals** | `ekoh_privacy_level_enum`, `vote_modality_name_enum`, etc. keep the exact value set already frozen in *Konnaxion Platform – Definitive Parameter Reference (v14-stable).* | So serializers, UI drop-downs and existing tests continue to pass. | | **Route & event invariants** | Tables that surface via APIs (`vote`, `consultation`, `user_demographic`) map to the endpoints listed in *Navigation Map.docx* and *07-integration\_mapping.md*. | No new top-level slug, no broken links. | | **Parameter names** | Weight caps (`RAW_WEIGHT_*`, `PROMETHEUS_BASE_URL`, etc.) match both the Parameter Reference v14 and the Annex you finalised. | Keeps config/Helm values one-to-one. | | **Partition strategy** | Monthly range partitions mirror the pattern used for `audit_log` and `analytics_fact_*` in v14’s Document 5\. | Ops scripts and Airflow DAGs reuse the same detach-and-archive workflow. | | **Extensions** | Only `ltree` (already enabled for Konnaxion taxonomy search) and `pgcrypto` (already used by core for salted hashes). | No new Postgres extension to provision. | | **RLS policy style** | `user_demographic` RLS mirrors v14’s pattern for `user_profile_private`. | Trust-ops can copy existing policy tests. | ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-smart-vote-definitive-module-documentation-set-v1-0.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 8d07cfc6e0d73e842eaf1cb7c33590add0a9d5bcb633edc734a93bc1e40a0038 CONTENT_BYTES: 68542 ================================================================================================ **`01-db_schema.md` — *Canonical Database Schema for EkoH & Smart Vote*** *(PostgreSQL \+ Django-ORM conventions; standard `created_at` / `updated_at` timestamp columns are implicit unless noted otherwise.)* --- ## **0 Overview & Conventions** * **Scope** – only the new tables owned by the standalone EkoH (expertise & ethics) and Smart Vote modules. Shared tables such as `auth_user` live in the Konnaxion core schema and are referenced by FK. * **Naming** – singular `CamelCase` model → `snake_case` table; FK columns carry `_id`; composite uniqueness enforced via `UniqueConstraint`. * **Immutability** – reference tables (`expertise_category`, `vote_modality`, ENUM types) are append-only. * **Retention & Partitioning** – see §6. * **ERD** – text diagram in §7 plus a placeholder for a PNG/SVG in `docs/assets/`. Note – Module-local tables: The following audit / integrity tables are local to the EkoH \+ Smart Vote module and therefore do not appear in the global Konnaxion canonical table list. They are safe to keep here as long as their names do not clash with core-schema objects. --- ## **1 EkoH (Expertise & Ethics)** | Table (Model) | Purpose | Key columns & constraints | | ----- | ----- | ----- | | **`expertise_category`*** **(`ExpertiseCategory`)* | UNESCO / ISCED-F domain catalogue. | `id PK`, `name VARCHAR UNIQUE` | | **`user_expertise_score`*** **(`UserExpertiseScore`)* | Per-user merit score per domain. | `id PK`, `user_id FK→auth_user`, `category_id FK→expertise_category`, `raw_score NUMERIC`, `weighted_score NUMERIC`, **UNIQUE**(`user_id`,`category_id`) | | **`user_ethics_score`*** **(`UserEthicsScore`)* | Behaviour-based multiplier ≥ 0\. | `user_id PK+FK→auth_user`, `ethical_score NUMERIC` | | **`score_configuration`*** **(`ScoreConfiguration`)* | Tunable coefficients for the merit engine. | `id PK`, `weight_name VARCHAR`, `weight_value NUMERIC`, `field VARCHAR NULLABLE` | | **`context_analysis_log`*** **(`ContextAnalysisLog`)* | Explainable-AI adjustment audit. | `id PK`, `entity_type VARCHAR`, `entity_id UUID`, `field VARCHAR`, `input_metadata JSONB`, `adjustments_applied JSONB` | | **`confidentiality_setting`*** **(`ConfidentialitySetting`)* | User privacy level. | `user_id PK+FK→auth_user`, `level ekoh_privacy_level_enum` | | **`score_history`*** **(`ScoreHistory`)* | Immutable audit of every score change. | `id PK`, `merit_score_id FK→user_expertise_score`, `old_value NUMERIC`, `new_value NUMERIC`, `change_reason TEXT` | *Index notes* – composite index `(category_id, weighted_score DESC)` accelerates “top experts per domain”. --- ## **2 Smart Vote (Weighted Voting Engine)** | Table (Model) | Purpose | Key columns & constraints | | ----- | ----- | ----- | | **`vote`*** **(`Vote`)* | One raw ballot cast by a user. | `id PK`, `user_id FK→auth_user`, `target_type VARCHAR`, `target_id UUID`, `modality_id FK→vote_modality`, `raw_value NUMERIC`, `weighted_value NUMERIC`, **UNIQUE**(`user_id`,`target_type`,`target_id`) | | **`vote_modality`*** **(`VoteModality`)* | Defines ballot formats & JSON parameters. | `id PK`, `name VARCHAR UNIQUE`, `parameters JSONB` | | **`vote_result`*** **(`VoteResult`)* | Aggregated outcome per target. | `id PK`, `target_type VARCHAR`, `target_id UUID`, `sum_weighted_value NUMERIC`, `vote_count INT`, **UNIQUE**(`target_type`,`target_id`) | | **`emerging_expert`*** **(`EmergingExpert`)* | Flags users with rapid merit growth. | `id PK`, `user_id FK→auth_user`, `detection_date DATE`, `score_delta NUMERIC` | | **`integration_mapping`*** **(`IntegrationMapping`)* | Cross-module glue (e.g., Ethikos topic → vote target). | `id PK`, `module_name VARCHAR`, `context_type VARCHAR`, `mapping_details JSONB` | *Index notes* – BTREE `(target_type,target_id)` on `vote` for fast tallies; partial index on `(user_id)` for “my votes”. --- ## **3 Audit / Ledger Extension *(transparency requirement)*** | Table | Purpose | Columns | | ----- | ----- | ----- | | **`vote_ledger`** | Immutable log of every ballot & weight hash. | `ledger_id BIGSERIAL PK`, `vote_id FK→vote`, `sha256_hash BYTEA`, `block_height BIGINT`, `logged_at TIMESTAMP DEFAULT now()` | --- ## **4 Integrity & Anomaly Logs** | Table | Purpose | Columns | | ----- | ----- | ----- | | **`integrity_event`** | Detects collusion, Sybil rings, spam etc. | `id PK`, `user_id FK→auth_user NULLABLE`, `event_type ekoh_integrity_event_enum`, `score JSONB`, `handled BOOLEAN DEFAULT FALSE`, `created_at TIMESTAMP DEFAULT now()` | --- ## **5 ENUM Appendix** *Defined in `ekoh_enums.sql`; referenced by table DDL.* | Enum type | Allowed values | | ----- | ----- | | `ekoh_privacy_level_enum` | `public`, `pseudonym`, `anonymous` | | `ekoh_integrity_event_enum` | `sybil`, `ring`, `rapid_growth`, `spam` | | `vote_modality_name_enum` | `approval`, `ranking`, `rating`, `preferential`, `budget_split` | | `stance_scale_enum` | `-3`, `-2`, `-1`, `0`, `1`, `2`, `3` | --- ## **6 Retention & Partitioning Policies** * GDPR-aligned and performance-oriented: * `vote` & `vote_ledger` – hot 5 years, then archived cold; monthly partitions on `created_at`. * `score_history` – 7 year retention; monthly partitions. * `integrity_event` – retain 3 years rolling; auto-purge handled=true events after 12 months. --- ## **7 Entity-Relationship Diagram (text)** text CopyEdit `auth_user (PK id)` │1 ├─\< confidentiality\_setting ├─\< user\_ethics\_score ├─\< user\_expertise\_score ─┐ │ └─\< score\_history └─\< emerging\_expert `expertise_category` └─\< user\_expertise\_score `vote_modality` └─\< vote ──\> vote\_result (1:1 per target) │ └─\< vote\_ledger `integration_mapping` `integrity_event (optional FK to user)` `context_analysis_log (polymorphic entity_type/entity_id)` *A vector version (`erd_ekoh_smartvote_v1.svg`) lives in `docs/assets/`.* --- ## **8 Glossary of Column Abbreviations** | Abbrev. | Meaning | | ----- | ----- | | `target_type` | Model label of the entity being voted on | | `score_delta` | % or absolute change triggering emerging-expert flag | | `block_height` | Position of ledger entry on external blockchain | | `event_type` | Categorical anomaly detected by Integrity Guard | --- ### **Change-control Checklist** 1. **Add column/table** → update this file *and* `02-parameter_reference.md` if tunables change. 2. **Rename/drop** → create reversible migration; mark old name here under “Deprecated” until purge. 3. **New ENUM value** → append to §5 and regenerate ERD. This document is now the *single source of truth* for every table, key, and enum powering the EkoH reputation engine and Smart Vote weighted-voting system. All subsequent specs, code, analytics, and tests must reference these canonical names and structures. Sources ##### **You said:** write 2/11 ###### **ChatGPT said:** Thought for 28 seconds **`02-parameter_reference.md` — Definitive Parameter Registry for EkoH & Smart Vote (v1.0)** *This file freezes every knob that integrators, ops teams, and data-scientists may tune.* *All other documents must hyperlink here rather than restating values.* --- ## **0 Document structure** 1. Global conventions & units 2. **EkoH engine** parameters 3. **Smart Vote engine** parameters 4. Choice/enum sets (shared) 5. Environment-variable matrix --- ## **1 Global conventions** * **Type** — SQL or Python primitive (`Decimal(4,3)`, `float`, `enum`, etc.) * **Range** — inclusive unless otherwise stated. * **Location** — where code reads the value (`ScoreConfiguration` table, `settings.py`, `.env`). * **Defaults** — MUST NOT change except by PR that updates **this file first**. --- ## **2 EkoH engine parameters** | Name | Location | Type & Range | Default | Description | | ----- | ----- | ----- | ----- | ----- | | `raw_weight_quality` | `ScoreConfiguration` | `Decimal(4,3)` 0 – 5 | **1.000** | Multiplier on *quality* axis in multidimensional scoring | | `raw_weight_expertise` | `ScoreConfiguration` | `Decimal(4,3)` 0 – 5 | **1.500** | Multiplier on *expertise depth* axis | | `raw_weight_frequency` | `ScoreConfiguration` | `Decimal(4,3)` 0 – 5 | **0.750** | Dampening factor for contribution frequency (prevents spam inflation) | | `ethical_multiplier_floor` | `settings.EKOH` | `float` 0 – 1 | **0.20** | Lower bound applied to unethical users; anything below is auto-suspension | | `ethical_multiplier_cap` | `settings.EKOH` | `float` 1 – 2 | **1.50** | Upper bound for exemplary conduct; prevents runaway influence | | `EXPERTISE_DOMAIN_CHOICES` | `ExpertiseCategory` fixtures | `enum[26]` | UNESCO ISCED-F codes | Frozen list used by all domain tagging | --- ## **3 Smart Vote engine parameters** | Name | Location | Type & Range | Default | Description | | ----- | ----- | ----- | ----- | ----- | | `VOTE_MODALITY_CHOICES` | `VoteModality` | `enum` | `"approval"`, `"ranking"`, `"rating"`, `"preferential"` | Allowed ballot types; engine must reject any other string | | `EMERGING_EXPERT_THRESHOLD` | `settings.SMART_VOTE` | `% Ekoh Δ over rolling 30 d` | **\+15 %** | Triggers `EmergingExpert` flag and mentorship prompts | | `CONSENSUS_STRONG_THRESHOLD` | `settings.SMART_VOTE` | `% weighted agreement` | **75 %** | Above this, a consultation is labeled “Strong Consensus” in UI | **Note – soft weight cap**: while the tech spec allows implementation-level caps (e.g. max 10× average weight), no constant is yet frozen; if introduced it must be appended here and cited to the governance minutes. --- ## **4 Shared choice & enum sets** | Enum | Values | Consumed by | | ----- | ----- | ----- | | `ekoh_privacy_level_enum` | `public`, `pseudonym`, `anonymous` | `ConfidentialitySetting.level` | | `ekoh_integrity_event_enum` | `sybil`, `ring`, `rapid_growth`, `spam` | `IntegrityEvent.event_type` | | `vote_modality_name_enum` | *(see VOTE\_MODALITY\_CHOICES above)* | `VoteModality.name` | | `stance_scale_enum` | `-3 … 0 … +3` | Ethikos integration (read-only for Smart Vote) | All enum literals are **case-sensitive** and must never be localized. --- ## **5 Environment-variable matrix (excerpt)** | Env var | Consumes | Maps to parameter | Default | | ----- | ----- | ----- | ----- | | `EKOH_MULTIPLIER_CAP` | `settings.EKOH` | `ethical_multiplier_cap` | `1.50` | | `SMARTVOTE_CONSENSUS_STRONG` | `settings.SMART_VOTE` | `CONSENSUS_STRONG_THRESHOLD` | `0.75` | | `SMARTVOTE_EMERGING_DELTA` | `settings.SMART_VOTE` | `EMERGING_EXPERT_THRESHOLD` | `0.15` | | RAW\_WEIGHT\_QUALITY | settings.EKOH | raw\_weight\_quality | 1.000 | | RAW\_WEIGHT\_EXPERTISE | settings.EKOH | raw\_weight\_expertise | 1.500 | | RAW\_WEIGHT\_FREQUENCY | settings.EKOH | raw\_weight\_frequency | 0.750 | | PROMETHEUS\_BASE\_URL | analytics-settings | \- | http://prometheus:9090 | **Convention** – env var names mirror the parameter in UPPER\_SNAKE; values are parsed as float or JSON as appropriate. PROMETHEUS\_BASE\_URL – analytics-settings CM – http://prometheus:9090 EXPORT\_MAX\_ROWS – analytics-settings CM – 100 000 --- ### **Change-control checklist** 1. **Propose new parameter** → draft PR adding row to correct section \+ env-var (if needed). 2. **Modify default** → governance vote required; update this file *and* config templates. 3. **Rename / drop** → breaking change; version bump this document and all dependent code. This registry is the **single source of truth** for runtime tunables in the EkoH reputation engine and Smart Vote weighted-voting system. All services, Helm charts, and CI pipelines must read values through the paths documented above. Sources ##### **You said:** 3/11 ###### **ChatGPT said:** Thought for 7 seconds **`03-technical_spec.md` — *Layer-by-Layer System Specification for EkoH & Smart Vote (v1.0)*** *(All identifiers must match the names frozen in `01-db_schema.md` and `02-parameter_reference.md`.)* --- ## **0 Purpose & Scope** This document translates the high-level architecture into implementable, testable contracts across: 1. **Backend micro-services** (Django \+ DRF) 2. **Frontend UI & state flow** (React 18 \+ TanStack Query) 3. **Data / persistence** (PostgreSQL 15, Redis 7, Kafka 3\) 4. **DevOps / runtime** (Docker \+ Kubernetes, Prometheus, Grafana) The spec is normative; deviations require a version bump and PR that patches every impacted reference doc. --- ## **1 High-Level Component Diagram** text CopyEdit ┌─────────── UI Layer (SPA) ───────────┐ │ /ekoh/\* widgets /smart-vote/\* pages │ └──────────────┬────────────────────────┘ │ HTTPS / JWT ┌───────────────────────▼───────────────────────────┐ │ API Gateway (Konnaxion Core) │ └──┬────────────────────────┬───────────────────────┘ │ │ ┌────▼─────┐ ┌─────▼────┐ │ EkohSvc │ gRPC/REST │ VoteSvc │ └────┬─────┘ └────┬─────┘ │ │ Kafka events │ ▼ ┌────▼───────────┐ ┌──────────────┐ │ Auth & Profile │ │ Integrity │ │ Service │ │ Guard │ └────┬───────────┘ └────┬─────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ PostgreSQL 15 │ │ Redis 7 │ │ ekoh & vote DB │ │ cache / locks │ └─────────────────┘ └─────────────────┘ --- ## **2 Backend Micro-Services** ### **2.1 EkohSvc (reputation engine)** | Endpoint | Method | Auth | Purpose | Status codes | | ----- | ----- | ----- | ----- | ----- | | `/ekoh/profile/:userId` | `GET` | JWT (public if level \= `public`) | Return expertise & ethics scores. | 200, 404 | | `/ekoh/score/recalc` | `POST` | `ROLE_ADMIN` | Trigger async full recalculation. | 202 | | `/ekoh/score/bulk` | `POST` | `ROLE_SERVICE` | Stream credentials / impacts for batch ingest. | 207, 400 | *Implementation notes* * Recalc job enqueues Kafka topic `ekoh.score.recalc`; Celery worker processes in shards of 500 users. * Scores stored in `user_expertise_score` & `user_ethics_score` tables . #### **2.1.1 Algorithm — multidimensional \_scoring** python CopyEdit `def weighted_domain_score(raw_quality, raw_expertise, raw_freq):` `return (` `raw_quality * RAW_WEIGHT_QUALITY` `+ raw_expertise * RAW_WEIGHT_EXPERTISE` `+ raw_freq * RAW_WEIGHT_FREQUENCY` `)` Constants map to parameters frozen in §2 of the registry . --- ### **2.2 VoteSvc (weighted voting)** | Endpoint | Method | Auth | Purpose | Status | | ----- | ----- | ----- | ----- | ----- | | `/smart-vote/cast` | `POST` | JWT | Submit ballot `{target, modality, value}`. | 201, 400, 409 | | `/smart-vote/result/:targetType/:id` | `GET` | JWT/Anon | Retrieve current weighted result snapshot. | 200, 404 | | `/smart-vote/modality` | `GET` | JWT | List supported modalities. | 200 | #### **2.2.1 Weight-calculator pseudocode** python CopyEdit `def compute_weight(user_id, consultation):` `base = 1` `dot_product = sum(` `user_scores[d] * consultation.relevance[d]` `for d in consultation.relevance` `)` `weight = (base + dot_product) * user_ethics[user_id]` `return min(weight, HARD_CAP) # optional cap` `user_scores` from `user_expertise_score`, ethics multiplier from `user_ethics_score`. `HARD_CAP` to be introduced only after governance vote (not yet in registry). #### **2.2.2 VoteEngine flow (sequence)** 1. Frontend POST `/cast` → API gateway → VoteSvc. 2. VoteSvc checks idempotency (`vote` table `UNIQUE(user,target)`), else 409\. 3. Calls **WeightCalculator** → returns `W`. 4. Stores `raw_value`, `weighted_value = raw_value * W` in `vote`. 5. Emits Kafka `vote.cast` event; **Aggregator** service consumes, UPSERTs into `vote_result`. 6. Writes hash to `vote_ledger` \+ (optionally) layer-1 blockchain. Error codes map to standard JSON problem+ details (`code`, `detail`, `instance`). --- ## **3 Frontend (SPA)** ### **3.1 Route map (superset of Navigation Map entries)** | Path | Component | Auth | Data source | | ----- | ----- | ----- | ----- | | `/ekoh/profile/:uid` | `` | Public/Private | `/ekoh/profile/:uid` | | `/smart-vote/:entity/:id` | `` | JWT/Anon | `/smart-vote/result` \+ `/cast` | | `/reports/smart-vote` | `` | `ROLE_ADMIN` | `/reports/smart-vote` (Insights API) | *State management* — TanStack Query caches per-route; WebSocket channel `ws://.../smart-vote/live/:id` pushes partial tally updates every 5 s. --- ## **4 Data Layer Contracts** | Table | Access pattern | Service owner | | ----- | ----- | ----- | | `user_expertise_score` | R/W by EkohSvc; read-only by VoteSvc. | | | `vote` | Insert by VoteSvc; read by Aggregator. | | | `vote_result` | Upsert by Aggregator; read by VoteSvc & UI. | | | `vote_ledger` | Append-only by VoteSvc; read by Audit Lambda. | | All table names & columns must match `01-db_schema.md`. --- ## **5 Integration & Messaging** | Kafka topic | Producer | Consumer | Payload schema | | ----- | ----- | ----- | ----- | | `ekoh.score.recalc` | API Gateway | Celery worker | `{batch_id, user_ids[]}` | | `vote.cast` | VoteSvc | Aggregator, IntegrityGuard | `{vote_id, user_id, target, w_value}` | | `integrity.alert` | IntegrityGuard | Ops Slack hook | `{event_id, type, user_id?}` | Topic names are frozen; message payloads versioned (`v1`). --- ## **6 Security & Auth** * JWT issued by Konnaxion Auth (HS256 \+ rotating keys). * Role matrix: `ROLE_USER`, `ROLE_EXPERT`, `ROLE_ADMIN`. * Vote endpoints accept anonymous read but require JWT for cast. * EKOH profile obeys `confidentiality_setting.level` (`401` vs `403` vs redacted fields). * Rate-limit: 60 req/min/user via API Gateway Leaky-Bucket filter. --- ## **7 Error & Event Codes (excerpt)** | Code | HTTP | Message | Source | | ----- | ----- | ----- | ----- | | `EKOH_40401` | 404 | “User not found” | EkohSvc | | `VOTE_40901` | 409 | “Duplicate ballot” | VoteSvc | | `INTG_20001` | 202 | “Recalc queued” | EkohSvc | | `AUTH_40101` | 401 | “JWT expired” | Gateway | Full list lives in `/common/error_codes.yaml`. --- ## **8 DevOps / Runtime** * **Containers** – each service in Alpine-based image; tag `v1.0.{git-sha}`. * **Kubernetes** – namespace `konnaxion-intel`; HPA 2-10 replicas per service on CPU 70 %. * **Observability** – Prometheus / Grafana dashboards: * `vote_tps` (target ≥ 200/s) * `ekoh_recalc_duration_ms` (p95 \< 120 000\) * **CI pipeline** – GitHub Actions → pytest \+ doc-lint \+ vulnerability scan; block merge if coverage \< 90 %. --- ## **9 Non-Functional Requirements** | Category | Target | | ----- | ----- | | **Latency** | P95 vote cast \< 150 ms (same region) | | **Throughput** | 100 k ballots / min burst | | **Uptime** | 99.9 % per rolling 30 d | | **Data integrity** | Zero lost ledger entries; SHA-256 mismatch alert in \< 1 min | | **Scalability** | Horizontal; DB partitioning strategy defined in `01-db_schema.md` §6 | | **Compliance** | GDPR, CCPA; ISO 27001 controls inherited from Konnaxion core | --- ### **Change-Control Checklist** 1. Add/modify endpoint → update §2 tables \+ Integration Mapping doc. 2. Change message schema → bump topic payload version & reflect here. 3. New role/permission → update Role matrix in §6 and Parameter Registry. This technical specification is now the contract binding code, tests, and operations for the EkoH reputation engine and Smart Vote weighted-voting subsystem. All engineering work must conform to the interfaces, flows, and thresholds defined herein. ##### **You said:** 4/11 ###### **ChatGPT said:** Thought for 15 seconds **`04-inventory_of_features.md` — Feature Catalogue for EkoH & Smart Vote (v1.0)** *Each row is a “contract”; code, DB, tasks and UI must implement the exact code-name.* --- ## **0 How to read this file** * **Display Name → Code Name** — UI wording on the left, immutable identifier on the right. * **Layer tags** — * **Svc** \= backend service / function * **API** \= REST/gRPC endpoint * **Task** \= Celery / Cron job * **DB** \= table(s) updated * **UI** \= React component / page hook * **Depends on** — tables, parameters, or other features that must exist first. * All tables & params referenced are frozen in `01-db_schema.md` and `02-parameter_reference.md`. --- ## **1 EkoH engine (Kollective Intelligence)** | \# | Display Name → Code Name | Purpose / behaviour | Layer tags | Depends on | | ----- | ----- | ----- | ----- | ----- | | 1 | Multidimensional Scoring → **`multidimensional_scoring`** | Computes per-user merit along axes (quality, frequency, expertise) | Svc `services/multidimensional_scoring.py` Task `ekoh_score_recalc` | DB: `user_expertise_score` Params: `raw_weight_*` | | 2 | Criteria Customization → **`configuration_weights`** | Admins adjust axis weights at runtime | API `PATCH /admin/ekoh/weights` DB `score_configuration` | Param registry | | 3 | Automatic Contextual Analysis → **`contextual_analysis`** | AI fine-tunes scores by topic & complexity | Svc `services/contextual_analysis.py` Task `contextual_analysis_batch` | DB `context_analysis_log` | | 4 | Dynamic Privacy → **`privacy_settings`** | Apply anonymity / pseudonym while still showing scores | API `PUT /ekoh/privacy` UI toggle DB `confidentiality_setting` | Enum `ekoh_privacy_level_enum` | | 5 | History & Traceability → **`score_history`** | Persist every score recalculation for audit | Svc logic wrapper DB `score_history` | Audit policy | | 6 | Interactive Visualizations → **`score_visualization`** | Serve live dashboards & skill-maps | API `/reports/ekoh` UI `` | Materialised view `mat_expert_domain_top10` | | 7 | Expertise Classification by Field → **`expertise_field_classification`** | Bind each sub-score to formal UNESCO domain | Svc helper DB `expertise_category` | Fixtures `EXPERTISE_DOMAIN_CHOICES` | --- ## **2 Smart Vote engine** | \# | Display Name → Code Name | Purpose / behaviour | Layer tags | Depends on | | ----- | ----- | ----- | ----- | ----- | | 1 | Dynamic Weighted Voting → **`dynamic_weighted_vote`** | Re-weights every ballot using voter’s EkoH score | Svc `services/weight_calculator.py` API `POST /smart-vote/cast` | DB `vote`, `user_expertise_score`, `user_ethics_score` | | 2 | Flexible Voting Modalities → **`voting_modalities`** | Support approval, ranking, rating, preferential ballots | DB seed `vote_modality` UI `` | Enum `vote_modality_name_enum` | | 3 | Emerging Expert Detection → **`emerging_expert_detection`** | Flag users with sharp EkoH growth | Task `detect_emerging_expert` DB `emerging_expert` | Param `EMERGING_EXPERT_THRESHOLD` | | 4 | Transparency of Results → **`vote_transparency`** | Publish raw \+ weighted values & context (no PII) | API `GET /smart-vote/result` DB `vote_ledger` | Privacy policy | | 5 | Advanced Result Visualizations → **`vote_result_visualization`** | Histograms, network graphs, interactive maps | UI `` Query `vote_result` | Reporting conduit | | 6 | Cross-Module Integration → **`cross_module_vote_integration`** | Make Smart Vote callable from all modules | API gateway mapping DB `integration_mapping` | Auth scopes, event bus | --- ## **3 Feature → Dependency Matrix (quick lookup)** | Code Name | Tables | Params | Scheduled Task | UI Hook | | ----- | ----- | ----- | ----- | ----- | | `multidimensional_scoring` | `user_expertise_score` | `raw_weight_*` | `ekoh_score_recalc` | n/a | | `contextual_analysis` | `context_analysis_log` | — | `contextual_analysis_batch` | n/a | | `privacy_settings` | `confidentiality_setting` | — | — | `` | | `dynamic_weighted_vote` | `vote`, `user_expertise_score`, `user_ethics_score` | — | — | `` | | `vote_transparency` | `vote_ledger`, `vote_result` | — | — | `` | | `emerging_expert_detection` | `emerging_expert` | `EMERGING_EXPERT_THRESHOLD` | nightly Celery | `` | *(If a square is blank, that layer does not touch the feature.)* --- ### **Change-control reminders** 1. **Add a new feature** → register Display Name → Code Name here **first**. 2. **Rename a feature** → migrate code, DB seed, tasks, and update this catalogue in the same PR. 3. **Delete a feature** → deprecate here, ensure no DB FK or API route still references the code-name, then remove. This catalogue is the authoritative cross-reference between UX wording, backend services, scheduled tasks, database artefacts, and configuration parameters for EkoH and Smart Vote. All future specs, code and documentation must use these exact identifiers to stay coherent. Sources ##### **You said:** 5/11 ###### **ChatGPT said:** Thought for 25 seconds **`05-reporting_analytics.md` — Reporting & Analytics Slice for EkoH \+ Smart Vote (layer 5\)** *(Frontend dashboards → read-only API → star-schema warehouse → ETL & DevOps)* --- ## **0 Scope & Position in the Stack** The Insights (Reporting & Analytics) module sits **read-only** atop the operational Konnaxion databases. It provides: * React dashboards under `/reports/*` (5.1) * `reports-api` micro-service (5.2) * A dedicated PostgreSQL 16 **star-schema** cluster \+ Redis cache (5.3) * Airflow-driven ETL \+ monitoring/backup infrastructure (5.4) These four sub-layers map 1-to-1 to the headings of *Document 5* referenced below. --- ## **1 Frontend Dashboards (5.1)** | Route | React page | Key components | | ----- | ----- | ----- | | `/reports/smart-vote` | `SmartVoteDashboard.tsx` | `SmartVoteChart`, `TimeRangePicker` | | `/reports/usage` | `UsageDashboard.tsx` | `UsageBigNumbers`, `DomainHeatMap` | | `/reports/perf` | `PerfDashboard.tsx` | `LatencySLOGauge`, `ErrorRateSparkline` | Component and file naming must follow the package layout shown in the design spec. All charts use Chart.js 4, Ant-Design 5 widgets, and React-Query for data fetch / cache (no extra state library). --- ## **2 Backend Service – `reports-api` (5.2)** | Endpoint | Method | Filters | Cache-TTL | Notes | | ----- | ----- | ----- | ----- | ----- | | `/reports/smart-vote` | GET | `range` (24h/7d/30d/custom), `grouping` (day/week) | 600 s | Returns `{labels[], votes[], avg_score[]}` | | `/reports/usage` | GET | identical | 600 s | MAU, docs, projects | | `/reports/perf` | GET | `range`, `endpoint` | 300 s | P95 latency & error-rate | | `/reports/export` | GET | `report`, `format` | 60 s | CSV/JSON stream, ADMIN-only | *Service tech-stack*: Django 4.2 \+ DRF 3.15, Redis-cached, JWT-protected, 60 req/min throttle. --- ## **3 Star-Schema Warehouse (5.3)** ### **3.1 Overview** Fact tables **`smart_vote_fact`**, **`usage_mau_fact`**, **`api_perf_fact`** sit at the centre, linked to **`dim_date`**, **`dim_domain`**, **`dim_endpoint`**. ### **3.2 Core dimensions** | Dim | PK | Note | | ----- | ----- | ----- | | `dim_date` | `date_id` | pre-populated 2000-2035 | | `dim_domain` | `domain_id` | maps UNESCO codes | | `dim_endpoint` | `endpoint_id` | REST path catalogue | All surrogate keys \= SMALLINT, zstd-compressed. ### **3.3 Fact `smart_vote_fact` (partitioned monthly)** *Columns*: `id UUID`, `date_id`, `domain_id`, `question_id`, `user_id (SHA-256)`, `vote_value`, `score_normalised` *Indexes*: `(domain_id, date_id)` BRIN. *ETL*: **`etl_smart_vote`** writes delta every 10 min; nightly full load. ### **3.4 Materialised views** | View | Scope | Refresh | | ----- | ----- | ----- | | `vw_smart_vote_30d` | last 30 days aggregates | incremental via ETL trigger | All views are created `WITH NO DATA` during migration; first populate via Airflow. ### **3.5 Retention & purge** * `smart_vote_fact` — keep 5 yrs, drop oldest partition yearly. Hashes replace user IDs; cohorts \< 10 rows are discarded for k-anonymity. --- ## **4 ETL & Airflow (5.4)** | DAG id | Schedule | Task summary | | ----- | ----- | ----- | | `etl_smart_vote` | `*/10 * * * *` | ingest weighted votes → `smart_vote_fact` | | `etl_usage` | `0 * * * *` | hourly MAU update → `usage_mau_fact` | | `etl_perf` | `*/15 * * * *` | pull Prometheus metrics → `api_perf_fact` | | `refresh_mat_views` | `5 * * * *` | `REFRESH MATERIALIZED VIEW vw_*` | | `cleanup_cache` | `@hourly` | purge Redis keys \> 12 h | | `purge_old_partitions` | `0 4 * * 0` | drop partitions past retention | Airflow images & resources are detailed in the infra table. --- ## **5 DevOps & Runtime** | Resource | Image | Replicas (HPA) | CPU m (req/lim) | RAM Mi (req/lim) | | ----- | ----- | ----- | ----- | ----- | | **`reports-api`** | `ghcr.io/konnaxion/reports-api:` | 3 (2 → 6\) | 300 / 600 | 384 / 768 | | **`reports-etl-worker`** | `ghcr.io/konnaxion/reports-etl:` | 2 (manual) | 400 / 800 | 512 / 1024 | Environment variables & secrets (Vault / ConfigMap) are listed in the infra section. ### **Monitoring & alerts** Prometheus rules e.g. `reports_latency_p95` (\> 400 ms) and `etl_task_fail` (Airflow) drive PagerDuty. Performance baseline: 100 M-row partition attach/detach ≤ 2 s; `/reports/*` P95 ≤ 400 ms. Backups: pgBackRest nightly \+ 30-min incrementals; 14-day retention; quarterly restore drill. --- ## **6 Security & Access** * All `user_id` fields are irreversible SHA-256 hashes. * Role **`reports_reader`** \= SELECT on dims/views only; facts restricted to ETL account. * CSV export capped at **100 000 rows** and ADMIN-only. --- ## **7 CI/CD Extensions** Jobs `schema-diff`, `dag-lint`, `perf-budget`, `export-guard` enforce schema drift, DAG quality, latency budget, and export limits before deploying images via Argo CD. --- ## **8 Change-Control Checklist** 1. **Add column to fact/dim** → new migration \+ update §3 tables \+ `schema-diff` test. 2. **New dashboard** → register React page & add OpenAPI path in §2. 3. **Modify DAG schedule** → edit table in §4 \+ redeploy Airflow chart. 4. **New Prometheus alert** → append to §5 metrics list and HPA triggers. This document now completes layer 5, binding dashboards, APIs, warehouse schema, ETL jobs and DevOps contracts into a single authoritative reference for all Reporting & Analytics functions in the EkoH / Smart Vote ecosystem. Sources ##### **You said:** 6/11 ###### **ChatGPT said:** Thought for 5 seconds **`06-insights_module.md` — Analytics & ML Reference for EkoH \+ Smart Vote (v 1.0)** *This file freezes every dataset, feature, and configuration knob consumed by downstream statistical dashboards, machine-learning models, and insight services. Anything that feeds or reads the star-schema warehouse (§3 of the Reporting doc) must respect these contracts.* --- ## **0 Scope** * **In-scope** – feature dictionaries, predictive-bonus rules, drift-detection thresholds, Airflow DAG IDs, environment variables, and privacy guarantees that govern the “Insights” slice. * **Out-of-scope** – operational reporting queries (see `05-reporting_analytics.md`), API routes (`03-technical_spec.md`), or raw OLTP schema (`01-db_schema.md`). --- ## **1 Canonical Data Inputs** | Source table / view | Grain | Primary keys | | ----- | ----- | ----- | | `smart_vote_fact` | *vote × day × domain* | `id` (UUID) | | `vw_smart_vote_30d` | *aggregated view* – last 30 d | `(date_id, domain_id)` | | `usage_mau_fact` | *org × month* | `(org_id, month)` | | `api_perf_fact` | *endpoint × 5 min* | `(endpoint_id, ts_5m)` | All user identifiers are one-way SHA-256 hashes with secret salt, and cohorts smaller than **10** rows are discarded to preserve k-anonymity . --- ## **2 Feature Dictionary** | Feature group | Feature name (snake\_case) | Definition / transformation | | ----- | ----- | ----- | | **Vote metrics** | `weighted_yes_ratio` | `sum(weighted_yes) / sum(weighted_total)` over 30 d | | | `expert_participation_rate` | voters with EkoH score ≥ 80 ÷ total voters | | | `weight_gini_index` | inequality of weights in a consultation | | **User trajectory** | `ekoh_score_delta_30d` | latest EkoH – EkoH 30 d ago | | | `predictive_bonus_points` | accumulated per §4 rule | | **System health** | `api_p95_latency_ms` | P95 latency per endpoint (5 min bins) | | | `etl_dag_success_rate` | successful Airflow task instances / total | Surrogate keys map to `dim_date`, `dim_domain`, `dim_endpoint` (see star schema). All features are materialised in nightly Airflow task **`etl_feature_store`** (DAG spec below). --- ## **3 Predictive-Insight Bonus Logic (EkoH)** 1. Identify minority votes (\< 25 % weighted share at close). 2. After a **validation event** (expert panel decision or real-world KPI) proves the minority correct, award **`+b`** bonus points: b=2×Wu,c b \= 2 \\times \\sqrt{W\_{u,c}}b=2×Wu,c​​ 3. Persist to `predictive_bonus_points` and `score_history`. 4. Cap cumulative bonus at **\+10 %** of user’s current domain score to prevent gaming. Design rationale documented in the EkoH overview . --- ## **4 Model Training & Drift Detection** | Model ID | Target | Algorithm | Retrain cadence | Drift signal | | ----- | ----- | ----- | ----- | ----- | | `sv_outcome_regressor_v1` | Consultation outcome within ±5 % | Gradient-boosted trees | weekly | KS-stat on `weighted_yes_ratio` vs training | | `ekoh_growth_forecast_v1` | `ekoh_score_delta_30d` | Prophet | daily | MAPE \> 15 % on latest week | | `expert_emergence_classifier_v1` | Binary flag (`emerging_expert`) | Logistic \+ SMOTE | monthly | F1 drop \> 5 % | Drift thresholds and retrain timers are defined in Airflow DAG defaults (section 5). --- ## **5 Airflow DAG Registry (extracted from *Insights Parameter Reference*)** yaml CopyEdit `etl_dags: # frozen list (do not rename ids)` `- id: etl_smart_vote # every 10 min` `- id: etl_usage # hourly` `- id: etl_perf # every 15 min` `- id: refresh_mat_views # hourly :05` `- id: cleanup_cache # hourly` `- id: purge_old_partitions # Sundays 04:00 UTC` `- id: etl_feature_store # nightly 01:00 UTC (new)` `- id: retrain_models # varies (see model spec)` Schedules and tasks for the first six DAGs are fixed per document lines 16-51 and 41-48 . --- ## **6 Configuration Parameters (superset of `02-parameter_reference.md`)** | Env var | Type | Default | Notes | | ----- | ----- | ----- | ----- | | `REPORTS_DB_URL` | string | *(none)* | Vault; Analytics Postgres conn | | `REDIS_URL` | string | `redis://redis:6379/0` | Shared Redis cache | | `EXPORT_MAX_ROWS` | int | **100 000** | Hard cap enforced in `reports-api` | | `PREDICTIVE_BONUS_CAP` | float | **0.10** | 10 % ceiling of domain score | | `MODEL_DRIFT_KS_THRESHOLD` | float | **0.07** | KS-stat threshold before retrain | All new variables follow Cookiecutter-Django naming, and are injected via ConfigMap or Vault. No overlap with global matrix (§7 of Definitive Parameter Reference) . --- ## **7 Resource & Autoscaling Defaults** * **reports-api**: 3 replicas, HPA 2→6, CPU 300 m / 600 m, RAM 384 Mi / 768 Mi * **reports-etl-worker**: 2 fixed pods, 400 m / 800 m, 512 Mi / 1 Gi * **Airflow**: 1 scheduler, 2 workers, 250 m CPU each These values must remain in sync with the Helm chart in `09-config_deploy.md`. --- ## **8 Privacy & Governance Guarantees** * SHA-256 hashing of `user_id`; no raw PII in analytics DB * Cohort suppression for counts \< 10 rows * Read-only role **`reports_reader`** restricted to dims/views; raw facts accessible only by ETL account * Full API request audit retained 6 months in OpenSearch --- ### **Change-Control Checklist** 1. **Add new feature column** → update §1 table list \+ §2 feature dictionary \+ regenerate `etl_feature_store`. 2. **New DAG** → append YAML in §5 and add schedule to `08-tasks_schedule.md`. 3. **Tweak resource limits** → sync with `09-config_deploy.md` and re-cite lines in §7. 4. **Alter privacy rules** → governance approval \+ update §8 and the Parameter Reference. This reference ensures that data scientists, ML engineers, and BI developers work from a single, immutable contract covering data structures, feature semantics, schedules, privacy, and runtime limits for the Insights stack powering EkoH and Smart Vote. Sources ##### **You said:** 7/11 ###### **ChatGPT said:** **`07-integration_mapping.md` — Cross-Module Route, Event & Auth Map (v 1.0)** *This document is the “wiring diagram” that binds EkoH / Smart Vote to the rest of the Konnaxion platform. Any change here forces a parallel patch in the Technical Spec, DevOps manifests, and Parameter Reference.* --- ## **0 Reference sources** * **Navigation Map** – canonical list of top-level routes * **Definitive Parameter Reference** – route invariants & env-var prefixes * **Technical Specification v14** – gateway, namespaces, auth roles * **Docs 01-05** in this series – DB tables, features, analytics. --- ## **1 REST / gRPC Route Matrix** /reports GET reports-api read:reports Analytics hub landing | Path | Method | Owner svc | Auth scope | Purpose | | ----- | ----- | ----- | ----- | ----- | | `/ekoh/profile/:uid` | `GET` | **EkohSvc** | `read:profile` (public if level=`public`) | Fetch expertise & ethics profile | | `/ekoh/score/recalc` | `POST` | **EkohSvc** | `admin:ekoh` | Queue async full recalculation | | `/smart-vote/cast` | `POST` | **VoteSvc** | `write:vote` | Submit weighted ballot | | `/smart-vote/result/:type/:id` | `GET` | **VoteSvc** | none (public) | Retrieve current weighted result | | `/reports/smart-vote` | `GET` | **reports-api** | `read:reports` | Time-series JSON for dashboards | | `/reports/export` | `GET` | **reports-api** | `admin:reports` | CSV/JSON bulk export (≤100 k rows) | *All new routes inherit API-gateway prefix `/api/v1/` and version header `X-Konnaxion-API: 1`.* *Path strings **must exactly match** Navigation Map slots to avoid regressions.* --- ## **2 Event-Bus (Kafka 3\) Topics** ws.smart-vote.\* aliases /ws/reports/\* until v15 migration | Topic | Producer | Consumer(s) | Schema ID (Avro) | Notes | | ----- | ----- | ----- | ----- | ----- | | `ekoh.score.recalc` | API-Gateway | Celery shard\*\* | `ekoh_recalc_v1` | Batch of user IDs | | `vote.cast` | **VoteSvc** | Aggregator, IntegrityGuard | `vote_cast_v1` | Weight & hash | | `integrity.alert` | IntegrityGuard | Ops-Slack-Hook | `integrity_alert_v1` | Collusion / Sybil | | `analytics.warehouse.load` | Airflow | Warehouse PG | `etl_load_v1` | Fact inserts | | ws.smart-vote.\* | \- | \- | \- | WebSocket alias for /ws/reports/\* | Topic names & schemas are immutable once released; new fields → new schema version with `_v2` suffix. --- ## **3 Frontend Route → Component Map** | SPA path | React component | Data source / hook | | ----- | ----- | ----- | | `/ekoh/profile/:uid` | `` | `useQuery('/ekoh/profile/:uid')` | | `/smart-vote/:entity/:id` | `` | `useQuery('/smart-vote/result/...')` \+ `` | | `/reports/smart-vote` | `` | `useQuery('/reports/smart-vote')` | Component filenames must align with UI conventions in the v14 spec. --- ## **4 Role & Permission Matrix** | Role | OAuth2 scope(s) | Capabilities | | ----- | ----- | ----- | | **`ROLE_USER`** | `read:profile`, `write:vote` | View any public profile, cast votes | | **`ROLE_EXPERT`** | *User* \+ `read:reports` | Access aggregate dashboards | | **`ROLE_ADMIN`** | *Expert* \+ `admin:ekoh`, `admin:reports` | Trigger score recalcs, exports, view integrity alerts | Scopes are issued by Auth Svc JWT and enforced by API-gateway filter inline with the Parameter Reference. --- ## **5 Integration Mapping Table (`integration_mapping`)** | Field | Meaning | Example | | ----- | ----- | ----- | | `module_name` | Source module requesting a Smart-Vote (e.g. `Ethikos`) | `"Ethikos"` | | `context_type` | Object type in that module | `"discussion_thread"` | | `mapping_details` | JSON: `{ "external_id": "abc", "vote_target_id": "uuid-123" }` | – | *Rule*: external module **never** stores raw vote IDs; must insert a mapping row then call `/smart-vote/cast` with the returned `vote_target_id`. --- ## **6 Webhooks / External Bridges** | Direction | URL / Target | Event | Payload | | ----- | ----- | ----- | ----- | | Outbound | **Ops Slack** (`https://hooks.slack.com/...`) | `integrity.alert` | `{ event_id, type, user_id?, severity }` | | Outbound | Layer-1 blockchain RPC | `vote_ledger` batch | `[ { sha256, block_height }... ]` | | Inbound | Credentials Registry webhook | new credential | `{ user, credential_type, domain }` → EkohSvc `/score/bulk` | All webhook secrets in Vault; L1 chain configurable via `LEDGER_RPC_URL`. --- ## **7 Environment-Variable Alignment** | Env var | Consumed by | Mirrors parameter | | ----- | ----- | ----- | | `EKOH_MULTIPLIER_CAP` | EkohSvc | `ethical_multiplier_cap` | | `SMARTVOTE_CONSENSUS_STRONG` | VoteSvc | `CONSENSUS_STRONG_THRESHOLD` | | `REPORTS_DB_URL` | reports-api, Airflow | warehouse Postgres DSN | Must match both `02-parameter_reference.md` and Helm chart values. --- ## **8 Sequence Diagram (cast vote)** mermaid CopyEdit `sequenceDiagram` `participant UI` `participant Gateway` `participant VoteSvc` `participant EkohSvc` `participant DB as Postgres` `participant Kafka` `UI->>Gateway: POST /smart-vote/cast` `Gateway->>VoteSvc: JWT + payload` `VoteSvc->>EkohSvc: gRPC getWeight(user, target)` `EkohSvc->>DB: SELECT score, ethics` `EkohSvc-->>VoteSvc: weight W` `VoteSvc->>DB: INSERT vote, vote_ledger` `VoteSvc->>Kafka: produce vote.cast` `VoteSvc-->>Gateway: 201 Created` `Gateway-->>UI: 201` --- ## **9 Change-Control Checklist** 1. **Add route** → update §1 \+ Role matrix, cite Navigation Map. 2. **New Kafka topic** → append §2 \+ Avro schema registry \+ Helm propagation. 3. **Modify auth scope** → revise §4 and sync with Keycloak realm config. 4. **Alter IntegrationMapping** → create reversible DB migration \+ update §5. Once merged, this mapping becomes the authoritative bridge spec; all services, front-end routes, and external modules must comply verbatim. Any divergence requires a version bump across this doc and affected layers. ##### **You said:** 8/11 ###### **ChatGPT said:** Thought for 9 seconds **`08-tasks_schedule.md` — Central Job-&-Scheduler Registry for EkoH \+ Smart Vote (v 1.0)** *All recurring jobs—whether Celery beat, Airflow DAG, CronJob, or Kubernetes Cron—are declared here.* *If it’s not on this page, it should not run in prod.* --- ## **0 Scheduler Landscape** | Layer | Engine | Clock source | Time-zone | Container image | | ----- | ----- | ----- | ----- | ----- | | **Application jobs** | Celery Beat 5.4 | K8s time | UTC | `ghcr.io/konnaxion/app-worker:` | | **Analytics / ETL** | Airflow 2.9 (K8sExecutor) | Airflow DB | UTC | `ghcr.io/konnaxion/reports-etl:` | | **K8s Infra** | k8s CronJob | cluster | UTC | `bitnami/kubectl:latest` | All schedules below are expressed in **cron-syntax UTC**. --- ## **1 Celery Periodic Tasks  *(operational EkoH / Smart Vote)*** | Task ID (code-name) | Queue | Schedule | SLA | Purpose | | ----- | ----- | ----- | ----- | ----- | | `ekoh_score_recalc` | `ekoh` | `0 2 * * *` (02:00 UTC daily) | 2 h | Recompute all `user_expertise_score` & `user_ethics_score` | | `contextual_analysis_batch` | `ekoh` | `*/30 * * * *` (every 30 min) | 15 min | Apply AI context adjustments; log to `context_analysis_log` | | `detect_emerging_expert` | `ekoh` | `30 2 * * *` | 30 min | Flag users meeting `EMERGING_EXPERT_THRESHOLD` | | `vote_result_aggregator` | `vote` | `*/5 * * * *` (every 5 min) | 2 min | Consume `vote.cast` topic; upsert `vote_result` | | `integrity_guard_scan` | `vote` | `*/30 * * * *` | 10 min | Scan for Sybil / ring patterns; emit `integrity.alert` | | `ledger_batch_to_chain` | `vote` | `0 * * * *` (top of hour) | 15 min | Anchor `vote_ledger` hashes on L1 blockchain | **Concurrency**: each queue runs with `--concurrency=4`; Beat sends max 1 task instance per schedule. --- ## **2 Airflow DAG Schedule  *(analytics warehouse)*** | DAG ID | Schedule | Owner | Success SLA | Notes | | ----- | ----- | ----- | ----- | ----- | | `etl_smart_vote` | `*/10 * * * *` | data-eng | 10 min | Incremental load → `smart_vote_fact` | | `etl_usage` | `0 * * * *` | data-eng | 30 min | Update `usage_mau_fact` | | `etl_perf` | `*/15 * * * *` | sre-team | 20 min | Pull Prometheus → `api_perf_fact` | | `refresh_mat_views` | `5 * * * *` | data-eng | 10 min | Refresh `vw_*` materialised views | | `etl_feature_store` | `0 1 * * *` | ml-ops | 1 h | Materialise nightly feature dataset | | `retrain_models` | `30 1 * * 1` (Mon) | ml-ops | 3 h | Conditional; skips if drift \< threshold | | `cleanup_cache` | `@hourly` | sre-team | 10 min | Purge Redis keys \> 12 h | | `purge_old_partitions` | `0 4 * * 0` (Sun) | dba | 2 h | Drop facts older than retention window | **DAG fail alerts** → Airflow’s `on_failure_callback` → `integrity.alert` Slack webhook. --- ## **3 Kubernetes CronJobs  *(infrastructure / housekeeping)*** | CronJob name | Schedule | Image tag | Command | Retention | | ----- | ----- | ----- | ----- | ----- | | `pgbackrest-full` | `0 0 * * *` | `pgbackrest:2.48` | full backup to S3 | 14 days | | `log-rotate` | `15 */6 * * *` | `bitnami/kubectl` | rotate & compress container logs | 7 days | | `prometheus-snapshot-export` | `45 0 * * *` | `prom/prometheus` | snapshot \+ push to long-term bucket | 30 days | --- ## **4 Alerting & Monitoring Rules** | Metric | Threshold | Alert channel | Owner | | ----- | ----- | ----- | ----- | | `task_duration{task='ekoh_score_recalc',p95}` | \> 2 h | PagerDuty SRE-P1 | sre-team | | `dag_failure_rate{dag_id='etl_smart_vote'}` | \> 5 % over 1 h | \#data-alerts | data-eng | | `integrity_event_unhandled_total` | \> 50 | \#moderation | trust-ops | | `vote_queue_lag_seconds` | \> 300 s | PagerDuty SRE-P2 | sre-team | Alerts configured in PrometheusRule CRDs; escalation policies in Ops runbook. --- ## **5 Environment Variables (Scheduler)** | Variable | Default | Consumed by | Description | | ----- | ----- | ----- | ----- | | `CELERY_BEAT_SCHEDULE_TZ` | `UTC` | all app-workers | Clock TZ | | `AIRFLOW__CORE__DEFAULT_TIMEZONE` | `UTC` | Airflow | Global TZ | | `EKOH_TASK_CONCURRENCY` | `4` | Celery | Overrides worker concurrency | | `EXPORT_MAX_ROWS` | `100000` | reports-api | Enforced by DAG `etl_export_guard` | Values must mirror Parameter Registry (§5 of `02-parameter_reference.md`) and Helm overrides. --- ## **6 Change-Control Checklist** 1. **Add / modify Celery task** * Patch code; register in `CeleryBeat` config; append row here (Section 1). 2. **Add / modify Airflow DAG** * PR must include DAG file, YAML schedule in `06-insights_module.md`, and row in Section 2\. 3. **Alter SLA or alert threshold** * Update Section 4, plus PrometheusRule manifest, then notify SRE slack. 4. **Rename CronJob** * Change K8s manifest \+ Section 3 table; preserve old job logs 7 days. This schedule is **source-of-truth** for all automated jobs in EkoH & Smart Vote. CI will fail if a task in code isn’t listed here, or a cron expression here is missing from manifests. Sources ##### **You said:** 9/11 ###### **ChatGPT said:** Thought for 11 seconds **`09-config_deploy.md` — Deployment & Configuration Guide for EkoH \+ Smart Vote (v 1.0)** *(This is the single source of truth for container images, Helm values, env vars, secrets, resource sizing, and CI/CD flow. Any change here **must** be reflected in the codebase, GitHub Actions, and Argo CD manifests before it can reach production.)* --- ## **0 Scope & Philosophy** * **Immutable images** – every build is tagged `v..` and never overwritten. * **Config-as-code** – *all* Kubernetes, Helm, and Argo CD objects live in Git. Runtime changes are carried by a manifest patch, never by kubectl exec. * **Twelve-factor env-vars** – no secrets or parameters hard-coded in images; everything injectable via `ConfigMap` or Vault-backed `Secret`. * **One namespace per logical stack** – `konnaxion-intel` for EkoH & Smart Vote, `konnaxion-analytics` for Reporting/Insights. --- ## **1 Container Images & Tagging** | Service / Job | Image repository | Tag pattern | Build trigger | | ----- | ----- | ----- | ----- | | **EkohSvc** | `ghcr.io/konnaxion/ekoh-svc` | `v1.0.` | Merge to `main` in `services/ekoh` | | **VoteSvc** | `ghcr.io/konnaxion/vote-svc` | `v1.0.` | Merge to `main` in `services/vote` | | **reports-api** | `ghcr.io/konnaxion/reports-api` | `v1.0.` | Merge to `main` in `services/reports` | | **Celery worker** | `ghcr.io/konnaxion/app-worker` | `v1.0.` | Merge in `services/common` | | **Airflow** | `ghcr.io/konnaxion/reports-etl` | `v1.0.` | Merge in `infra/airflow` | Tag promotion flow: **dev → staging → prod** via Argo CD wave-files. No `latest`. --- ## **2 Kubernetes Namespaces & RBAC** | Namespace | Purpose | ServiceAccounts (short) | | ----- | ----- | ----- | | `konnaxion-intel` | Ekoh & Smart Vote runtime | `ekoh-svc`, `vote-svc`, `app-worker` | | `konnaxion-analytics` | Reporting, Airflow, warehouse | `reports-api`, `airflow-scheduler`, `airflow-worker` | | `konnaxion-ops` | Monitoring & backups | `prometheus`, `pgbackrest` | ClusterRoles follow least-privilege: each SA can *get/list/watch* its own CRDs plus `secrets` in its namespace. Image pull uses a shared read-only registry secret. --- ## **3 Helm Chart Layout** arduino CopyEdit `charts/` `ekoh/` `Chart.yaml` `values.yaml # overridable per env` `templates/` `deployment.yaml` `hpa.yaml` `service.yaml` `ingress.yaml` `configmap-env.yaml` `smart-vote/` `reports/` `airflow/` `infra-backup/` Each chart ships opinionated defaults; per-env values overlay lives in `clusters//.yaml`. --- ## **4 Environment Variables & Secrets** ### **4.1 Shared (ConfigMap: `intel-common-env`)** | Env var | Default | Notes | | ----- | ----- | ----- | | `DJANGO_SETTINGS_MODULE` | `config.settings` | | | `LOG_LEVEL` | `INFO` | Map to gunicorn & Celery | | `REDIS_URL` | `redis://redis:6379/0` | Shared cache | ### **4.2 Ekoh / Smart Vote (ConfigMap: `ekoh-sv-env`)** | Env var | Maps to parameter | Default | | ----- | ----- | ----- | | `EKOH_MULTIPLIER_CAP` | `ethical_multiplier_cap` | `1.50` | | `RAW_WEIGHT_QUALITY` | `raw_weight_quality` | `1.000` | | `RAW_WEIGHT_EXPERTISE` | `raw_weight_expertise` | `1.500` | | `RAW_WEIGHT_FREQUENCY` | `raw_weight_frequency` | `0.750` | | `SMARTVOTE_CONSENSUS_STRONG` | `CONSENSUS_STRONG_THRESHOLD` | `0.75` | | `SMARTVOTE_EMERGING_DELTA` | `EMERGING_EXPERT_THRESHOLD` | `0.15` | | PROMETHEUS\_BASE\_URL | PROMETHEUS\_BASE\_URL | http://prometheus:9090 | ### **4.3 Secrets (Vault-CSI or SealedSecret)** | Secret key | Service | Purpose | | ----- | ----- | ----- | | `POSTGRES_DSN` | all | R/W DB connection | | `JWT_PUBLIC_KEY` | gateway & all | verify auth tokens | | `LEDGER_RPC_URL` | vote-svc | anchor `vote_ledger` hashes | | `AIRFLOW_FERNET_KEY` | airflow | DAG encryption | --- ## **5 Resource Requests, Limits & Autoscaling** | Deployment | Req CPU / RAM | Lim CPU / RAM | HPA | Scale trigger | | ----- | ----- | ----- | ----- | ----- | | EkohSvc | 250 m / 256 Mi | 500 m / 512 Mi | 2 → 6 | 70 % CPU | | VoteSvc | 300 m / 384 Mi | 600 m / 768 Mi | 2 → 8 | 70 % CPU or 400 req/s | | app-worker | 400 m / 512 Mi | 800 m / 1 Gi | 3 → 10 | Celery queue \> 500 | | reports-api | 300 m / 384 Mi | 600 m / 768 Mi | 2 → 6 | 70 % CPU | | airflow-worker | 400 m / 512 Mi | 800 m / 1 Gi | manual | Airflow pools | Values mirror §5 of `05-reporting_analytics.md`; prod sizing is doubled for HA. --- ## **6 Ingress & API Gateway** * **North-south traffic** hits NGINX Ingress Controller with TLS from LetsEncrypt. * All paths routed to Gateway (`/api/v1/*`) where per-service **internal** host names are resolved by header. * Rate-limit: 60 req/min/user; burst 200\. * WebSockets (`/smart-vote/live/*`) proxied with sticky sessions. --- ## **7 Observability Stack** * **Prometheus Operator** – scrapes `/metrics` on port 9090\. * **Grafana Dashboards** – `EkoH Overview`, `VoteSvc Latency`, `Celery Queues`, `Airflow DAGs`. * **Alertmanager** – routes to PagerDuty (severity P1/P2) and Slack `#intel-alerts`. * **Loki** \+ **Grafana Loki** – central log aggregation, 7-day retention. * **OpenTelemetry** traces exported to Jaeger in staging, Tempo in prod. --- ## **8 CI/CD Pipeline (GitHub Actions → Argo CD)** 1. **Push / PR** – run `pytest`, `black --check`, `doc-lint`, and SCA. 2. **Image build** – `docker buildx bake`, tag `v1.0.`, push to GHCR. 3. **Chart bump** – update `Chart.yaml.version`; commit in PR. 4. **Argo CD auto-sync** – watches `clusters/`; deploys new image tag & chart revision. 5. **Post-deploy smoke test** – GitHub Action workflow calls `/healthz` & verifies Prometheus targets up. Rollback \= Argo CD `sync --revision `. --- ## **9 Change-Control Checklist** 1. **New env-var** → add to Section 4, patch ConfigMap, reference in `02-parameter_reference.md`. 2. **Resource tweak** → Section 5 & Helm values; update Grafana alert thresholds if needed. 3. **New service** → add image repo (Section 1), namespace, RBAC, chart scaffold. 4. **Ingress path change** → Section 6 \+ Navigation Map \+ API Gateway routes. 5. **Secret rotation** → update Vault path & Secret spec; bump service Deployment for reload. Failure to update this guide **blocks the PR**: CI contains a linter that compares manifests against the tables above. --- This document now locks deployment topology, environment configuration, resource sizing, secrets mapping, and the CI/CD conveyor for the EkoH and Smart Vote modules. All operators, SREs, and developers must treat it as the canonical reference before touching infrastructure. ##### **You said:** 10/11 ###### **ChatGPT said:** Thought for 18 seconds **`10-testing_plan.md` — Quality-Engineering & CI Gate Reference (v 1.0)** *Every test artefact, coverage target, load goal and CI guard for EkoH \+ Smart Vote lives here. If the check isn’t listed, it must not block—or sneak past—production deployments.* --- ## **0 Purpose & scope** This plan enforces a **90 % line-coverage baseline** across back-end, front-end and ETL code, plus deterministic integration, e2e, load and security checks before a container tag may roll to staging or prod. --- ## **1 Test-pyramid & coverage targets** | Level | Tooling | Coverage goal | Key subjects | | ----- | ----- | ----- | ----- | | **Unit** | `pytest`, `pytest-django`, `vitest` | ≥ 90 % lines per package | score formulas, serializers, React hooks | | **Integration** | Django `APIClient`, `pytest-asyncio`, Dredd contract tests | pass rate 100 % | API routes, DB migrations, cache invalidation | | **End-to-End** | Playwright | green run on Chrome \+ Firefox \+ WebKit | user journeys *home → Smart Vote → CSV export* | | **Load / Perf** | k6, Locust | p95 \< 300 ms @ 200 RPS, error \< 1 % | | | **Security** | Semgrep, Bandit, OWASP ZAP | 0 high-sev findings | JWT, SQLi, XSS, RBAC | | **Data / ETL** | `pytest` \+ Great Expectations | all expectations green | `smart_vote_fact`, `dim_date`, materialised views | --- ## **2 Unit-test checklist by module** | Module | Must test… | Example cases | | ----- | ----- | ----- | | **EkohSvc** | `multidimensional_scoring` maths | weight override, negative raw values | | **VoteSvc** | `WeightCalculator` \+ DUP vote guard | ethics multiplier edge, UNIQUE constraint | | **reports-api** | serializers, range validation, cache decorator | invalid range \> 90 d, CSV header match | | **Airflow DAGs** | task graphs via `airflow dags test` | `etl_smart_vote` SQL row count \> 0 | | **React** | hooks & UI components | `useReport` cache expiry, `` error state | Mock external services with `responses`, Redis `fakeredis`, Kafka `aiokafka` fixtures. --- ## **3 Integration tests** | Contract | Tool | Approach | | ----- | ----- | ----- | | **OpenAPI** (Vote, Ekoh, reports) | **Dredd** | validate every example payload against `/openapi.yaml` | | **DB migrations** | `pytest-django` | migrate forward+backward; snapshot schema diff clean | | **Cache** | custom | POST vote → expect Redis set; TTL ≤ 600 s | | **Kafka flow** | `testcontainers-kafka` | produce `vote.cast`, expect `vote_result` row | --- ## **4 End-to-End scenarios** | ID | Path | Assertions | | ----- | ----- | ----- | | `SV001` | login → open `/smart-vote/foo` → cast ballot | toast “Vote saved”, row in `vote` | | `SV002` | anonymous → open `/smart-vote/...` | result chart visible, cast button disabled | | `REP001` | `/reports/smart-vote` 30 d → export CSV | file download ≤ 100 000 rows (config guard) | Runs headless in CI on chrome; screenshots saved on failure. --- ## **5 Performance & load** * **k6** script hits `/smart-vote/cast` and `/smart-vote/result` at 200 RPS for 5 min; test fails if p95 \> 150 ms (cast) or \> 400 ms (result/api) in line with API SLOs. * **Celery stress** – enqueue 10 k votes; expect aggregator latency \< 2 min. Results upload to Prometheus custom metric `ci_load_pass{branch="main"}`. --- ## **6 Security & privacy** | Check | Tool | Threshold | | ----- | ----- | ----- | | Static analysis | **Semgrep** coroutine | no high-sev rule violation | | Dependency scan | GitHub Dependabot \+ `pip-audit` | 0 critical CVE | | DAST | OWASP ZAP scripted | no auth bypass; same-site cookies enforced | Data-protection tests ensure SHA-256 user hashes persist in analytics DB. --- ## **7 CI pipeline quality-gates** On every PR GitHub Actions run: 1. **lint** (`ruff`, `prettier`, `eslint`) 2. **unit \+ integration tests** (`pytest -q`, `vitest run`) – block if coverage \< 90 % lines 3. **contract tests** (Dredd) 4. **load/perf quick-shot** (`k6` 50 RPS, 1 min) 5. **schema-diff** for analytics DB – fail on drift 6. **export-guard** – abort if CSV export would exceed cap 7. **image build** – only after all checks green; then Argo CD sync (see `09-config_deploy.md`). --- ## **8 Test data management** * Factory Boy for Django models; `pytest-snapshot` for deterministic JSON. * Analytics fixtures generated nightly from staging anonymised dump; truncated to last 7 d. * Playwright seeds browser local-storage with JWT signed by test RSA key. --- ## **9 Ownership & review** | Area | Code-owner | Review label | | ----- | ----- | ----- | | EkohSvc / VoteSvc tests | `@konnaxion/kollective-intel` | `INTEL-TEST` | | reports-api, ETL | `@konnaxion/data-eng` | `DATA-TEST` | | Front-end e2e | `@konnaxion/ux-guild` | `UX-TEST` | | Security scans | `@konnaxion/sec-ops` | `SEC-TEST` | A PR must have at least **one** approving review from each affected owner label. --- ## **10 Change-control checklist** 1. **New endpoint / feature** → add unit \+ contract tests; update pyramid table. 2. **Coverage threshold change** → governance vote \+ edit §1 and CI job. 3. **New load SLO** → adjust §5 numbers \+ Prometheus alert. 4. **Deprecate route/data** → drop relevant tests in same PR; ensure quality gate still ≥ 90 %. This plan is now the *single source of truth* for all testing and quality gates across EkoH and Smart Vote. CI enforces the rules above; an out-of-date MR will fail fast until the document and reality converge. Sources ##### **You said:** 11/11 ###### **ChatGPT said:** Thought for 7 seconds **`00-docs_index.md` — Master Documentation Directory (EkoH \+ Smart Vote, release v1.0)** *(Bookmark this page: every other file hangs off the anchors below. If you rename a doc or a section heading, update the map immediately or CI will fail.)* --- ## **1 Library at a Glance** | \# | File | What question it answers | Last-edited / version | | ----- | ----- | ----- | ----- | | **00** | **`00-docs_index.md`** | “Where do I find X?” — this table of contents | *2025-08-07 / v1.0* | | **01** | `01-db_schema.md` | Exact tables, PK/FK, ERD, retention rules | v1.0 | | **02** | `02-parameter_reference.md` | All tunable weights, caps, enums, env-vars | v1.0 | | **03** | `03-technical_spec.md` | Layer-by-layer APIs, algorithms, flows | v1.0 | | **04** | `04-inventory_of_features.md` | Feature catalogue → code-name cross-ref | v1.0 | | **05** | `05-reporting_analytics.md` | Dashboards, star-schema, ETL, metrics | v1.0 | | **06** | `06-insights_module.md` | Feature store, ML models, drift rules | v1.0 | | **07** | `07-integration_mapping.md` | Routes, Kafka topics, auth scopes, Webhooks | v1.0 | | **08** | `08-tasks_schedule.md` | Celery, Airflow, Cron—when and how they run | v1.0 | | **09** | `09-config_deploy.md` | Helm values, env-var matrices, resource sizes | v1.0 | | **10** | `10-testing_plan.md` | Test pyramid, coverage gates, CI workflow | v1.0 | **Tip for new contributors** *Need a constant?* — look in **02**. *Need an API payload or path?* — check **03** then **07**. *Want to know why a scheduled job failed?* — see **08** then Grafana links in **09**. --- ## **2 Navigation Rules & Stable Anchors** * **Filenames are immutable** once shipped. Patch this index first, then apply the rename across code & CI. * **Section IDs** (markdown headings) serve as intra-doc anchors; keep wording stable or add an explicit ``. * **CI doc-lint** (`docs-link-checker`) resolves every link on PR; a broken anchor blocks merge. --- ## **3 Versioning & Change-Control** | Change type | Required actions | | ----- | ----- | | **Add new doc** | Choose next number (11, 12…), add row here, create file skeleton with `{#}` header. | | **Major breaking change** (schema, route, env-var) | Increment minor version on *all affected docs*; update date stamps in table above. | | **Minor clarifications** | Edit doc, bump patch in front-matter, no index change needed. | | **Deprecation** | Mark row as ***deprecated***, point to replacement, remove after 2 minor versions. | Front-matter template for every doc: yaml CopyEdit `---` `title: 03-technical_spec` `version: v1.0` `updated: 2025-08-07` `---` --- ## **4 Ownership & Review Matrix** | File pattern | Code-owner GitHub team | | ----- | ----- | | `0*-*.md` (docs in this library) | **@konnaxion/doc-guild** | | `services/ekoh/**` `services/vote/**` | **@konnaxion/kollective-intel** | | `services/reports/**` `infra/airflow/**` | **@konnaxion/data-eng** | | `charts/**` `clusters/**` | **@konnaxion/sre-team** | At least one approving review from the relevant owner is mandatory; doc PRs without an index update will be auto-rejected. --- ## **5 Quick-jump Markdown Links** * DB schema → EkoH tables * Parameter registry → Smart Vote section * Tech spec → Weight calculator pseudocode * Report ETL schedule * Airflow DAG registry * Kafka topic list * Celery task timetable * Helm env-var matrix * Load test thresholds --- ## **6 Onboarding Checklist (1-hour crash path)** 1. Clone repo → run `make init-docs` → open this index. 2. Skim **01** schema & **02** parameters (10 min). 3. Read **03** tech spec weight section (10 min). 4. Fire up `/docs/architecture.drawio` for high-level component map (5 min). 5. Run `pytest -q` & `npm test` (15 min). 6. Open Grafana at `/d/ekoh-overview` to see live metrics (10 min). --- With this index in place, the EkoH \+ Smart Vote knowledge base is fully self-navigable. Keep links alive, headers consistent, and versions current—everything else will follow. ### **Annex A – Implementation Inputs & Repo Layout** | \# | Input | Final choice | Alignment notes | | ----- | ----- | ----- | ----- | | **A-1** | **Runtime stack** | **Python 3.12 \+ Django 4.2** for EkohSvc / VoteSvc · **React 18 \+ TypeScript** for SPA | Same versions already used in the root *Konnaxion* project (`apps/konnaxion_core`). No extra base images needed. | | **A-2** | **Repository location** | **Same repo** – [https://github.com/Rejean-McCormick/Konnaxion](https://github.com/Rejean-McCormick/Konnaxion) | Keeps CI, CODEOWNERS and Argo CD wave-files untouched. | | **A-3** | **Folder structure inside repo** | text\\nmodules/ekoh-smartvote/\\n├── ekoh/ \# Django app (Expertise & Ethics)\\n├── smart\_vote/ \# Django app (Weighted Voting)\\n├── charts/ekoh-smartvote \# Helm sub-chart overlay\\n├── fixtures/ \# UNESCO ISCED-F JSON, demo users\\n├── pyproject.toml \# PEP 621 package metadata\\n└── README.md \# Stand-alone quick-start\\n | Mirrors existing `apps/…` layout; keeps all module code in one subtree for easy subtree-split or wheel build. | | **A-4** | **Python package namespace** | `konnaxion.ekoh` and `konnaxion.smartvote` (namespace-package under `modules/ekoh-smartvote`) | Import paths stay valid if the module is later moved to its own repo. | | **A-5** | **Database strategy** | Shared Postgres cluster, dedicated **schema `ekoh_smartvote`**. Django `OPTIONS: {"options": "-c search_path=ekoh_smartvote,public"}`. | Portable via `pg_dump -n ekoh_smartvote`; zero extra DB instances in Konnaxion. | | **A-6** | **Secrets handling** | All module secrets pulled from **Vault-CSI** at `secret/ekoh-smartvote/*`. Placeholders committed as `` in Helm values. | Same pattern as core; no clear-text creds in repo. | | **A-7** | **Event backend** | Kafka in prod (`EVENT_BACKEND="kafka"`). Automatic fallback to in-process bus when `EVENT_BACKEND="local"` (dev/test). | Keeps high-throughput path yet runnable with `docker-compose` alone. | | **A-8** | **Blockchain anchoring** | Disabled by default (`LEDGER_RPC_URL=""`). Can be enabled per-tenant (e.g. Polygon) without code changes. | | | **A-9** | **UI theming** | Re-use **K-brand Tailwind token set** shipped in root repo. Optional override via `modules/ekoh-smartvote/tailwind.override.js`. | | | **A-10** | **Demo data** | Dev seed only (`DJANGO_ENV=dev`): creates `admin@example.com / admin123` \+ 3 demo users \+ 20 sample votes. **No auto-admin in prod.** | | #### **CI / CD specifics** * **Workflow file:** `.github/workflows/ekoh-smartvote.yml` triggers on changes under `modules/ekoh-smartvote/**`. * **Docker tags:** `ghcr.io/konnaxion/ekoh-smartvote:` built from `Dockerfile` in that module folder, then referenced by the sub-chart. * **Argo CD:** new Application manifest `argo/ekoh-smartvote.yaml` pointing to `charts/ekoh-smartvote` with `values-prod.yaml`. With this annex the module is fully codified: one repo, one schema, one chart — but still extractable via git subtree split \--prefix modules/ekoh-smartvote \-b ekoh-release or pip wheel modules/ekoh-smartvote \-w dist/ for future stand-alone deployments. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/ekoh-system-overview-smart-vote-ecosystem.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b1dafcb4ce3ecb9028f31595e55f37bcb25a08b5d768b5d2766e802e48c8b25b CONTENT_BYTES: 5295 ================================================================================================ # EkoH System Overview ## Status This document describes the current architectural role of **EkoH** inside Konnaxion and ethiKos. The binding separation is: - **ethiKos / Konsultations** own source participation facts. - **EkoH** supplies contextual expertise, reliability, provenance, and privacy-aware profile data. - **Smart Vote** may use an EkoH snapshot to publish a declared, reproducible reading of source facts. EkoH is **not** the voting engine and an EkoH-weighted result is **not** the canonical source result. ## 1. Purpose EkoH helps answer a narrow question: > What competence and reliability context is relevant to this contribution, for this domain, at this time? It does not assign a universal rank to a person. Expertise is contextual and domain-bounded. A strong economics profile may matter greatly for a fiscal consultation and provide little or no additional signal for a software-security question. ## 2. Domain-bounded expertise EkoH represents expertise as a vector across a governed knowledge taxonomy. The current implementation uses `ExpertiseCategory` and `UserExpertiseScore`. Conceptually: ```text user expertise = { domain A: score, domain B: score, domain C: score, ... } ``` Scores must be grounded in evidence such as verified credentials, documented practice, validated contributions, peer review, or other governed sources. Absence of expertise in a domain is not a penalty; it simply means no expertise bonus is available for that domain. The current scoring contract normalizes domain expertise to `0..1`. ## 3. Evidence and provenance An EkoH score should be explainable. The system should be able to answer: - Which domain is being scored? - Which evidence contributed? - Which rules transformed that evidence into the current score? - When was the score computed? - Which version of the scoring policy was used? - Can the subject challenge or correct the evidence? Automated analysis may assist classification or propose adjustments, but probabilistic output must not silently become authoritative profile state. ## 4. Reliability / ethics signal EkoH may expose a governed reliability or ethics modifier. This is a cross-cutting signal, not a declaration of a person's moral worth. The modifier must be: - explainable; - governed; - appealable where appropriate; - bounded; - subject to privacy rules; - separable from domain expertise. For demo data where no defensible evidence exists, the neutral value is `1.0`. ## 5. Consultation relevance A consultation or declared Smart Vote lens specifies which expertise domains are relevant and their relative importance. Example: ```text Federal fiscal question Economics 40% Public administration 20% Statistics 15% Political science 15% Welfare 10% ``` The weights form a relevance vector and should normally sum to `1.0`. This prevents expertise from leaking across unrelated domains. ## 5.1 Source binding A Smart Vote consultation used for an ethiKos topic must be bound explicitly to that source object. The current binding is `SourceConsultationBinding`: ```text source_type = ethikos_topic source_id = consultation = ``` The binding prevents title-based guessing and lets the same source facts be read through Smart Vote without transferring ownership of the topic. Demo schema v3 uses `topic_relevance` for this path. ## 6. EkoH and Smart Vote For participant `u` and consultation `c`, Smart Vote may compute contextual expertise alignment from: ```text alignment(u,c) = Σ relevance(c,d) × expertise(u,d) ``` EkoH provides the expertise data. Smart Vote owns the derived reading. The public or canonical baseline remains a separate result. A weighted reading must not overwrite source ballots, stances, arguments, or baseline outcomes. ## 7. Multiple readings The architectural rule is: > Single source facts, multiple declared readings. Examples of possible readings include: - public baseline; - relevant-expertise advisory reading; - affected-group reading; - jurisdictional reading; - expert-panel reading. A lens is a method of interpretation, not truth. A reading must identify its method, inputs, snapshot, and computation time. ## 8. Privacy and confidentiality EkoH profile data can be sensitive. Visibility settings must be respected independently from the existence of a reading. A Smart Vote reading may use an authorized EkoH snapshot without exposing every participant's private domain scores publicly. Public, pseudonymous, anonymous, and institutionally private contexts must remain distinguishable. ## 9. Current implementation boundary The current EkoH API exposes a read-only user profile with: - user identity/display information; - confidentiality level; - per-domain weighted expertise scores; - ethics/reliability score. The profile is context. It is not a fixed global Smart Vote weight. ## 10. Invariants - Expertise ≠ sovereignty. - Competence ≠ political mandate. - Political equality ≠ epistemic equivalence. - EkoH ≠ Smart Vote. - EkoH score ≠ universal human rank. - AI output ≠ canonical EkoH state. - Weighted reading ≠ source fact. - Lens ≠ truth. - Baseline results remain visible. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/konnaxion-smart-vote-weighted-voting-system-structure-and-logic-internal-white-paper.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 507fcbee41c3ca3378444bec3ae5b7aff675b06acdaff9433f793f169f947dc9 CONTENT_BYTES: 8214 ================================================================================================ # Konnaxion Smart Vote — Contextual Collective-Intelligence Readings ## Executive summary Smart Vote is a mechanism for producing **parallel, declared readings** of collective input. Its purpose is not to replace democratic equality with a permanent hierarchy of experts. It makes relevant expertise legible alongside the public baseline. The architecture rests on four distinctions: 1. **Political equality is not epistemic equivalence.** Everyone may retain an equal baseline voice while relevant expertise can be examined separately. 2. **Expertise is contextual.** Competence in economics does not create authority in cybersecurity, medicine, education, or Indigenous governance. 3. **A reading is not truth.** A weighted result is an interpretive lens over source facts. 4. **Advice is not decision authority.** Institutions remain responsible for legitimate decisions. ## 1. The problem Public decisions often combine several kinds of knowledge: lived experience, technical expertise, economic analysis, legal constraints, institutional knowledge, territorial knowledge, and public preference. A single raw vote can reveal preference but cannot by itself reveal how the result changes when a particular type of relevant knowledge is considered. A single opaque weighted score creates the opposite problem: it hides the democratic baseline and makes the weighting difficult to interpret. Smart Vote therefore keeps the signals separate. ## 2. Single facts, multiple readings The canonical rule is: > **One set of source facts; multiple declared readings.** For example, an ethiKos consultation might expose: ```text Public baseline Relevant-expertise reading Affected-community reading Jurisdictional reading Expert-panel reading ``` These readings can agree or diverge. Neither convergence nor disagreement is automatically truth. The objective is coherence, not consensus. ## 3. EkoH as the contextual layer EkoH describes demonstrated expertise by domain. It does not assign a universal rank to the person. A profile can be visualized as: ```text Economics 0.92 Public administration 0.78 Software systems 0.20 Environmental science 0.15 ``` A different participant may have the inverse profile. The same person can therefore have strong advisory relevance in one consultation and ordinary baseline influence in another. ## 4. Questions also have profiles A consultation declares its domain relevance before a weighted reading is computed. Example A — fiscal policy: ```text Economics 40% Public administration 20% Statistics 15% Political science 15% Welfare 10% ``` Example B — technological sovereignty: ```text Software / AI 25% Network / data systems 10% Economics 20% Administration 15% Political science 10% Law 10% Energy 10% ``` The first question will amplify different participants than the second. That is the point. ## 4.1 Source-target binding The question remains owned by ethiKos/Konsultations. Smart Vote creates a reading context only after an explicit source-target binding exists. `SourceConsultationBinding` maps an `ethikos_topic` source identifier to the Smart Vote consultation that owns the relevance vector. No runtime component should infer this relationship from matching titles. For demo schema v3, `topic_relevance` is therefore the preferred import form. The importer creates or updates the binding and writes the declared domain vector to `ConsultationRelevance`. ## 5. Why domain relevance must be visible The domain vector is part of the governance of the lens. It cannot be a hidden model choice. Participants should be able to ask: - Why is economics 30% rather than 10%? - Why is cybersecurity absent? - Does the question require Indigenous governance expertise? - Is the lens missing a materially affected group? A poor relevance vector can produce a poor reading even if the EkoH profiles themselves are accurate. ## 6. Weighting without sovereignty A useful conceptual formula is: ```text alignment = participant expertise · question relevance reading weight = baseline + bounded contextual bonus ``` The weight exists **for that reading of that question**. It is not attached permanently to the person. This preserves a core distinction: > Expertise informs judgment. It does not silently acquire political sovereignty. ## 7. Public baseline remains visible A Smart Vote implementation should never force observers to choose between democracy and expertise by hiding one of them. Example: ```text Public baseline: 61% support Relevant-expertise reading: 74% support ``` The difference is information. A decision-maker can then inspect why it exists: which domains mattered, which expert cohorts participated, where evidence converged, and which expertise was missing. The system should also be able to report insufficient coverage rather than imply false confidence. ## 8. Institutions, individuals, and cohorts An institutional position and an individual EkoH profile are not identical objects. A ministry, statistical agency, professional association, university, Indigenous nation, private firm, and individual expert may each contribute legitimate knowledge, but they represent different forms of authority and evidence. Readings should declare how these actor types are included rather than silently combine them into one undifferentiated score. ## 9. Ethics and reliability EkoH may carry a reliability or ethics modifier, but this must not become a universal morality score. The signal should concern governed properties such as evidence integrity, declared conflicts, repeated manipulation, or other reviewable conduct. It must be bounded, explainable, privacy-aware, and open to correction. For demonstrations where no evidence supports differentiation, the neutral multiplier should be used. ## 10. Conflict and recusal A participant may possess genuine expertise and also have a strong conflict or prior commitment. Those facts can coexist. The system should support explicit conflict declarations and recusal without erasing the participant's arguments or evidence. A reading can then include, exclude, or separately display the contribution according to its declared rules. ## 11. Confidential contexts The same core can support public or restricted deliberation. Sensitive diplomatic, security, commercial, cabinet, or other institutional processes may require closed access. Confidentiality changes who can see or participate; it does not require a different epistemic core. Source facts, provenance, domain relevance, and declared readings can still be governed consistently inside the closed environment. ## 12. AI boundary AI may assist with: - domain classification; - evidence extraction; - summarization; - translation; - comparison; - anomaly detection; - proposed relevance vectors. AI output is not authoritative by default. It must not silently change canonical ballots, EkoH scores, lens definitions, or decision authority. ## 13. Architectural value The value of Smart Vote is not that experts “win” over the public. The value is that a decision-maker can inspect several legitimate signals without collapsing them into one opaque score. This makes it possible to ask: - What does the public prefer? - What does relevant expertise suggest? - What do directly affected groups see differently? - Where is the evidence strong? - Which domains are underrepresented? - Where do the readings converge or diverge? That is a more useful form of collective intelligence than either an unstructured comment stream or an invisible technocratic weighting. ## 14. Canonical invariants - Coherence ≠ consensus. - Expertise ≠ sovereignty. - Competence ≠ mandate. - Political equality ≠ epistemic equivalence. - Affectedness ≠ expertise. - Vote count ≠ collective judgment. - Majority ≠ truth. - Expert consensus ≠ democratic mandate. - One score ≠ one reality. - Lens ≠ truth. - Advice ≠ authority. - AI analysis ≠ automated sovereignty. - Source facts must not be mutated by derived readings. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/Smart Vote - Reading Contract.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 29a63181e2846021a683b3fb1e5af1e7d2befca975cc09df87c6bd0c2b749af2 CONTENT_BYTES: 2187 ================================================================================================ # Smart Vote — Reading Contract ## Core rule > Source participation and derived interpretation are separate objects. For ethiKos: ```text EthikosTopic + EthikosStance ↓ source facts baseline aggregation ↓ SourceConsultationBinding ConsultationRelevance EkoH context ↓ Smart Vote reading ``` ## Current endpoint ```text GET /api/v1/smart-vote/readings/ethikos-topic// ``` ## Current envelope ```json { "target_type": "ethikos_topic", "target_id": "...", "smart_vote_consultation_id": "...", "baseline": { "reading_key": "baseline", "lens_hash": null, "snapshot_ref": null, "computed_at": "...", "results_payload": {} }, "readings": [ { "reading_key": "ekoh_weighted_v1", "lens_hash": "sha256:...", "snapshot_ref": "ekoh_snapshot:...", "computed_at": "...", "results_payload": {} } ] } ``` ## Lens Current EkoH reading formula is conceptually: ```text alignment(u,c) = Σ relevance(c,d) × expertise(u,d) bonus(u,c) = min(alignment(u,c), configured_cap) weight(u,c) = 1 + bonus(u,c) × ethics_modifier(u) ``` The weight is a **reading weight**, not a global personal voting weight. ## Baseline The baseline is computed from the source stances without the EkoH lens. It must remain independently identifiable in the response/UI. ## Snapshot identity The current service hashes the EkoH inputs used by the reading and emits a `snapshot_ref`. For a reading to be called durably published/replayable, the system must also make the referenced snapshot or equivalent complete inputs recoverable. A hash alone proves identity; it does not store the data. ## Privacy Participant-level details in a reading are filtered through EkoH rating access. A reading can use authorized context without exposing every private score. ## Prohibitions - Do not overwrite `EthikosStance` with a weighted value. - Do not copy baseline into a reading field when no reading exists. - Do not describe EkoH as assigning a universal voting weight. - Do not let the client submit an authoritative derived weight. - Do not hide divergence between baseline and advisory reading. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-consultation-simulations.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 47a82d05bf25240f9bb17d253a6b38995da301827236a7e0ff46034f2a46fe8b CONTENT_BYTES: 36173 ================================================================================================ # **Smart Vote Consultation Simulations** **Smart Vote Overview:** *Smart Vote* is a weighted voting system that adjusts each individual’s voting power based on their expertise in relevant knowledge domains and their ethical standing. Instead of “one person, one vote,” each voter carries a weight calculated from a *merit profile* across pertinent domains and an ethics multiplier. In the following simulations, we run five public consultations – on climate policy, vaccine mandates, AI regulation, international aid, and arts funding – involving well-known figures (Barack Obama, Donald Trump, Pope Francis, a relevant Nobel laureate, Bill Gates, Greta Thunberg, Tom Hanks, and James Hetfield). For each consultation, we identify key domains of expertise (aligned with UNESCO’s ISCED-F classification) and assign domain weightings proportional to their importance for the issue. We then assign realistic domain-specific merit scores (0–10) to each personality, reflecting their expertise or accomplishments in those areas, and an estimated ethics multiplier (\>1.0 for notable positive ethical contributions, \~1.0 baseline, or \<1.0 if tarnished by controversy). Finally, we apply the Smart Vote formula: Total Voting Weight=(∑domains d(DomainWeightd×Merit in d))×Ethics Multiplier.\\text{Total Voting Weight} \= \\Big(\\sum\_{\\text{domains }d} (\\text{DomainWeight}\_d \\times \\text{Merit in }d)\\Big) \\times \\text{Ethics Multiplier}. This produces each individual’s effective voting weight. Below we detail each consultation, the chosen domains and weights, participants’ merit profiles, and the resulting weighted vote distribution. (All domain fields are drawn from UNESCO’s ISCED-F taxonomy – e.g. *Environmental Sciences* (code 0521), *Political Science* (0312), *Economics* (0311), etc. – ensuring standard definitions of expertise areas.) ## **Consultation 1: Climate Policy** **Issue:** A public consultation on national **Climate Policy** (e.g. setting emissions targets, climate action plans). **Relevant Domains & Weights:** For climate policy, we consider three primary domains: **Environmental Science** (50%), **Public Policy (Political Science)** (30%), and **Economics** (20%). These weights reflect that climate decision-making relies most on climate/environmental science expertise, with significant input from policy/governance knowledge and some economic consideration (for cost-benefit and implementation feasibility). Environmental science corresponds to the field of environmental sciences in UNESCO’s classification, political/public policy expertise falls under social sciences (political science and civics), and economics is a key social science relevant to climate policy. **Participants’ Merit Profiles:** Below is each figure’s merit vector in the relevant domains (0–10 scale), their ethics multiplier, and the resulting total weight. We assign high merit in *Environmental Science* to the climate science Nobel laureate, while Greta Thunberg, as a climate activist, has moderate climate-science familiarity. Barack Obama and Donald Trump have low environmental science expertise but high and moderate public policy merits respectively (as former presidents). Obama also scores moderately in economics (having dealt with economic policy), whereas Trump, with a business background, scores relatively high in economics. Pope Francis, despite moral leadership on climate (he wrote the encyclical *Laudato si’* on the environment), has minimal formal science or policy expertise, but we will see his strong ethics multiplier boost his weight. Bill Gates is assigned moderate environmental science merit (due to his engagement in climate innovation investments) and high economics merit, given his experience in technology business. Tom Hanks and James Hetfield, with no particular background in these domains, have negligible merit scores. The ethics multipliers qualitatively reflect each individual’s public ethical stance: e.g. Pope Francis (renowned for humility and social justice) gets a high multiplier (1.20), Bill Gates (major philanthropist) 1.10, Greta Thunberg (altruistic activist) 1.10, Barack Obama and Tom Hanks around 1.05 (respected public figures with generally positive ethical reputations), a baseline 1.00 for the Nobel laureate (assumed neutral), and a slightly lower value for Donald Trump (0.90, due to controversies affecting his perceived ethics). James Hetfield is given 0.95 (little public philanthropic record). | Participant | Environmental Science | Public Policy (Political Science) | Economics | Ethics Multiplier | Total Weight | | ----- | ----- | ----- | ----- | ----- | ----- | | Nobel Laureate (Climate Science) | 10 | 5 | 3 | 1.00 | 7.10 | | Barack Obama | 4 | 10 | 7 | 1.05 | 6.72 | | Bill Gates | 5 | 4 | 8 | 1.10 | 5.83 | | Greta Thunberg | 6 | 5 | 2 | 1.10 | 5.39 | | Donald Trump | 1 | 7 | 8 | 0.90 | 3.78 | | Pope Francis | 2 | 3 | 2 | 1.20 | 2.76 | | Tom Hanks | 1 | 1 | 2 | 1.05 | 1.26 | | James Hetfield | 1 | 1 | 1 | 0.95 | 0.95 | *Table: Merit vectors and calculated voting weights for the Climate Policy consultation.* The Nobel-winning climate scientist unsurprisingly excels in *Environmental Science* (10/10), giving her the highest weight. Obama’s perfect 10 in public policy and solid economics (7) make him a close second in total weight, aided by a modest ethics bump. Bill Gates and Greta Thunberg cluster next; Gates leverages strong economics and a good ethics score, while Greta’s domain knowledge (though not expert-level) plus high ethics yield a comparable weight. Trump’s influence is lower – despite decent economics and policy scores, his negligible science merit and a penalty on ethics diminish his weight. Pope Francis, with scant technical merits, relies on his 1.20 ethics factor to reach 2.76 weight (still modest overall). Hanks and Hetfield, lacking expertise in any relevant domain, end up with minimal weights (\~1 or less), effectively having a very minor say on this technical climate policy issue. This outcome demonstrates the Smart Vote principle: those with domain-aligned expertise and positive social contributions carry more influence, whereas popular figures without relevant knowledge (or with lesser ethical standing) have proportionally less sway. *Figure: Weighted vote distribution among participants for the Climate Policy consultation.* The chart highlights the **Nobel Laureate** (far right bar) as having the greatest voting weight (\~7.1) due to top-tier environmental science credentials. **Barack Obama** follows closely, reflecting his strong public policy expertise (the second-highest bar). **Bill Gates** and **Greta Thunberg** have substantial but lower weights (middle bars), each contributing meaningfully thanks to moderate domain knowledge and high ethics. In contrast, **Tom Hanks** and **James Hetfield** (far left bars) hold almost negligible weight, illustrating how limited domain expertise results in minimal influence under Smart Vote’s weighted system. ## **Consultation 2: Vaccine Mandates Policy** **Issue:** A consultation on **Vaccine Mandates** (e.g. requiring COVID-19 vaccinations) – a topic at the intersection of public health, law, and ethics. **Relevant Domains & Weights:** Key domains here include **Medical Science (Health)** (50%), **Public Policy / Law** (30%), and **Ethics / Social Impact** (20%). Successfully evaluating vaccine mandate policy requires foremost an understanding of health and epidemiology (hence 50% weight on medical science, which falls under Health & Welfare in ISCED classifications), significant knowledge of legal/government policy frameworks (30% weight, aligning with political science/law fields), and consideration of ethical and societal implications (20% weight, reflecting the importance of ethics and public trust – ethics as an academic field is classified under Philosophy & Ethics in UNESCO terms). **Participants’ Merit Profiles:** For medical science, we grant a perfect 10 to the Nobel Laureate in Medicine (representing a top virologist or immunologist). Bill Gates, through his foundation’s extensive work on global health and vaccines, scores a notable 6 in medical knowledge. Obama and Trump have minimal medical science background (3 and 1 respectively), while Pope Francis and the activist/celebrity figures score 1 (no medical training). In Public Policy/Law, Obama earns 10 (deep experience in governance), Trump 7 (some policy exposure as former president), and Gates 6 (experience influencing global health policy via philanthropy); the Nobel scientist and Greta get 5 and 2 respectively (scientists often engage in advisory roles to some extent, and Greta’s policy knowledge here is minimal). Ethics/Social Impact merit is highest for Pope Francis, a moral authority who has publicly emphasized caring for others, solidarity, etc., here given 10\. Gates and the Nobel laureate both have strong ethics/social scores (7 each), reflecting Gates’s philanthropic mission and a scientist’s adherence to ethical standards in public health. Obama scores 7 (valuing science and societal well-being in his leadership), Greta Thunberg 5 (no specific role in vaccine ethics but a general social conscience), Tom Hanks 4 (he advocated for COVID precautions, leveraging his trusted reputation), and Trump only 3 (heavily criticized for spreading misinformation, indicating a low alignment with the ethical promotion of public health). The ethics multipliers remain as before: Pope Francis the highest (1.20), Gates and Greta 1.10, Obama/Hanks 1.05, Nobel laureate baseline 1.00, Trump 0.90, Hetfield 0.95. | Participant | Medical Science (Health) | Public Policy / Law | Ethics / Social Impact | Ethics Multiplier | Total Weight | | ----- | ----- | ----- | ----- | ----- | ----- | | Nobel Laureate (Medicine) | 10 | 5 | 7 | 1.00 | 7.90 | | Bill Gates | 6 | 6 | 7 | 1.10 | 6.82 | | Barack Obama | 3 | 10 | 7 | 1.05 | 6.20 | | Pope Francis | 1 | 2 | 10 | 1.20 | 3.72 | | Donald Trump | 1 | 7 | 3 | 0.90 | 2.88 | | Tom Hanks | 2 | 2 | 4 | 1.05 | 2.52 | | Greta Thunberg | 1 | 2 | 5 | 1.10 | 2.31 | | James Hetfield | 1 | 1 | 2 | 0.95 | 1.14 | *Table: Merit and weight summary for the Vaccine Mandates consultation.* The Nobel-winning physician, with unparalleled medical expertise, achieves the top weight (\~7.9). Bill Gates closely follows (\~6.8) – while not a doctor, his solid grasp of public health policy and strong ethical reputation boost his influence. Obama also scores highly (\~6.2), thanks to his policy experience and ethical credibility, even though his medical knowledge is limited. A significant drop follows: Pope Francis reaches about 3.7 weight – his negligible science/policy merits are partially offset by a high ethics factor and moral voice. Trump’s weight (\~2.9) remains low, dragged down by poor science understanding and a lower ethics multiplier, despite some policy influence. The remaining figures (Hanks \~2.5, Greta \~2.3, Hetfield \~1.1) have marginal impact. Notably, the spread of weights shows that domain experts and those actively engaged in health causes dominate the consultation outcome, whereas celebrity status alone (Hanks, Hetfield) or high office without science alignment (Trump) results in substantially less weight. *Figure: Weighted vote distribution for the Vaccine Mandates consultation.* **Nobel Laureate (Medicine)** holds the greatest weight (rightmost bar), reflecting primacy of medical expertise in this decision. **Bill Gates** and **Barack Obama** also command significant weight (next bars to the left), leveraging their contributions to public health policy and governance. The middle bars (e.g. **Pope Francis**) show moderate influence coming mainly from ethical authority rather than technical expertise. The least-weighted participants (**Tom Hanks**, **Greta Thunberg**, **James Hetfield**) have minimal influence (far left bars), underscoring that without medical or policy expertise their voices carry little weight on this public health mandate. ## **Consultation 3: AI Regulation** **Issue:** A consultation on **AI Regulation** (e.g. how to govern artificial intelligence and algorithms). This topic blends technological, legal, and ethical dimensions. **Relevant Domains & Weights:** We define three relevant domains: **Computer Science (AI Technology)** (40%), **Public Policy / Law** (30%), and **Ethics** (30%). Expertise in AI technology (computer science, specifically AI development) is crucial (40%) for informed regulation. Policy and legal expertise is also key (30%) for crafting implementable regulations. Given widespread concerns about AI’s moral implications, we allocate a substantial weight to ethics (30%) – understanding AI ethics, risks, and societal impacts is on par with policy know-how here. (In UNESCO’s framework, *Artificial Intelligence* falls under Information & Communication Technologies – e.g. AI is listed as a topic under ICT fields – while *Computer Science* and software development are core ICT subfields. Ethics remains under Philosophy/Ethics as a knowledge domain.) **Participants’ Merit Profiles:** The Nobel-caliber participant here is not literally a Nobel (there is no Nobel in computer science), but we include a **Turing Award**\-level AI researcher as “Nobel Laureate (AI Research)” with top technical merit (10 in AI tech domain). Bill Gates, a tech pioneer, scores just below (9) in AI tech – while not an AI researcher, he has deep computing expertise and actively engages with AI issues. Obama and Trump have minimal technical knowledge (3 and 2 respectively), and the non-tech figures (Pope, Greta, Hanks, Hetfield) each have virtually none (1 each). In policy/legal domain, Obama again leads with a 9 (experience in governance of tech policy), Trump 6, Gates 7 (he often advises on tech policy, antitrust, etc.), the AI expert 6 (some have policy advisory experience), and others low (Pope 2, Greta/Hanks/Hetfield 1 each). For ethics domain merits, Pope Francis excels (10) – he has spoken about ethics of technology and prioritizes moral considerations, thus is highly attuned to ethical discourse. The AI expert and Gates both have solid ethics awareness (7 each), given many AI researchers and tech leaders are actively engaged in AI ethics and Gates has warned of AI risks (and strives for responsible innovation). Obama has a good ethical understanding (7) informed by prioritizing civil liberties and human values in governance. Greta, Hanks, Hetfield have low-to-moderate “AI ethics” familiarity (3, 3, 2 respectively – they have general moral perspectives but no specific AI focus). Ethics multipliers remain consistent (Pope 1.20, Gates/Greta 1.10, Obama/Hanks 1.05, AI expert 1.00, Trump 0.90, Hetfield 0.95). | Participant | Computer Science (AI Tech) | Public Policy / Law | Ethics (domain) | Ethics Multiplier | Total Weight | | ----- | ----- | ----- | ----- | ----- | ----- | | Bill Gates | 9 | 7 | 7 | 1.10 | 8.58 | | Nobel Laureate (AI Research) | 10 | 6 | 7 | 1.00 | 7.90 | | Barack Obama | 3 | 9 | 7 | 1.05 | 6.30 | | Pope Francis | 1 | 2 | 10 | 1.20 | 4.80 | | Donald Trump | 2 | 6 | 3 | 0.90 | 3.15 | | Greta Thunberg | 1 | 1 | 3 | 1.10 | 1.76 | | Tom Hanks | 1 | 1 | 3 | 1.05 | 1.68 | | James Hetfield | 1 | 1 | 2 | 0.95 | 1.23 | *Table: Merit and weight details for the AI Regulation consultation.* Here **Bill Gates** emerges with the highest weight (\~8.58), slightly surpassing the AI research luminary. Gates’s breadth of technical knowledge and policy engagement, combined with an elevated ethics multiplier, gives him a formidable edge. The top AI researcher holds \~7.9 weight, primarily from unrivaled technical expertise – a clear demonstration that subject-matter experts heavily influence outcomes. Obama ranks third (\~6.3), largely on the strength of policy expertise and a solid ethical reputation, despite limited tech knowledge. Pope Francis, lacking tech or policy credentials, still reaches a non-trivial weight (\~4.8) solely due to his moral authority (ethics merit 10 and multiplier 1.2) emphasizing how Smart Vote does credit ethical leadership even in tech debates. Trump’s weight (\~3.15) remains low given his poor tech understanding and lower ethical standing. The remaining activists/celebrities (Greta, Hanks, Hetfield) each have negligible say (weights under 2\) – their absence of AI or policy expertise renders their influence minimal, as expected. *Figure: Weighted vote distribution for the AI Regulation consultation.* The chart shows **Bill Gates** (rightmost bar) narrowly ahead of the **AI Expert** in voting weight, illustrating that a combination of strong domain knowledge across tech and policy plus high ethical regard can outweigh even a top specialist. **Barack Obama** (third bar) also maintains significant influence through policy expertise. The **Pope** (mid-level bar) holds notable sway purely from ethical weight, unlike the **activist/celebrity group** (cluster of shortest bars on the left) who contribute almost no weight in this technically complex and ethically charged discussion. This distribution underscores that Smart Vote weights expertise in AI and ethics heavily, aligning influence with those most equipped to understand and morally navigate AI’s challenges. ## **Consultation 4: International Aid Allocation** **Issue:** A consultation on **International Aid** – how to prioritize and distribute foreign aid or humanitarian relief funding. **Relevant Domains & Weights:** We consider **Development Economics** (40%), **International Relations / Policy** (30%), and **Social/Humanitarian Studies** (30%) as key domains. Knowledge of development economics and finance is paramount (40%) for assessing aid effectiveness and budgeting. Insight into international relations and public policy (30%) is needed to navigate diplomatic, geopolitical and governance aspects of aid programs. Lastly, understanding social/humanitarian contexts (30%) – drawn from sociology, cultural studies, or humanitarian field experience – is equally important to ensure aid addresses on-the-ground needs. (These correspond to UNESCO fields like *Economics*, *Political science/International relations*, and *Sociology and cultural studies* respectively.) **Participants’ Merit Profiles:** The Nobel-level expert here is a **Nobel Laureate in Economics (Development Economics)** – e.g. someone like Amartya Sen or Esther Duflo – who scores 10 in development economics, 6 in international policy (some engage in global policy advisory), and 8 in social/humanitarian studies (development economists often have field experience and social insight). Bill Gates also scores very high: 8 in development economics (through managing large-scale development projects via the Gates Foundation), 7 in international policy (collaborating with governments and global institutions), and 9 in humanitarian understanding (extensive on-ground public health project knowledge). Obama has a strong profile too: 6 in development economics (familiar with economic aid policy), 9 in international relations (deep foreign policy experience), 7 in social/humanitarian (promoter of global development initiatives). Pope Francis contributes a 10 in social/humanitarian domain (his deep involvement in humanitarian causes and advocacy for the poor), but only 2 in economics and 4 in international policy. Trump’s merits: 7 in economics (experience with international trade/business, though not specifically development economics), 5 in international relations (some foreign affairs exposure), and only 3 in humanitarian (low emphasis on aid during his tenure). Greta Thunberg scores 5 social (due to climate justice activism overlapping with humanitarian issues), 4 in policy (interacting with international climate forums), but only 2 in economics. Tom Hanks and James Hetfield have minimal direct expertise: we give each 2 in economics (they manage charitable foundations at smaller scale), 1 in international policy, 3 in social (both have partaken in some charitable causes – Hanks supports veterans and disaster relief, Metallica’s foundation supports workforce education – but they are not experts). Ethics multipliers: Pope 1.20, Gates 1.10, Greta 1.10, Obama/Hanks 1.05, Nobel economist 1.00 baseline, Trump 0.90, Hetfield 0.95. | Participant | Development Economics | International Relations (Policy) | Social/Humanitarian Studies | Ethics Multiplier | Total Weight | | ----- | ----- | ----- | ----- | ----- | ----- | | Bill Gates | 8 | 7 | 9 | 1.10 | 8.80 | | Nobel Laureate (Development Econ) | 10 | 6 | 8 | 1.00 | 8.20 | | Barack Obama | 6 | 9 | 7 | 1.05 | 7.56 | | Pope Francis | 2 | 4 | 10 | 1.20 | 6.00 | | Donald Trump | 7 | 5 | 3 | 0.90 | 4.68 | | Greta Thunberg | 2 | 4 | 5 | 1.10 | 3.85 | | Tom Hanks | 2 | 1 | 3 | 1.05 | 2.10 | | James Hetfield | 2 | 1 | 3 | 0.95 | 1.90 | *Table: Merit and weight details for the International Aid consultation.* **Bill Gates** edges out the Nobel laureate with the top weight (\~8.8 vs 8.2). His extensive practical experience in funding global aid projects, combined with a boost from his philanthropy-driven ethics, gives him a slight lead over the laureate who is academically top-notch (perfect 10 in economics) but has a neutral ethics score. Obama scores \~7.56, leveraging his international diplomacy expertise and solid ethical standing to remain influential. Pope Francis, despite low technical merits, reaches a weight of 6.0 – significantly higher than in prior scenarios – because the *Social/Humanitarian* domain (where he scores 10\) is heavily weighted here (30%), and his ethics multiplier amplifies that further. This indicates the system recognizing moral and experiential knowledge in humanitarian contexts as true expertise. Trump’s weight (\~4.68) is higher here than in other scenarios (his business/economics experience partly translates to development economics merit), but his influence is still markedly below the top experts due to lower humanitarian understanding and ethics factor. Greta Thunberg (\~3.85) has some voice primarily on the strength of her social advocacy credibility (and a decent ethics multiplier), but is limited by low economics/policy knowledge. Hanks and Hetfield remain low (around 2 or below), reflecting very limited domain expertise. Overall, those who combine economic savvy, policy experience, and humanitarian insight (and good ethical reputations) drive the weighted outcome. *Figure: Weighted vote distribution for the International Aid consultation.* The chart illustrates **Bill Gates** (rightmost bar) as the most influential voter, closely followed by the **Development Economics Nobel Laureate**, reflecting their exceptional expertise in aid-related economics and policy design. **Barack Obama** and **Pope Francis** (mid-range bars) also hold considerable weight – Obama due to governance and international relations skills, and Pope Francis due to his humanitarian leadership and high ethical standing (despite limited economic expertise). The **remaining participants** (left cluster of bars) have progressively smaller weights; while **Donald Trump** has some influence (owing to business/economics experience), activists and celebrities like **Greta Thunberg, Tom Hanks, and James Hetfield** contribute only marginally to the decision. This distribution underscores Smart Vote’s ability to elevate those with both technical competence and ethical commitment in the aid arena, while sidelining those without relevant insight into global development challenges. ## **Consultation 5: Arts Funding Initiative** **Issue:** A consultation on **Arts Funding** – determining support for arts and culture (e.g. public funding for museums, music programs, film grants). **Relevant Domains & Weights:** We use **Arts & Culture** (50%), **Economics/Management** (30%), and **Social Impact (Cultural Studies)** (20%) as the domains. Expertise in the arts (50%) – knowledge of artistic creation, cultural heritage, the needs of artists – is paramount for deciding how funds should be allocated effectively. Financial and management savvy (30%) is also crucial since it deals with budgeting and administering funds (related to business/administration in ISCED). Finally, understanding the social and cultural impact of the arts (20%) is important for justifying funding (aligns with sociology/cultural studies, i.e. how art benefits communities, education, well-being). **Participants’ Merit Profiles:** This scenario highlights our two artists: Tom Hanks and James Hetfield. Both have **Arts & Culture** merits near the top. Hanks, an award-winning actor/producer, scores a full 10 in arts domain, while Hetfield, a legendary musician, scores 9 – reflecting their mastery and industry experience in film and music (performing arts are recognized as a field under ISCED code 0215). The Nobel figure here is a **Nobel Laureate in Literature**, who also scores 10 in arts & culture (as a writer of the highest acclaim). Others have minimal arts domain knowledge: Obama and Trump each get 2 (they appreciate arts but have no professional background; Trump had some involvement in entertainment ventures but not as an artist), Gates 2 (known more for STEM, though he has funded some cultural initiatives), Greta 1 (no notable involvement in arts). In **Economics/Management**, ironically Bill Gates leads with 9 (decades of running a large organization, albeit not arts-specific, but skills are transferable to managing funds), Trump has 8 (experience in business, though not arts-focused, he did run the Miss Universe pageant and a reality TV show), Hanks 7 (experience producing films and managing film budgets), Hetfield 6 (managed a band’s business for years), Obama 6 (oversaw budgets including cultural programs), Nobel laureate (literature) 3 (not typically involved in finance), Pope Francis 2 (limited to managing church finances for the Vatican, not directly arts budgets), Greta 2 (no relevant financial management experience). For **Social Impact/Cultural Studies**, the Nobel laureate writer scores high (9) – literati often reflect deeply on culture and society. Hanks gets 8 (he’s observed to champion the cultural value of the arts and participates in related philanthropy), Hetfield 7 (witnessing music’s impact on global culture and engaging in charity events). Pope Francis scores 6 here – he appreciates how art can serve society and the church has a history of supporting arts for community, though it’s not his specialty. Obama scores 5 (supports arts education and cultural programs as a means of social improvement), Gates 4 (focuses more on scientific education but acknowledges cultural factors), Greta 3 (her advocacy is climate-focused, but she uses artful communication occasionally). Trump scores only 1 in social impact – his approach to arts has been more utilitarian, with attempts to cut arts funding, suggesting little concern for its societal role. Ethics multipliers: unchanged (Pope 1.20, Gates/Greta 1.10, Obama/Hanks 1.05, Nobel laureate 1.00, Trump 0.90, Hetfield 0.95). | Participant | Arts & Culture | Economics/Management | Social Impact (Cultural Studies) | Ethics Multiplier | Total Weight | | ----- | ----- | ----- | ----- | ----- | ----- | | Tom Hanks | 10 | 7 | 8 | 1.05 | 9.13 | | Nobel Laureate (Literature) | 10 | 3 | 9 | 1.00 | 7.70 | | James Hetfield | 9 | 6 | 7 | 0.95 | 7.31 | | Bill Gates | 2 | 9 | 4 | 1.10 | 4.95 | | Barack Obama | 2 | 6 | 5 | 1.05 | 3.99 | | Pope Francis | 3 | 2 | 6 | 1.20 | 3.96 | | Donald Trump | 2 | 8 | 1 | 0.90 | 3.24 | | Greta Thunberg | 1 | 2 | 3 | 1.10 | 1.87 | *Table: Merit and weight summary for the Arts Funding consultation.* Here the **artists themselves** dominate: Tom Hanks achieves the highest weight (\~9.13), reflecting his unparalleled artistic expertise (10 in arts) combined with solid business sense and a positive ethical image. The Nobel literature laureate and James Hetfield come next at 7.7 and 7.3 respectively – despite Hetfield’s slightly lower raw merits, the Nobel laureate’s neutral ethics vs. Hetfield’s slight ethics penalty results in a small gap between them. These three far outstrip the others, indicating that in an arts-focused vote, actual creators/arts experts carry the most influence (as one would hope). Bill Gates (\~4.95) leads the second tier, mainly because his superior management skills (9) grant him weight in the funding aspect, even though his arts knowledge is minimal – an interesting case of strong cross-domain merit (finance) still contributing significantly. Obama, Pope Francis, and Trump all cluster around 3.2–3.99 weight. Obama’s moderate influence comes from leadership and a bit of cultural policy support; Pope Francis, notably, almost ties Obama (3.96 vs 3.99) – his high ethics and genuine appreciation for the social value of art elevate him, despite lacking technical arts or finance expertise. Trump, while proficient in business, is held back by low regard for arts’ social value and a poor ethics score, resulting in only \~3.24 weight. Greta Thunberg (1.87) has virtually no impact here – as expected, since climate activism doesn’t translate into arts funding expertise. This scenario vividly demonstrates Smart Vote’s *domain alignment*: individuals renowned in arts and culture are given a far louder voice on arts policy than those who are not – a reversal of typical popularity-based influence. Merit differentiation is clear: even among generally influential figures, those with directly relevant accomplishments (Oscars, Grammys, Nobel Prize in literature) overshadow those without. The ethics modulation also plays a subtle role – note that if Hetfield had an ethics multiplier of 1.0 equal to the Nobel laureate’s, their weights would be equal; his slightly lower ethics (0.95) means the laureate inches ahead, highlighting that character and public service factor into one’s final influence. *(No figure embedded for the arts scenario to avoid repetition; the distribution described above shows the first three bars (Hanks, Laureate, Hetfield) towering over the rest.)* ## **Conclusion** Across these simulations, we see the Smart Vote system functioning as intended: **domain alignment** ensures that each consultation is primarily influenced by those with expertise in the relevant fields (scientists on science questions, artists on arts funding, etc.), while **merit differentiation** within those domains further ranks individuals by their achievements and knowledge. The inclusion of an **ethics multiplier** means that individuals who have demonstrated social responsibility or integrity can slightly augment their influence, whereas those with ethical shortcomings lose some weight – this is evident in cases like Pope Francis punching above his raw merit in secular topics, or Donald Trump’s weights consistently lagging what his domain knowledge alone might have yielded. Crucially, we avoid comparing these weighted outcomes to hypothetical raw-vote outcomes, and instead focus on the internal logic of the weighted system. In each scenario, the total “voting weight” is distributed in a way that **elevates domain experts and reputable contributors**. For example, in climate policy, climate scientists and experienced policymakers dominated; in vaccine mandate decisions, medical and health policy experts led; in AI regulation, technologists and ethicists held sway; in international aid, development economists and humanitarian leaders prevailed; and in arts funding, artists and cultural figures had the loudest voices. This illustrates how Smart Vote’s formula – weighting votes by expertise across pertinent UNESCO-defined domains and by ethical standing – reallocates decision power toward those most aligned with the issue at hand. The result is a more nuanced, knowledge-centered form of democracy where the quality of contributions matters as much as quantity, aiming to produce well-informed decisions without silencing ethical considerations. Each consultation above demonstrates this balance, with clear logic as to why certain individuals carried more weight than others, strictly **based on their merits and ethics relevant to the consultation’s subject matter**, rather than popularity or raw political power. The Smart Vote simulations thus showcase an approach that *could* lead to more competent and principled collective decisions on complex public issues. Voici des représentations visuelles « ASCII » de la répartition des poids de vote pour chaque consultation : --- ### **1\. Climate Policy (Dom. Env. 50% / Pol. Sci. 30% / Econ. 20%)** Nobel Laureate ██████████████ 14 (7.10) Barack Obama █████████████ 13 (6.72) Bill Gates ████████████ 12 (5.83) Greta Thunberg ███████████ 11 (5.39) Donald Trump ████████ 8 (3.78) Pope Francis ██████ 6 (2.76) Tom Hanks ███ 3 (1.26) James Hetfield ██ 2 (0.95) --- ### **2\. Vaccine Mandates (Health 50% / Pol. Sci. 30% / Ethics 20%)** Nobel Laureate ████████████████ 16 (7.90) Bill Gates █████████████ 14 (6.82) Barack Obama ███████████ 12 (6.20) Pope Francis ███████ 7 (3.72) Donald Trump ██████ 6 (2.88) Tom Hanks █████ 5 (2.52) Greta Thunberg █████ 5 (2.31) James Hetfield ██ 2 (1.14) --- ### **3\. AI Regulation (AI Tech 40% / Pol. Sci. 30% / Ethics 30%)** Bill Gates █████████████████ 17 (8.58) Nobel Laureate ████████████████ 16 (7.90) Barack Obama █████████████ 13 (6.30) Pope Francis ██████████ 10 (4.80) Donald Trump ██████ 6 (3.15) Greta Thunberg ████ 4 (1.76) Tom Hanks ███ 3 (1.68) James Hetfield ██ 2 (1.23) --- ### **4\. International Aid (Dev. Econ. 40% / Int’l Policy 30% / Humanitarian 30%)** Bill Gates ██████████████████ 18 (8.80) Nobel Laureate ████████████████ 16 (8.20) Barack Obama ███████████████ 15 (7.56) Pope Francis ████████████ 12 (6.00) Donald Trump ██████████ 9 (4.68) Greta Thunberg ████████ 8 (3.85) Tom Hanks ████ 4 (2.10) James Hetfield ████ 4 (1.90) --- ### **5\. Arts Funding (Arts 50% / Econ. Mgmt 30% / Social Impact 20%)** Tom Hanks ██████████████████ 18 (9.13) Nobel Laureate ███████████████ 15 (7.70) James Hetfield ███████████████ 15 (7.31) Bill Gates ███████████ 10 (4.95) Barack Obama ██████████ 8 (3.99) Pope Francis ██████████ 8 (3.96) Donald Trump ██████ 6 (3.24) Greta Thunberg ████ 4 (1.87) --- Chaque barre est proportionnelle au **poids de vote** calculé : on multiplie la somme pondérée des compétences par le coefficient éthique, sans oublier la voix de base (1). Vous pouvez ainsi voir d’un coup d’œil qui porte le plus d’influence selon la question et les domaines d’expertise requis. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-empower-ux-naming-guidelines.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 24b01e6ba4a2cfbd9133e516a4c1e580993cd838ff84ee0140b944e18236f1a7 CONTENT_BYTES: 3954 ================================================================================================ Unifying everything under Smart Vote and dropping the word “Like” is consistent with both your internal docs and the wiki. On the wiki and Smart Vote pages, the actions are always framed as **voting**, **CSR voting**, **user ratings**, and “empowering … consumer choices / ethical consumerism,” not generic “likes.” ([Global Ethical Debates][1]) Given that, using **Empower** as the unified verb fits the existing language and your “shared power” philosophy very well. ### 1. Canonical naming If you want one term everywhere, I would recommend: * Primary verb (button): **Empower** * Past tense: **Empowered** * Concept: **Empower vote** (internally) / **Empowerment** (in docs/UX copy if you need a noun) Examples: * Button: `Empower` * State: `Empowered` (with filled icon) * Tooltip: `Empower this to increase its influence in Smart Vote.` * Analytics/admin copy: `Total Empower votes`, `Empowerment score` You can keep “Smart Vote” as the underlying system name; “Empower” is the user-facing action. ### 2. Mapping “Empower” across contexts Because everything goes through Smart Vote, you can use the same core verb and just adjust the surrounding copy slightly: 1. **Content (posts, lessons, debates, comments)** * Button: **Empower** * Empty state hint: “Empower thoughtful contributions so they carry more weight in decisions.” * Under the hood: Smart Vote approval on `target_type = content`. 2. **Projects / proposals (keenKonnect, governance items, CSR topics)** * Button: **Empower this project** * List chip: `32 Empower votes` * This matches the CSR / ethical consumerism framing where public voting “empowers users to favor brands and practices aligned with their values.” ([Global Ethical Debates][1]) 3. **People / skills / expertise** * Button (on profile or skill): **Empower this expertise** * Tooltip: “Empower this to increase their influence in this domain.” * This aligns with the weighted voting hierarchy (Titans/Olympians/Heroes) where peer recognition and ethical behavior affect vote weight. ([Weighted Voting][2]) So the **mental model** is always: *“When I click Empower, I’m giving power and visibility to this thing/person/idea in Smart Vote”*. ### 3. Icon and interaction pattern To keep it simple but distinct from “generic likes”: * Icon: You can still use a **thumbs-up** or a more thematic icon (spark, rising bar, small torch). The important part is: * Outline when not used * Filled when user has Empowered * Interaction: * Single tap/click: cast Smart Vote (“Empower”) * Second tap/click: remove Smart Vote (“Un-empower”) using the vote-toggle pattern described for your voting mechanisms. ([King Klown Wiki][3]) Minimal UI examples: * Inline: * `[⬆️ Empower] 24` (before click) * `[⬆️ Empowered] 25` (after click) * Card: * `Empower` button at bottom with counter to the right. ### 4. Copy rules to keep it coherent To really standardize: * Never use “Like” in Konnaxion or EkoH UI. * Use “Empower” everywhere a Smart Vote is triggered. * Use short contextual phrases around it, not alternative verbs: * Good: “Empower this debate”, “Empower this project”, “Empower this skill”. * Avoid: “Support”, “Vouch”, “Endorse” as primary button text if Smart Vote is involved; you can still use them in explanatory paragraphs (“empower and support ethical companies”) but not as the action label. If you want, next step I can outline exact string names (EN keys) and states for the components so you can drop them straight into your design system. [1]: https://global-ethical-debates-57d8pci.gamma.site/ "Global Ethical Debates: Fostering Responsibility and Understanding" [2]: https://weighted-voting-qj6ov3b.gamma.site/ "Weighted Voting: Balancing Expertise and Ethics" [3]: https://kingklown.wiki/ "Welcome to the Knowledge Platform Hub" ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/EkoH Smart Vote/smart-vote-system-in-konnaxion-technical-specification.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: dfaedc9eeb51777217b3d37c7c61cf9280e35f1e26bb165d4c78767b744e612c CONTENT_BYTES: 6707 ================================================================================================ # Smart Vote in Konnaxion — Technical Specification ## Status and authority This specification follows the current ethiKos Kintsugi boundary: > **ethiKos preserves canonical source facts. Smart Vote publishes declared, reproducible readings. EkoH supplies contextual profile data.** Smart Vote must not mutate source ballots, source stances, arguments, or canonical baseline results. ## 1. Ownership boundaries | Concern | Canonical owner | | --- | --- | | Topic / deliberation facts | ethiKos | | Public ballot / decision facts | Konsultations / ethiKos decision layer | | Domain expertise profile | EkoH | | Reliability / ethics context | EkoH | | Consultation domain relevance | Smart Vote reading context / governed consultation configuration | | Derived weighted result | Smart Vote | | Reading presentation | ethiKos Decide / Insights / Pulse | EkoH is not a voting engine. Smart Vote is not the owner of the underlying civic fact. ## 2. Source facts and baseline A source ballot records what the participant actually submitted. For an ethiKos stance this may be a value in `-3..+3`; for other ballot modalities it may be approval, ranking, rating, or allocation data. The source event must remain unchanged by later interpretation. The baseline is computed from those source facts under the declared baseline rule, normally preserving one-person-one-vote political equality where applicable. ## 3. EkoH expertise vector Each participant may have an EkoH expertise vector: ```text S(u) = { domain_id -> normalized_score } ``` Current normalized contract: ```text 0.0 <= S(u,d) <= 1.0 ``` Scores are domain-specific and should be evidence-backed. ## 4. Consultation relevance vector Each Smart Vote reading that uses expertise declares a relevance vector: ```text R(c) = { domain_id -> relevance_weight } ``` Requirements: ```text 0.0 <= R(c,d) <= 1.0 Σ R(c,d) = 1.0 ``` The domain mix is part of the lens declaration and must be reviewable. Expertise in domains with zero relevance contributes no expertise bonus. ## 4.1 Canonical source binding Smart Vote must not infer a source object by title. The current mapping model is: ```text SourceConsultationBinding source_type source_id source_key consultation -> Smart Vote Consultation metadata_json ``` For ethiKos, `source_type = "ethikos_topic"` and `source_id` is the canonical `EthikosTopic` primary key represented as text. Demo schema v3 imports `topic_relevance`; the importer creates the binding and persists the vector as `ConsultationRelevance` rows. This keeps ownership explicit: ```text EthikosTopic + EthikosStance = source facts SourceConsultationBinding = cross-subsystem reference ConsultationRelevance = Smart Vote lens context Smart Vote reading = derived output ``` ## 5. Contextual expertise alignment The expertise alignment for user `u` in consultation `c` is: ```text A(u,c) = Σd R(c,d) × S(u,d) ``` With normalized inputs, `A(u,c)` is normally in `0..1`. This number means **fit between the participant's demonstrated expertise and the declared knowledge needs of this question**. It does not mean the participant is generally more important. ## 6. Advisory reading weight The current advisory formula is: ```text bonus(u,c) = min(A(u,c), expertise_bonus_cap) weight(u,c) = 1 + bonus(u,c) × ethics_modifier(u) ``` Where: - `1` is the baseline participation entitlement inside this reading; - `A(u,c)` is contextual expertise alignment; - `expertise_bonus_cap` limits concentration; - `ethics_modifier(u)` is an optional governed EkoH reliability modifier. The neutral reliability modifier is `1.0`. This formula produces a **reading weight**, not a replacement ballot. ## 7. Derived reading For a numeric ballot value `v(u,c)`, a simple weighted reading can use: ```text weighted_contribution(u,c) = v(u,c) × weight(u,c) ``` Aggregation depends on ballot modality. Approval, rating, ranking, preferential, and budget-allocation ballots require modality-specific aggregation rules. The output must be labeled as a derived Smart Vote reading. ## 8. Reading contract A published reading should contain enough metadata to be reproduced: ```json { "target_type": "ethikos_topic", "target_id": 123, "baseline": { "reading_key": "baseline", "lens_hash": "sha256:...", "snapshot_ref": null, "computed_at": "...", "results_payload": {} }, "readings": [ { "reading_key": "ekoh_weighted_v1", "lens_hash": "sha256:...", "snapshot_ref": "ekoh_snapshot:...", "computed_at": "...", "results_payload": {} } ] } ``` At minimum a derived reading should identify: - `reading_key`; - `lens_hash` or equivalent immutable lens identity; - `snapshot_ref` for EkoH inputs when applicable; - `computed_at`; - target topic/consultation; - result payload; - method/version metadata. ## 9. Baseline and reading display User interfaces must show the baseline separately from any derived reading. Correct: ```text Public baseline +0.8 Relevant-expertise lens +1.4 ``` Incorrect: ```text Final truth +1.4 ``` A large divergence between readings is itself useful information and should not be hidden. ## 10. Privacy A reading may use authorized EkoH information without publishing individual private scores. Reading publication and EkoH profile visibility are separate governance decisions. The public result payload should expose only the detail permitted by the applicable privacy and governance policy. ## 11. Demo import contract For current demo schema v3: - source consultation votes import `raw_value` only; - `weighted_value` is forbidden as a source field; - EkoH profiles may be imported as contextual demo data; - consultation relevance vectors may be declared and validated; - Smart Vote readings must be computed from source facts rather than supplied as canonical JSON facts. Legacy schema v1/v2 may retain `weighted_value` only for backward compatibility. ## 12. Current implementation state The current Smart Vote backend includes a ballot-casting endpoint and the core EkoH weight calculation service. A canonical published-reading API matching the contract above is not yet implemented in the current code snapshot. Until that endpoint exists, frontend pages must not fabricate a Smart Vote reading from the baseline or derive a global user voting weight locally. ## 13. Invariants - Source ballot ≠ weighted reading. - Baseline ≠ expert reading. - EkoH ≠ Smart Vote. - Expertise ≠ authority. - Majority ≠ truth. - Expert consensus ≠ democratic mandate. - One lens ≠ reality. - Smart Vote must not mutate source facts. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos-kintsugi-upgrade-plan-v1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 7a1638851b7c66cb13bbe1aba969c8b6977d60fe81386832bd09c112b1445d5a CONTENT_BYTES: 15374 ================================================================================================ # ethiKos — Unified Civic Deliberation & Decision Engine **A unified civic deliberation, drafting, and decision pipeline** **#kintsugi edition — harmonizing the best civic tech patterns into one orchestrated flow** **Author:** Réjean McCormick **Status:** Merged master draft **Purpose:** combine the strongest strategic framing, architecture logic, and staged operating model for ethiKos into one canonical public-facing master document. --- ## 1) Executive summary This update transforms **Konnaxion’s ethiKos** from a structured debate module into a **full-spectrum civic intelligence system**: one that combines **crowd sentiment mapping, structured reasoning, collaborative drafting, formal decision-making, and accountability workflows**. Instead of merging outside civic platforms directly into the core stack, Konnaxion adopts a **Mimic vs Annex** strategy: - **Mimic** when a platform’s ideas are strong but the codebase is too heavy, copyleft, architecturally incompatible, or likely to dominate the product. - **Annex** when a feature is modular, permissively licensed, and can be isolated safely as a sidecar. The result is not a clone of other civic systems. It is a coherent civic engine that **orchestrates the best ideas in computational democracy without inheriting unnecessary technical debt, governance confusion, or license risk**. --- ## 2) Why this upgrade exists Online debate fails for structural reasons: - chronological feeds reward repetition, outrage, and dominance, - threads collapse into identity conflict instead of converging on decisions, - “consensus” becomes a popularity contest instead of a clarity mechanism, - even when a vote happens, follow-through often disappears. **ethiKos vNext** restructures participation into distinct stages, each optimized for a different job: 1. **Discovery** — surface the real landscape of opinions 2. **Deliberation** — capture the “why,” not the noise 3. **Drafting** — convert agreement into text people can sign 4. **Decision** — choose an outcome using a clear protocol 5. **Accountability** — track implementation and keep receipts This is the **#kintsugi approach**: consolidate what works, harmonize it, and orchestrate it into one coherent civic engine. --- ## 3) Strategic principle: Mimic vs Annex ### Mimic (native re-implementation) Use when: - the source license is **AGPL/GPL**, - the stack is incompatible or too invasive, - the platform is effectively a full civic operating system, - Konnaxion needs sovereignty, long-term stability, and a unified UX. ### Annex (sidecar / optional integration) Use when: - the source license is **MIT / BSD / Apache**, - the feature is modular and isolatable, - integration can add speed without corrupting the core architecture, - the component can remain replaceable. This keeps Konnaxion architecturally coherent while still learning from proven civic technology patterns. --- ## 4) Core architecture principle: many inputs, one common reading layer ethiKos introduces multiple ways to participate — tri-votes, reasons, proposals, drafting, decision protocols — without creating separate incompatible decision systems for each. Instead, the architecture converges into a shared aggregation and publication layer built around **Smart Vote**. That means civic input can be: - compared fairly, - audited consistently, - analyzed through multiple legitimate lenses, - displayed in ways that resist manipulation. This is not about claiming a single “correct” outcome. It is about supporting **multiple legitimate readings of the same civic input**, clearly declared and reproducible. --- ## 5) Smart Vote, explained simply Smart Vote is not a power-grab mechanism. It is a **reading and aggregation layer** that can be turned on or off depending on the decision context. ### Smart Vote stores votes in a standardized way Each vote or recorded signal can be represented as: - **who** participated, - **what object** they acted on (topic, statement, reason, proposal, etc.), - the **raw value** of that action, - optional **metadata** (region, cohort, language, role, etc.), - optional **weighting inputs** for declared alternative readings. ### Smart Vote enables multiple lenses on the same result #### Lens A — 1 person = 1 vote This is the baseline democratic reading: - everyone counts equally, - it is simple, understandable, and universally legible, - it remains available as the canonical baseline. Best suited for: - broad civic consultations, - public referendums, - high-trust situations, - contexts where equality of influence is the primary legitimacy principle. #### Lens B — quality-weighted reading This is an optional clarity layer: - participation can be weighted using declared expertise, trusted participation history, or other governed criteria, - not to silence anyone, but to increase signal resolution where competence matters. Best suited for: - scientific or medical domains, - high-risk decisions, - technical governance, - professional standards and safety questions. **Important:** ethiKos can show both readings side by side. The baseline remains visible; no single lens is forced. --- ## 6) Cohort filters: the library of readings ethiKos results should support filters that help communities understand **who agrees with what** without fragmenting the process into separate debates. Examples: - region / jurisdiction, - language, - age bands where appropriate, - role (citizen, stakeholder, organization member), - field of expertise, - level of expertise, - verified cohorts. This makes it possible to ask: - What does the overall crowd think? - What do local residents think? - What do professionals think? - Where do experts disagree with the public? - Where do groups converge? This is how ethiKos avoids both extremes: - purely popular outcomes with low competence, - purely technocratic outcomes with low legitimacy. --- ## 7) Source platforms and how ethiKos uses them ### A. Polis — consensus mapping **Status:** MIMICKED **Patterns adopted:** - Agree / Disagree / Pass interaction, - opinion-space mapping, - cluster detection, - bridge-statement discovery. **What Konnaxion adds:** - Smart Vote readings, - cohort filters, - dual view of crowd topology and credibility topology, - auditable derivation of outcomes. **Result:** ethiKos gains computational consensus discovery, not just comment threads. ### B. Loomio — decision protocols **Status:** MIMICKED **Patterns adopted:** - proposal lifecycle, - time-boxed decisions, - consent / objection / approval flows, - clear outcome publishing. **What Konnaxion adds:** - Smart Vote publication layer, - clearer publication of alternative readings, - stronger transition from debate to decision. **Result:** ethiKos gains decision mechanics instead of endless discussion. ### C. Decidim — civic process architecture **Status:** MIMICKED **Patterns adopted:** - participation workflows, - consultation → drafting → voting → execution pipelines, - public accountability timelines. **What Konnaxion adds:** - integration with keenKonnect execution, - governance dashboards and insight surfaces. **Result:** ethiKos gains legitimacy scaffolding for real process follow-through. ### D. CONSUL Democracy — petitions and budgeting **Status:** MIMICKED **Patterns adopted:** - petition thresholds, - proposal gating, - participatory budgeting mechanics. **What Konnaxion adds:** - Smart Vote readings, - cohort filters, - optional expertise-aware interpretations. **Result:** ethiKos gains scalable civic legitimacy mechanics. ### E. Consider.it — deliberation compression **Status:** MIMICKED **Patterns adopted:** - structured pro/con reasons, - summarized rationale visualization, - reflection-first interaction patterns. **What Konnaxion adds:** - stronger credibility interpretation, - anti-troll interaction constraints, - compatibility with structured decision outputs. **Result:** ethiKos gains high-signal reasoning instead of flamewars. ### F. Your Priorities — idea intake and ranking **Status:** ANNEX (optional) **Patterns adopted or integrated:** - lightweight idea submission, - community prioritization, - early-stage filtering. **Result:** a fast ideation intake layer. ### G. All Our Ideas — pairwise voting **Status:** ANNEX or MIMIC **Patterns adopted:** - pairwise idea ranking, - popularity-resistant prioritization. **Result:** better idea filtering before full deliberation. ### H. LiquidFeedback — delegation and voting theory **Status:** MIMICKED **Patterns adopted:** - delegated voting logic, - liquid democracy models, - vote-flow mathematics. **What Konnaxion adds:** - domain-specific delegation, - governance-aware interpretation layers. **Result:** scalable governance mechanics for larger populations. ### I. DemocracyOS — policy debate UX **Status:** MIMICKED **Patterns adopted:** - proposal-centric discussion pages, - clause-level policy review. **Result:** ethiKos gains legislative-grade policy review patterns. ### J. Citizen OS — collaborative drafting **Status:** MIMICKED **Patterns adopted:** - co-authoring proposals, - structured discussion around text, - draft versioning. **Result:** a smooth transition from consensus to final policy text. ### K. OpenSlides — assembly and parliamentary mode **Status:** ANNEX (optional) **Patterns adopted or integrated:** - motions, - elections, - formal meeting governance. **Result:** optional institutional “Parliament Mode.” --- ## 8) The unified ethiKos pipeline ### Stage 0 — Idea intake and early prioritization **Job:** gather many ideas quickly without chaos. **What happens:** - people submit ideas or statements, - lightweight prioritization helps shortlist items, - promising inputs move forward to deeper consultation. **Inspired by / optionally integrated from:** - Your Priorities, - All Our Ideas. **Why it matters:** it prevents “10,000 comments = unusable noise.” ### Stage 1 — Consultation and consensus mapping **Job:** reveal the real opinion landscape and detect common ground. **Interaction rules:** - no reply chains, - no thread combat, - simple Agree / Disagree / Pass input where appropriate. **What the engine produces:** - opinion maps, - participant clusters, - bridge statements, - divisive statements. **Inspired by:** Polis. ### Stage 2 — Deliberation (reasons over reactions) **Job:** capture the “why” in structured form. **Mechanics:** - reasons are stored as pro/con points, - participants assess reasons for strength and clarity, - debate becomes legible rather than personal. **Outputs:** - strongest reasons for agreement, - strongest reasons for disagreement, - summaries of where the tension lives. **Inspired by:** Consider.it and Kialo-style argument mapping. ### Stage 3 — Drafting (turn consensus into text) **Job:** convert agreement into a proposal people can adopt. **Mechanics:** - collaborative drafting, - amendment flows, - version history, - visible evolution from idea to final text. **Inspired by:** Citizen OS drafting patterns. ### Stage 4 — Decision (protocols and outcomes) **Job:** end debate responsibly and publish a clear result. **Mechanics:** - proposal cards with time windows, - selectable decision protocols, - publishable outcomes with dissent visibility, - baseline reading plus optional declared readings. **Inspired by:** Loomio, with optional advanced concepts from LiquidFeedback. ### Stage 5 — Process and accountability **Job:** prevent participation from becoming performative. **Mechanics:** - process phases from consultation to implementation, - transparency pages with milestones and updates, - public tracking of what changed, shipped, or stalled. **Inspired by:** Decidim and CONSUL Democracy. ### Optional module — Assembly / Parliament Mode **Job:** support formal institutional meetings. **Optionally integrated from:** OpenSlides. --- ## 9) Mimicked vs integrated: what comes from where ### MIMICKED (native inside ethiKos) - **Polis** — consultation rules, opinion mapping, bridge statements - **Consider.it** — reason capture, deliberation compression - **Citizen OS** — collaborative drafting patterns - **Loomio** — proposals, decision protocols, outcome publishing - **Decidim** — process scaffolding, legitimacy workflows - **CONSUL Democracy** — petition and budgeting mechanics - **LiquidFeedback** — delegation concepts and governance mathematics - **DemocracyOS** — proposal and policy framing UX ### INTEGRATED (optional annex modules) - **All Our Ideas** — pairwise ranking - **Your Priorities** — idea intake and prioritization - **OpenSlides** — assembly mode --- ## 10) Architectural integrity Konnaxion remains: - a coherent core application stack, - operationally sovereign, - analytically auditable, - able to learn from outside platforms without being captured by them. External applications are: - **never merged blindly into the core**, - either mimicked natively or isolated as sidecars, - connected only through controlled interfaces and replaceable boundaries. This preserves long-term product coherence. --- ## 11) Ethical positioning and public credit ethiKos should explicitly credit its inspirations. A clear public statement could be: > ethiKos builds on ideas pioneered by Polis (consensus mapping), Loomio (decision protocols), Decidim and CONSUL (civic workflows), Consider.it (deliberation UX), LiquidFeedback (delegated democracy), and Citizen OS (collaborative drafting). That positions Konnaxion as **an orchestrator of the best democratic innovations, not a clone**. --- ## 12) Outcome: what Konnaxion becomes Konnaxion evolves into: - a **Consensus Engine**, - a **Reasoning Engine**, - a **Drafting Engine**, - a **Decision Engine**, - a **Civic Process Engine**, - and, optionally, a more formal **Governance OS** layer for institutional use. In short: **Konnaxion becomes a full-stack platform for collective intelligence, democratic legitimacy, and real-world decision-making.** --- ## 13) Why publish this before coding Civic software usually fails first at the architecture and legitimacy level, not the UI level. Publishing this merged plan early allows civic builders, researchers, and practitioners to: - challenge missing edge cases, - improve legitimacy safeguards, - suggest interoperability patterns, - identify architectural risks before they harden into design debt. --- ## 14) Credits and inspirations This document draws inspiration from: - Polis, - Consider.it, - Citizen OS, - Loomio, - Decidim, - CONSUL Democracy, - All Our Ideas, - Your Priorities, - OpenSlides, - LiquidFeedback, - Kialo-style argument mapping patterns, - DemocracyOS-style policy review patterns. --- ## 15) Suggested companion document structure This merged master document should sit alongside: - **ethiKos v2 — Boundaries and articulation with Kintsugi elements** for governance boundaries, canonical objects, ownership, and audit contracts, - any later short hub/overview page for lighter public onboarding. That keeps strategy and architecture-legitimacy framing separate from operational contracts. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/00_KINTSUGI_START_HERE.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 1039f75e4838cb5df7c7fbdc9cca3c3cccc7f87d09323d3aafc064b692c30c4f CONTENT_BYTES: 27130 ================================================================================================ # 00 — Kintsugi Start Here **File:** `00_KINTSUGI_START_HERE.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Status:** Canonical entry point **Primary audience:** Réjean McCormick, future AI sessions, maintainers, implementers **Module:** `ethiKos` **Platform:** `Konnaxion` --- ## 1. Purpose This document is the entry point for the complete **ethiKos Kintsugi Upgrade** documentation pack. Its purpose is to prevent scope drift, architecture drift, naming drift, route drift, model drift, and AI-generated inconsistency while preparing the next major ethiKos upgrade. This pack exists because the Kintsugi update is not a small bugfix, not a cosmetic rewrite, and not a direct import of external civic-tech platforms. It is a documentation-first architecture upgrade that turns the existing ethiKos module into a more complete civic deliberation, drafting, decision-formation, and accountability engine. The documentation pack MUST be read and generated before implementation backlog generation. --- ## 2. What Kintsugi means in this upgrade The Kintsugi update is a **partial native mimic** strategy. It means: - keep the existing ethiKos frame; - keep the existing `/ethikos/*` route families; - keep the current backend ownership boundaries; - learn from selected civic-tech systems; - reimplement only selected patterns natively; - avoid full external code merges; - avoid premature annex/sidecar integration; - document contracts first; - inspect code second; - generate implementation backlog only after the docs are stable. Kintsugi does **not** mean merging other civic platforms into Konnaxion. --- ## 3. Canonical one-line definition **ethiKos Kintsugi Upgrade** is a documentation-first, native-mimic upgrade that extends ethiKos into a structured civic deliberation, consultation, drafting, decision, and accountability engine while preserving current routes, backend ownership, and source-of-truth boundaries. --- ## 4. Current stable baseline The following baseline is treated as the current known platform state before the Kintsugi upgrade. ```yaml CURRENT_BASELINE: FRONTEND_BUILD_WORKS: true PLAYWRIGHT_SMOKE_RAN_SUCCESSFULLY: true BACKEND_LOCAL_STARTUP_WORKS_WITH_UV: true AUTH_CSRF_CATEGORY_TOPIC_CREATION_FIXED: true ARGUMENT_POSTING_WORKS: true EKOH_MIGRATION_0002_CREATED_AND_APPLIED: true REMAINING_VISIBLE_ETHIKOS_BUG: "Deliberate preview drawer shows 'Preview / No data'" ```` The preview drawer bug is a known targeted bugfix. It MUST NOT be used as a reason to redesign the Kintsugi architecture. --- ## 5. Primary strategy variables All documents in this pack MUST respect the following constants. ```yaml KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_ETHIKOS_FRAME_STABLE: true DOCS_BEFORE_CODE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true ``` If another document, prompt, or AI session conflicts with these variables, this document wins unless explicitly superseded by a later canonical ADR. --- ## 6. Source-of-truth priority order When sources conflict, use this priority order. ```yaml SOURCE_PRIORITY_ORDER: 1_CODE_SNAPSHOT_REALITY: description: "Routes, files, current endpoints, current models, current implementation state." 2_BOUNDARIES_DOC: description: "Korum/Konsultations/Smart Vote/EkoH ownership, write rules, and pipeline." 3_CLEAN_SLATE_PLAN: description: "First-pass scope, no full merge, docs first, code inspection second." 4_KIALO_CORE_DOCS: description: "Structured deliberation contract for /ethikos/deliberate/*." 5_OSS_SOURCE_DOCS: description: "Pattern inspiration only; never direct merge in first pass." 6_PRIOR_MASTER_DOCS: description: "Use only after correcting scope and route reality." ``` Implementation reality comes from the current Konnaxion code snapshot. Ownership reality comes from the boundaries contract. Deliberation UX reality comes from the Kialo-style contract. OSS documents are inspiration sources only. --- ## 7. First-pass OSS scope The following sources are allowed in first pass as **native mimic inspirations only**. ```yaml FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" ``` Their first-pass role is to provide patterns, not code. --- ## 8. Deferred OSS scope The following sources are explicitly deferred. ```yaml DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ``` Deferred means: * do not include them in the first implementation scope; * do not build backlog tasks for them now; * do not create annexes for them now; * do not import their code; * mention only as future inspiration or public credit where appropriate. --- ## 9. Core ownership model The Kintsugi update depends on strict ownership boundaries. ```yaml OWNERSHIP: KORUM_OWNS: - "Ethikos topics used as debate/deliberation containers" - "Arguments" - "Threaded argument graph" - "Topic-level stance events" - "Moderation on debate artifacts" KONSULTATIONS_OWNS: - "Intake" - "Consultations" - "Citizen suggestions" - "Ballot capture" - "Result snapshots" - "Impact tracking" SMART_VOTE_OWNS: - "Derived readings" - "Lens declarations" - "Aggregations" - "Result publication" EKOH_OWNS: - "Expertise context" - "Ethics context" - "Cohort eligibility" - "Domain vectors" - "Snapshot/audit context" ``` No generated document may redefine these ownership boundaries without creating or referencing an ADR. --- ## 10. Write rules The following rules are mandatory. ```yaml WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_KORUM_RECORDS: false SMART_VOTE_MUTATES_KONSULTATIONS_RECORDS: false SMART_VOTE_WRITES_ONLY_DERIVED_ARTIFACTS: true EKOH_IS_VOTING_ENGINE: false EKOH_MUTATES_VOTES: false WEIGHTED_OUTCOME_REQUIRES_REPRODUCIBILITY: true READING_FORMULA: "Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?)" ``` Smart Vote publishes readings. EkoH supplies expertise and ethics context. Korum and Konsultations own the source facts. --- ## 11. Current backend reality The current backend is Django/DRF. ```yaml CURRENT_BACKEND_CORE: ETHIKOS_BACKEND_APP: "konnaxion.ethikos" KOLLECTIVE_BACKEND_APP: "konnaxion.kollective_intelligence" USERS_APP: "konnaxion.users" AUTH_USER_MODEL: "users.User" ROOT_URLCONF: "config.urls" API_ROUTER_FILE: "config/api_router.py" DEFAULT_API_STYLE: "Django REST Framework ViewSet + Serializer + Router" DEFAULT_DB: "PostgreSQL" BACKGROUND_WORKER: "Celery" BROKER_RESULT_BACKEND: "Redis" ``` Current ethiKos models: ```yaml CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" ``` Current canonical endpoints: ```yaml CURRENT_ENDPOINTS_CANONICAL: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" ``` Compatibility aliases: ```yaml CURRENT_ENDPOINTS_COMPATIBILITY: DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." ``` Legacy/problematic endpoint family: ```yaml LEGACY_OR_PROBLEMATIC_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" RULE: "Do not expand /api/home/* usage. Replace, isolate, or mark legacy." ``` --- ## 12. Current frontend route surface The Kintsugi upgrade targets the existing ethiKos route surface. ```yaml PRIMARY_ROUTE_SURFACE: "/ethikos/*" ``` Canonical route families: ```yaml ETHIKOS_ROUTE_FAMILIES: DECIDE: PREFIX: "/ethikos/decide/*" ROUTES: - "/ethikos/decide/elite" - "/ethikos/decide/public" - "/ethikos/decide/results" - "/ethikos/decide/methodology" DELIBERATE: PREFIX: "/ethikos/deliberate/*" ROUTES: - "/ethikos/deliberate/elite" - "/ethikos/deliberate/[topic]" - "/ethikos/deliberate/guidelines" TRUST: PREFIX: "/ethikos/trust/*" ROUTES: - "/ethikos/trust/profile" - "/ethikos/trust/badges" - "/ethikos/trust/credentials" PULSE: PREFIX: "/ethikos/pulse/*" ROUTES: - "/ethikos/pulse/overview" - "/ethikos/pulse/live" - "/ethikos/pulse/health" - "/ethikos/pulse/trends" IMPACT: PREFIX: "/ethikos/impact/*" ROUTES: - "/ethikos/impact/feedback" - "/ethikos/impact/outcomes" - "/ethikos/impact/tracker" LEARN: PREFIX: "/ethikos/learn/*" ROUTES: - "/ethikos/learn/changelog" - "/ethikos/learn/glossary" - "/ethikos/learn/guides" INSIGHTS: PREFIX: "/ethikos/insights" ROUTES: - "/ethikos/insights" ADMIN: PREFIX: "/ethikos/admin/*" ROUTES: - "/ethikos/admin/audit" - "/ethikos/admin/moderation" - "/ethikos/admin/roles" ``` The Kintsugi update MUST NOT create a new top-level Kintsugi app or a new Kialo route family. --- ## 13. Route-family purpose | Route family | Kintsugi role | | ----------------------- | ------------------------------------------------------------------------------------------ | | `/ethikos/deliberate/*` | Korum, structured argumentation, Kialo-style claim graph, Consider.it-style reason capture | | `/ethikos/decide/*` | Decision protocols, ballots, Smart Vote readings, result publication | | `/ethikos/impact/*` | Accountability, implementation tracking, outcomes, feedback loops | | `/ethikos/pulse/*` | Participation health, live signals, trends, debate-quality indicators | | `/ethikos/trust/*` | EkoH visibility, trust profile, credentials, badges | | `/ethikos/admin/*` | Audit, moderation, roles, eligibility and governance controls | | `/ethikos/learn/*` | Guides, glossary, methodology, public explanation | | `/ethikos/insights` | Analytics, reading comparison, Smart Vote/EkoH interpretation | --- ## 14. Kialo-style deliberation contract summary Kialo-style argument mapping is a first-pass canonical reference for structured deliberation under Korum. It is not a separate module. ```yaml KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ROLE_IN_KINTSUGI: "Canonical structured deliberation UX reference for Korum." ``` Canonical Kialo-to-ethiKos mapping: ```yaml KIALO_CANONICAL_MAPPING: KIALO_DISCUSSION: "EthikosTopic" KIALO_THESIS: "Topic thesis/prompt field; current fallback is EthikosTopic.title + description" KIALO_CLAIM: "EthikosArgument" KIALO_PRO_CON_EDGE: "EthikosArgument.parent + EthikosArgument.side" KIALO_SOURCE: "ArgumentSource" KIALO_IMPACT_VOTE: "ArgumentImpactVote" KIALO_SUGGESTED_CLAIM: "ArgumentSuggestion" KIALO_PERSPECTIVE: "DiscussionPerspective / Smart Vote lens depending context" KIALO_PARTICIPANT_ROLE: "DiscussionParticipantRole" ``` Critical Kialo rules: ```yaml KIALO_ANTI_DRIFT_RULES: - "Do not rename EthikosArgument to Claim." - "Do not create konnaxion.kialo." - "Do not create /kialo routes." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expose anonymous identities to normal participants." - "Do not publish suggested claims without approval when role is suggester." ``` --- ## 15. Vote-type separation The Kintsugi update MUST separate three concepts that are easy to confuse. ```yaml VOTE_TYPE_SEPARATION: ETHIKOS_STANCE: RANGE: "-3..+3" LEVEL: "topic-level" OWNER: "Korum" MODEL: "EthikosStance" MEANING: "User stance on topic." KIALO_IMPACT_VOTE: RANGE: "0..4" LEVEL: "argument/claim-level" OWNER: "Korum" PROPOSED_MODEL: "ArgumentImpactVote" MEANING: "Impact of a claim on its parent; combines veracity and relevance." SMART_VOTE_READING: RANGE: "not fixed; depends on lens and modality" LEVEL: "derived aggregation" OWNER: "Smart Vote" PROPOSED_MODEL: "ReadingResult" MEANING: "Published derived reading of baseline events." ``` Mandatory separation rules: ```yaml CRITICAL_VOTE_RULES: CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false ``` --- ## 16. Kintsugi pipeline The full civic workflow is expressed as six stages. | Stage | Name | Owner | Required outputs | | ----- | ------------------------ | -------------------------- | ----------------------------------------------------------------------- | | 0 | Intake | Konsultations | `ProblemStatement`, `IntakeQueue`, `TopicTags` | | 1 | Discovery / Consultation | Konsultations | `OptionSet`, `ConstraintSet`, optional `ConsensusMapArtifact` | | 2 | Deliberation | Korum | `ArgumentGraph`, `StanceEvents`, `ModerationLog` | | 3 | Drafting | ethiKos bounded capability | `Draft`, `VersionHistory`, `Amendments`, `RationalePacket` | | 4 | Decision | Smart Vote | `BaselineResult`, `ReadingResults`, `DecisionRecord` | | 5 | Accountability | Konsultations + handoff | `ImpactTrack`, execution handoff links, public accountability snapshots | The pipeline is a contract. Individual routes may expose only part of it, but generated documents must not collapse all stages into one model or one table. --- ## 17. Data model policy The Kintsugi update must evolve the data model conservatively. ```yaml DATA_MODEL_POLICY: BREAK_EXISTING_MODELS: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_FIELDS: false ADD_NON_BREAKING_TABLES_ALLOWED: true ADD_NON_BREAKING_FIELDS_ALLOWED: true MIGRATIONS_REQUIRED_FOR_NEW_MODELS: true FUTURE_MAKEMIGRATIONS_DRIFT_MUST_BE_AVOIDED: true ``` Existing models are preserved. Proposed models may be introduced only through documented migration plans and ownership contracts. --- ## 18. Proposed first-pass model priorities The following model concepts are candidates for first-pass consideration. ```yaml FIRST_PASS_MODEL_PRIORITY: MUST_CONSIDER: - "DecisionProtocol" - "DecisionRecord" - "LensDeclaration" - "ReadingResult" - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" - "ImpactTrack" - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" DEFER: - "ArgumentBookmark" - "ArgumentLink" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionPerspective" - "DiscussionExport" ``` This list is not an implementation backlog. It is a planning boundary. --- ## 19. Mimic vs Annex summary Default external-tool strategy: ```yaml MIMIC_VS_ANNEX: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" MIMIC_FIRST_PASS: true ANNEX_REQUIRES_ISOLATION: true ANNEX_REQUIRES_REPLACEABILITY: true ANNEX_REQUIRES_NO_CORE_TABLE_WRITES: true ANNEX_REQUIRES_LICENSE_CLEARANCE: true ANNEX_REQUIRES_ADAPTER_LAYER: true FULL_CODE_IMPORT_DEFAULT: false ``` Annex boundary objects: ```yaml ANNEX_BOUNDARY_OBJECTS: - "ExternalArtifact" - "ProjectionMapping" ``` In first pass, assume mimic. Do not design annex integration unless the assigned document explicitly concerns future annex rules. --- ## 20. Document pack The complete documentation pack contains the following files. ```text 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 21. Recommended generation order When generating the pack in parallel AI conversations, each conversation should generate exactly one file. Recommended order: ```text 1. 00_KINTSUGI_START_HERE.md 2. 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 3. 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 4. 04_CANONICAL_NAMING_AND_VARIABLES.md 5. 20_AI_GENERATION_GUARDRAILS.md 6. 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 7. 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 8. 10_FIRST_PASS_INTEGRATION_MATRIX.md 9. 11_MIMIC_VS_ANNEX_RULEBOOK.md 10. 05_CURRENT_STATE_BASELINE.md 11. 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 12. 07_API_AND_SERVICE_CONTRACTS.md 13. 08_DATA_MODEL_AND_MIGRATION_PLAN.md 14. 09_SMART_VOTE_EKOH_READING_CONTRACT.md 15. 12_CANONICAL_OBJECTS_AND_EVENTS.md 16. 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 17. 14_FRONTEND_ALIGNMENT_CONTRACT.md 18. 15_BACKEND_ALIGNMENT_CONTRACT.md 19. 16_TEST_AND_SMOKE_CONTRACT.md 20. 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 21. 18_ADR_REGISTER.md 22. 19_OSS_CODE_READING_PLAN.md 23. 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 22. Document responsibilities | File | Responsibility | | ----------------------------------------------- | -------------------------------------------- | | `00_KINTSUGI_START_HERE.md` | Entry point and orientation | | `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` | Strategic execution framing | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Source hierarchy and drift prevention | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Ownership and write rules | | `04_CANONICAL_NAMING_AND_VARIABLES.md` | Names, constants, slugs, enums | | `05_CURRENT_STATE_BASELINE.md` | Current code and product baseline | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route-by-route Kintsugi mapping | | `07_API_AND_SERVICE_CONTRACTS.md` | API and frontend service contracts | | `08_DATA_MODEL_AND_MIGRATION_PLAN.md` | Schema and migration strategy | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Baseline, readings, lenses, snapshots | | `10_FIRST_PASS_INTEGRATION_MATRIX.md` | OSS first-pass mimic matrix | | `11_MIMIC_VS_ANNEX_RULEBOOK.md` | Rules for mimic, annex, and no-go | | `12_CANONICAL_OBJECTS_AND_EVENTS.md` | Domain objects and event vocabulary | | `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` | JSON contracts and serializer shape | | `14_FRONTEND_ALIGNMENT_CONTRACT.md` | Next.js, shell, route and service rules | | `15_BACKEND_ALIGNMENT_CONTRACT.md` | Django/DRF alignment rules | | `16_TEST_AND_SMOKE_CONTRACT.md` | Test and smoke minimums | | `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` | Known bugs and exclusions | | `18_ADR_REGISTER.md` | Architecture decision records | | `19_OSS_CODE_READING_PLAN.md` | Future OSS repo inspection plan | | `20_AI_GENERATION_GUARDRAILS.md` | AI-specific generation constraints | | `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` | Kialo-style structured deliberation contract | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Template for later backlog generation | --- ## 23. Required document sections Every document in this pack SHOULD include these sections unless the assigned document has a stronger reason to differ. ```text 1. Purpose 2. Scope 3. Canonical variables used 4. Source-of-truth references 5. Non-goals 6. Main contract or content 7. Anti-drift rules 8. Related documents ``` --- ## 24. Non-goals for this pack The Kintsugi documentation pack is not intended to: * perform the implementation; * rewrite the whole platform; * replace current ethiKos routes; * replace current ethiKos models; * import external civic-tech code; * create a new Kialo module; * create a new Kintsugi frontend app; * create a full annex integration; * expand `/api/home/*`; * turn EkoH into a voting engine; * let Smart Vote mutate source facts; * generate a full implementation backlog before docs and code reading are complete. --- ## 25. Known bug boundary The following item is known and open. ```yaml KNOWN_BUGS: BUG_001: TITLE: "Deliberate preview drawer shows 'Preview / No data'" STATUS: "known_open" CLASSIFICATION: "targeted_bugfix_not_architecture" DO_NOT_USE_TO_REDESIGN_KINTSUGI: true ``` This bug should be tracked and fixed, but it MUST NOT dominate the Kintsugi documentation process. --- ## 26. AI generation rules Any AI session generating one of these docs MUST follow these rules. ```yaml GENERATION_RULES: GENERATE_ONE_FILE_PER_CONVERSATION: true EACH_CONVERSATION_MUST_OBEY_CANONICAL_VARIABLES: true DO_NOT_REINTERPRET_SCOPE: true DO_NOT_CREATE_NEW_ARCHITECTURE_UNLESS_DOC_EXPLICITLY_ASSIGNED: true IF_CONFLICT_USE_SOURCE_PRIORITY_ORDER: true ``` Each AI-generated document MUST NOT: * invent new routes; * invent new endpoints; * rename existing canonical models; * create a new Kialo app; * create a new top-level Kintsugi app; * propose a full OSS merge; * treat Kialo impact votes as topic stances; * treat Kialo impact votes as Smart Vote ballots; * expand `/api/home/*`; * create a second layout shell; * create a second theme system. --- ## 27. Absolute forbidden outputs The following outputs are forbidden across the entire pack. ```yaml FORBIDDEN: - "Do not propose full external OSS merge." - "Do not create a new Kialo app." - "Do not create a new top-level Kintsugi frontend app." - "Do not rename EthikosArgument to Claim." - "Do not rename /api/ethikos/... to /api/deliberation/..." - "Do not convert EkoH into a voting engine." - "Do not let Smart Vote mutate upstream facts." - "Do not let foreign tools write to Korum/Konsultations core tables." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expand /api/home/*." - "Do not create a second layout shell." - "Do not create a second theme system." - "Do not produce implementation tasks before documentation contracts unless generating doc 22." ``` --- ## 28. Required ADRs The ADR register MUST include at least the following decisions. ```yaml REQUIRED_ADRS: ADR_001: "No full OSS merge" ADR_002: "Existing Ethikos route families remain stable" ADR_003: "Korum and Konsultations ownership split" ADR_004: "Smart Vote publishes readings only" ADR_005: "EkoH is context, not voting engine" ADR_006: "Drafting is separate bounded capability" ADR_007: "External tools use mimic first, annex later" ADR_008: "/api/home legacy calls must be removed or isolated" ADR_009: "Impact belongs to Ethikos/Konsultations truth, not KeenKonnect truth" ADR_010: "Implementation backlog comes after docs and code-reading" ADR_011: "Kialo-style features extend Korum; no separate Kialo module" ``` --- ## 29. How to use this file Before generating or editing any Kintsugi document: 1. Read this file. 2. Confirm the assigned document filename. 3. Follow the source-of-truth order. 4. Use the canonical variables. 5. Do not reinterpret the first-pass scope. 6. Do not invent new architecture. 7. Generate only the assigned document. 8. Cross-reference related documents. 9. Keep implementation tasks out unless generating `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md`. --- ## 30. Related documents This file directly governs or is referenced by: ```text 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 31. Final binding statement For the ethiKos Kintsugi Upgrade documentation pack: ```yaml FINAL_BINDING_STATEMENT: KINTSUGI_IS: "A documentation-first native-mimic architecture upgrade." KINTSUGI_IS_NOT: "A full OSS merge, route rewrite, or backend ownership collapse." PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_BACKEND_APP: "konnaxion.ethikos" PRIMARY_DELIBERATION_CONTRACT: "Korum + Kialo-style native mimic" PRIMARY_DECISION_CONTRACT: "Smart Vote readings over baseline events" PRIMARY_EXPERTISE_CONTEXT: "EkoH snapshots and cohort context" PRIMARY_DRIFT_CONTROL_RULE: "If a generated document conflicts with this file, this file wins unless a later ADR explicitly supersedes it." ``` --- ## V4.1 canonical extension — EkoH rating disclosure `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md` is the canonical contract for individual EkoH rating visibility, scoped disclosure, reusable EkoH profile UI, and the boundary between rating disclosure and Smart Vote contextual influence. It MUST be read with `03`, `07`, `08`, `09`, `13`, `14`, `15`, `16`, and `18`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: ac923db7e5d5c03f95b36ac6eb0b89e7e4e05f3cc1aab9dda1b4cf358d65aff9 CONTENT_BYTES: 27913 ================================================================================================ # 01 — ethiKos Kintsugi Execution Strategy **File:** `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` **Pack:** `ethiKos Kintsugi Update Documentation Pack` **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Status:** Draft for execution alignment **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Primary module:** `ethiKos` **Update name:** `Kintsugi` --- ## 1. Purpose This document defines the execution strategy for the **ethiKos Kintsugi Upgrade**. The Kintsugi Upgrade transforms ethiKos from a structured debate module into a fuller civic deliberation, consultation, drafting, decision-formation, and accountability engine while preserving the existing Konnaxion architecture. This strategy is not an implementation backlog. It is the execution-level architectural frame that all later technical plans, route plans, migrations, payload contracts, and code-reading passes MUST obey. The purpose of this document is to fix: - the strategic intent of the Kintsugi upgrade; - the first-pass scope; - the relationship between ethiKos, Korum, Konsultations, Smart Vote, and EkoH; - the rule that OSS civic tools are mimicked natively before any annex/sidecar approach; - the route-level execution strategy; - the distinction between baseline facts, derived readings, and external inspiration patterns; - the non-goals and anti-drift rules for future AI-assisted generation. --- ## 2. Scope This document covers the execution strategy for the first Kintsugi planning and documentation pass. It covers: - ethiKos product positioning; - strategic transformation goals; - first-pass OSS source usage; - deferred OSS source usage; - mimic vs annex strategy; - ownership boundaries; - route-family strategy; - data-model posture; - Smart Vote and EkoH relationship; - Kialo-style deliberation strategy; - execution sequence; - success criteria; - anti-drift rules. It does not define: - exact Django model fields; - exact serializers; - exact migrations; - exact frontend component implementation; - exact test files; - full implementation backlog; - direct code modifications; - final UI copy; - deployment procedure. Those details belong in the companion documents listed in Section 18. --- ## 3. Canonical Variables Used This document is governed by the following canonical variables. ```yaml PROJECT: PLATFORM_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" FULL_UPDATE_NAME: "ethiKos Kintsugi Upgrade" STRATEGY: KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_ETHIKOS_FRAME_STABLE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" PRIMARY_ROUTE_SURFACE: "/ethikos/*" OWNERSHIP: KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument graph" - "debate moderation" KONSULTATIONS_OWNS: - "intake" - "consultations" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false ```` --- ## 4. Strategic Summary The Kintsugi Upgrade makes ethiKos the civic reasoning and decision-formation layer of Konnaxion. The upgrade does not replace the existing ethiKos surface. It strengthens it. The existing route families remain the execution surface: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` The upgrade introduces a coherent civic pipeline: ```txt Intake → Discovery / Consultation → Deliberation → Drafting → Decision → Accountability ``` The upgrade integrates selected patterns from external civic tools, but it does not merge those tools into Konnaxion. The guiding rule is: ```txt Mimic useful civic patterns natively inside ethiKos. Do not import external architectures into the core product. ``` --- ## 5. Why the Upgrade Exists Online debate usually fails because it is not structured for decision-quality reasoning. Common failures include: * chronological feeds that reward repetition and emotional escalation; * debate threads that collapse into identity conflict; * unclear separation between arguments, stances, votes, and decisions; * weak provenance of claims and evidence; * no clear transition from discussion to drafting; * no auditable path from vote to outcome; * no accountability layer after a decision is made; * no distinction between raw outcomes and interpreted readings. ethiKos Kintsugi exists to correct these structural failures by turning civic participation into a staged, auditable, and decision-ready process. The upgrade is not intended to make ethiKos merely more interactive. It is intended to make ethiKos more legitimate, more legible, more reproducible, and more useful for real governance workflows. --- ## 6. Product Positioning ethiKos is the Konnaxion module responsible for structured civic reasoning and decision-formation. After Kintsugi, ethiKos SHOULD be understood as: > A unified civic deliberation, consultation, drafting, decision, and accountability engine that preserves a canonical baseline truth while allowing declared, reproducible Smart Vote readings. The module is composed of bounded internal responsibilities: | Layer | Role | | ------------- | ------------------------------------------------------------------------------- | | Korum | Structured deliberation, topics, stances, arguments, argument graph, moderation | | Konsultations | Intake, consultation flow, ballots, result snapshots, impact tracking | | Smart Vote | Derived readings, lens declarations, aggregation, result publication | | EkoH | Expertise context, ethics context, cohort eligibility, snapshot/audit context | | Kintsugi | Orchestration strategy for integrating civic-tech patterns into ethiKos | Kintsugi is not a separate product surface. It is the upgrade strategy and integration architecture for ethiKos. --- ## 7. Execution Principles ### 7.1 Preserve the Existing Frame The Kintsugi Upgrade MUST preserve the existing ethiKos frame and route families. It MUST NOT create: * a new top-level `/kintsugi` application; * a new `/kialo` route family; * a second ethiKos shell; * a separate civic-tech clone beside ethiKos; * duplicate decision surfaces outside `/ethikos/*`. ### 7.2 Native Mimic First The first-pass strategy is native mimic. This means: * extract the useful product pattern; * translate it into the existing Konnaxion stack; * implement it through existing ethiKos route families; * preserve Konnaxion data ownership; * avoid importing foreign architecture; * avoid creating sidecars before the core contracts are stable. ### 7.3 Annex Later Only When Safe Annex or sidecar integration MAY be considered later only when all of the following are true: * the feature is modular; * the license is acceptable; * the component is isolated; * the component is replaceable; * it does not write to core ethiKos tables; * it has an adapter boundary; * it does not create duplicate truth; * it does not dominate the Konnaxion UX. ### 7.4 Docs First, Code Second The Kintsugi Upgrade MUST proceed in this order: ```txt 1. Documentation contracts 2. Source-of-truth alignment 3. Route-by-route plan 4. Data and payload contracts 5. Code-reading plan 6. Implementation backlog 7. Code changes ``` Code changes before contract stabilization are out of scope for this document. --- ## 8. First-Pass OSS Source Strategy The following sources are first-pass inspirations. They are used as pattern references only. | Source | First-pass use | ethiKos target | | ---------------------------- | ---------------------------------------------------------------- | -------------------------------------------- | | Consider.it | Reason capture, pro/con deliberation compression | `/ethikos/deliberate/*` | | Kialo-style argument mapping | Structured claim graph, sources, impact voting, roles, anonymity | `/ethikos/deliberate/*` | | Loomio | Proposal lifecycle, discussion-to-decision transition | `/ethikos/decide/*` | | Citizen OS | Drafting, versioning, topic lifecycle | Drafting capability under ethiKos | | Decidim | Process architecture, components, accountability, admin patterns | `/ethikos/impact/*`, `/ethikos/admin/*` | | CONSUL Democracy | Eligibility, thresholds, proposal governance | `/ethikos/decide/*`, `/ethikos/admin/*` | | DemocracyOS | Proposal-centric policy debate | `/ethikos/decide/*`, `/ethikos/deliberate/*` | The first-pass source strategy is: ```yaml CONSIDER_IT: "mimic" KIALO_STYLE: "mimic" LOOMIO: "mimic" CITIZEN_OS: "mimic" DECIDIM: "mimic" CONSUL_DEMOCRACY: "mimic" DEMOCRACY_OS: "mimic" ``` No first-pass OSS source is allowed to become a direct merge. --- ## 9. Deferred OSS Sources The following sources are explicitly deferred. | Source | Status | | --------------- | -------------------------------- | | Polis | Deferred / public credit only | | LiquidFeedback | Deferred / public credit only | | All Our Ideas | Deferred | | Your Priorities | Deferred | | OpenSlides | Deferred / possible future annex | These sources MUST NOT drive first-pass implementation. They MAY be referenced as longer-term inspiration, but they MUST NOT introduce new first-pass models, routes, services, or architectural decisions. --- ## 10. Korum Strategy Korum is the structured deliberation side of ethiKos. It owns: * topics used as deliberation containers; * topic-level stances; * arguments; * argument threading; * argument graph; * argument moderation; * claim/source evidence attachments; * Kialo-style structured argument UX. Korum’s first-pass strategy is to evolve the current `EthikosTopic`, `EthikosStance`, and `EthikosArgument` foundation into a stronger structured deliberation workspace. The core mapping is: ```txt Kialo Discussion → EthikosTopic Kialo Thesis → Topic prompt / thesis / title + description Kialo Claim → EthikosArgument Kialo Pro/Con relation → EthikosArgument.parent + EthikosArgument.side Kialo Source → ArgumentSource Kialo Impact Vote → ArgumentImpactVote Kialo Suggested Claim → ArgumentSuggestion ``` Important distinction: ```txt EthikosStance ≠ ArgumentImpactVote ArgumentImpactVote ≠ Smart Vote ballot ``` Korum MUST preserve the current `EthikosArgument` concept. The implementation MUST NOT rename `EthikosArgument` to `Claim`. The term “claim” MAY be used in UX language or documentation, but the current backend object remains `EthikosArgument`. --- ## 11. Konsultations Strategy Konsultations is the consultation and civic intake side of ethiKos. It owns: * intake; * consultation framing; * citizen suggestions; * ballot capture; * result snapshots; * accountability preparation; * impact tracking. Konsultations converts civic input into structured decision material. The first-pass strategy is to formalize Konsultations as a bounded ethiKos capability without creating a separate app unless the backend architecture later proves it necessary. Konsultations MUST NOT collapse into Korum. Korum and Konsultations are related but distinct: | Concern | Owner | | ------------------- | ------------- | | Argument graph | Korum | | Topic stance | Korum | | Consultation ballot | Konsultations | | Result snapshot | Konsultations | | Impact tracking | Konsultations | | Derived reading | Smart Vote | Konsultations MAY reuse `EthikosTopic` as a container when the current implementation requires it, but the documentation MUST preserve the conceptual distinction. --- ## 12. Smart Vote Strategy Smart Vote owns derived readings. It does not own raw source facts. It does not mutate Korum records. It does not mutate Konsultations records. It does not replace baseline results. Smart Vote computes declared readings from baseline events. The core formula is: ```txt Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?) ``` Smart Vote outputs MUST be reproducible. A Smart Vote reading MUST be bound to: ```txt reading_key lens_hash snapshot_ref computed_at topic_id or consultation_id results_payload ``` The baseline result MUST remain visible even when weighted or filtered Smart Vote readings are displayed. The strategic rule is: ```txt Single truth, multiple readings. ``` Baseline facts are the source of legitimacy. Smart Vote readings are declared interpretations of those facts. --- ## 13. EkoH Strategy EkoH provides expertise and ethics context. It owns: * expertise context; * ethics context; * cohort eligibility; * domain vectors; * snapshot references; * audit context for readings. EkoH is not the voting engine. EkoH MUST NOT mutate votes. EkoH MUST NOT replace Smart Vote. EkoH MAY provide context used by Smart Vote readings, such as: * expertise-weighted readings; * cohort-filtered readings; * ethics-contextualized readings; * domain-specific readings. The relationship is: ```txt EkoH provides context. Smart Vote computes readings. ethiKos preserves baseline events. ``` --- ## 14. Route-Family Execution Strategy The Kintsugi Upgrade MUST map onto the existing ethiKos route families. ### 14.1 `/ethikos/deliberate/*` Primary role: ```txt Structured deliberation and argument mapping. ``` Patterns: * Kialo-style claim graph; * Consider.it-style pro/con reason compression; * DemocracyOS-style proposal discussion. First-pass capabilities SHOULD include: * argument tree; * parent/child pro/con relation; * source attachment; * impact voting separated from topic stance; * suggested claims; * role-aware participation; * author visibility rules; * basic topic background panel. Deferred capabilities MAY include: * sunburst minimap; * small group mode; * custom perspectives; * clone-from-template; * export; * cross-discussion claim extraction. ### 14.2 `/ethikos/decide/*` Primary role: ```txt Decision protocols, ballots, Smart Vote readings, and result publication. ``` Patterns: * Loomio proposal lifecycle; * CONSUL Democracy eligibility/threshold logic; * DemocracyOS proposal-centric decision framing. First-pass capabilities SHOULD include: * decision record; * decision protocol; * open/closed/published lifecycle; * baseline result; * Smart Vote reading display; * methodology explanation. ### 14.3 `/ethikos/impact/*` Primary role: ```txt Accountability and implementation tracking. ``` Patterns: * Decidim accountability; * CONSUL Democracy public follow-through; * outcome/feedback loops. First-pass capabilities SHOULD include: * outcome tracking; * impact status; * public feedback; * accountability updates; * connection to decision records. Impact truth SHOULD belong to ethiKos/Konsultations, not to KeenKonnect project truth. KeenKonnect MAY receive handoff links after a decision is made, but it MUST NOT own the civic impact source of truth. ### 14.4 `/ethikos/pulse/*` Primary role: ```txt Participation health and civic signal monitoring. ``` First-pass capabilities SHOULD include: * activity health; * participation trends; * live civic signals; * deliberation quality indicators. Pulse SHOULD visualize process state rather than create a separate source of truth. ### 14.5 `/ethikos/trust/*` Primary role: ```txt Trust, expertise, credentials, and EkoH-facing civic context. ``` First-pass capabilities SHOULD include: * trust profile; * badges; * credentials; * EkoH-derived civic context. Trust MUST NOT become the voting engine. ### 14.6 `/ethikos/admin/*` Primary role: ```txt Audit, moderation, roles, and governance controls. ``` First-pass capabilities SHOULD include: * moderation queue; * audit trail; * participant roles; * eligibility configuration; * visibility settings; * Kialo-style discussion role controls. ### 14.7 `/ethikos/learn/*` Primary role: ```txt Public explanation and civic literacy. ``` First-pass capabilities SHOULD include: * glossary; * guides; * methodology; * changelog; * explanation of baseline vs readings; * explanation of Korum, Konsultations, Smart Vote, and EkoH. ### 14.8 `/ethikos/insights` Primary role: ```txt Analytics, reading comparison, and interpretation. ``` First-pass capabilities SHOULD include: * baseline vs derived reading comparison; * Smart Vote reading summaries; * participation summaries; * argument and decision quality signals. Insights MUST NOT create a separate result truth. --- ## 15. Data Strategy The Kintsugi Upgrade MUST use a non-destructive data strategy. Existing core models MUST remain stable: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` The upgrade MAY add non-breaking tables and fields. It MUST NOT: * rename existing core models; * delete existing core fields; * break existing endpoints; * replace `EthikosArgument` with `Claim`; * replace `EthikosStance` with `Vote`; * collapse Smart Vote readings into raw stance records; * allow external tools to write core tables directly. Potential new model areas include: ```txt DecisionProtocol DecisionRecord LensDeclaration ReadingResult Draft DraftVersion Amendment RationalePacket ImpactTrack ExternalArtifact ProjectionMapping ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` The data model details are not finalized in this document. They MUST be defined in: ```txt 08_DATA_MODEL_AND_MIGRATION_PLAN.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md ``` --- ## 16. API and Service Strategy The current canonical ethiKos API prefix remains: ```txt /api/ethikos/* ``` Current canonical endpoints include: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` Compatibility aliases MAY remain: ```txt /api/deliberate/... /api/deliberate/elite/... ``` The upgrade MUST NOT invent a replacement prefix such as: ```txt /api/deliberation/* ``` The upgrade MUST NOT expand legacy `/api/home/*` usage. Where `/api/home/*` still appears, it MUST be treated as legacy, isolated, or migrated behind canonical service contracts. Frontend code SHOULD use the services layer. New direct raw fetches from page components SHOULD be avoided unless explicitly documented. --- ## 17. Execution Sequence The strategy is executed in documentation-first phases. ### Phase 1 — Anti-Drift Documentation Produce and stabilize: ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 20_AI_GENERATION_GUARDRAILS.md ``` ### Phase 2 — Strategy and Scope Produce and stabilize: ```txt 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 18_ADR_REGISTER.md ``` ### Phase 3 — Product and Route Contracts Produce and stabilize: ```txt 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md ``` ### Phase 4 — Technical Contracts Produce and stabilize: ```txt 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md ``` ### Phase 5 — Code Reading and Backlog Produce and stabilize: ```txt 19_OSS_CODE_READING_PLAN.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` Only after these phases should implementation tasks be generated. --- ## 18. Companion Documents This strategy document depends on the full documentation pack. | File | Purpose | | ----------------------------------------------- | -------------------------------------------- | | `00_KINTSUGI_START_HERE.md` | Entry point and current baseline | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Source priority and conflict resolution | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Ownership and write rules | | `04_CANONICAL_NAMING_AND_VARIABLES.md` | Fixed names, slugs, constants | | `05_CURRENT_STATE_BASELINE.md` | Current code and product baseline | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route-level execution plan | | `07_API_AND_SERVICE_CONTRACTS.md` | Backend/frontend service contracts | | `08_DATA_MODEL_AND_MIGRATION_PLAN.md` | Non-destructive model and migration strategy | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Readings, lenses, snapshots | | `10_FIRST_PASS_INTEGRATION_MATRIX.md` | OSS source-to-Ethikos mapping | | `11_MIMIC_VS_ANNEX_RULEBOOK.md` | Pattern adoption rules | | `12_CANONICAL_OBJECTS_AND_EVENTS.md` | Civic domain object/event model | | `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` | JSON and serializer contracts | | `14_FRONTEND_ALIGNMENT_CONTRACT.md` | Frontend shell, routes, services | | `15_BACKEND_ALIGNMENT_CONTRACT.md` | Django/DRF alignment rules | | `16_TEST_AND_SMOKE_CONTRACT.md` | Smoke and regression expectations | | `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` | Known bugs and out-of-scope items | | `18_ADR_REGISTER.md` | Architecture decision records | | `19_OSS_CODE_READING_PLAN.md` | How to inspect downloaded OSS repos | | `20_AI_GENERATION_GUARDRAILS.md` | AI anti-drift rules | | `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` | Kialo-style structured deliberation contract | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Template for future implementation tasks | --- ## 19. Non-Goals This strategy explicitly does not authorize: * full external OSS merge; * direct Kialo code import; * direct Loomio code import; * direct Decidim code import; * direct CONSUL Democracy code import; * direct DemocracyOS code import; * direct Citizen OS code import; * creation of `konnaxion.kialo`; * creation of `/kialo` routes; * creation of a second ethiKos shell; * creation of a separate Kintsugi frontend application; * expansion of `/api/home/*`; * renaming `EthikosArgument` to `Claim`; * renaming `/api/ethikos/*` to `/api/deliberation/*`; * converting EkoH into the voting engine; * allowing Smart Vote to mutate source facts; * allowing foreign tools to write core ethiKos tables; * treating Kialo impact votes as topic stances; * treating Smart Vote readings as baseline facts; * generating implementation tasks before documentation contracts are stable. --- ## 20. Anti-Drift Rules The following rules are binding for future documentation and code-generation sessions. ### 20.1 Route Drift Do not invent new route families when an existing `/ethikos/*` route family can carry the feature. Wrong: ```txt /kialo/* /kintsugi/* /deliberation/* ``` Correct: ```txt /ethikos/deliberate/* /ethikos/decide/* /ethikos/impact/* /ethikos/admin/* ``` ### 20.2 Model Drift Do not rename existing canonical models. Wrong: ```txt Claim replaces EthikosArgument Vote replaces EthikosStance ``` Correct: ```txt Claim is a conceptual UX term. EthikosArgument remains the backend model. EthikosStance remains the topic-level stance model. ``` ### 20.3 Vote Drift Do not merge the three vote concepts. ```txt EthikosStance = topic-level stance, range -3..+3 ArgumentImpactVote = claim-level impact vote, range 0..4 Smart Vote Reading = derived aggregation, lens-based ``` ### 20.4 Ownership Drift Do not let layers mutate each other’s source facts. ```txt Korum owns deliberation facts. Konsultations owns consultation/ballot/impact facts. Smart Vote owns readings. EkoH owns context. ``` ### 20.5 OSS Drift Do not convert OSS inspiration into OSS dependency. ```txt Pattern mimic is allowed. Architecture import is not allowed in first pass. ``` ### 20.6 Backlog Drift Do not generate implementation backlog items inside strategy documents. Implementation tasks belong in: ```txt 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 21. Success Criteria The Kintsugi execution strategy is successful when: 1. The existing `/ethikos/*` surface remains intact. 2. Korum and Konsultations are clearly separated. 3. Smart Vote readings are reproducible and separate from baseline facts. 4. EkoH remains a context and eligibility layer, not a voting engine. 5. Kialo-style structured deliberation is mapped into `/ethikos/deliberate/*`. 6. First-pass OSS sources are used only as mimic references. 7. Deferred OSS sources do not drive first-pass work. 8. Data changes are non-destructive. 9. API contracts preserve `/api/ethikos/*`. 10. Legacy `/api/home/*` usage is not expanded. 11. The Deliberate preview drawer bug is tracked as a targeted bug, not an architecture driver. 12. Future AI sessions can generate companion docs without reinterpreting the scope. --- ## 22. Final Execution Position The Kintsugi Upgrade is a controlled, documentation-first, native-mimic upgrade to ethiKos. It is not a rewrite. It is not a merge of civic-tech platforms. It is not a new module beside ethiKos. It is an orchestration strategy that strengthens the existing Konnaxion civic layer by combining: * Korum for structured deliberation; * Konsultations for civic intake, ballots, and accountability; * Smart Vote for declared readings; * EkoH for expertise and ethics context; * selected OSS civic patterns translated into native ethiKos workflows. The first-pass execution rule is: ```txt Keep the ethiKos frame. Keep the route families. Mimic selected patterns natively. Preserve source truth. Publish declared readings. Defer annexes. Generate docs before code. ``` ``` Source basis: existing Kintsugi master draft, boundary contract, clean-slate plan, Konnaxion frontend/backend snapshot, Kialo core corpus, and technical contracts. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2} :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4} :contentReference[oaicite:5]{index=5} ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3118237094656ffce34d3fa8e90437de2ffa3421221b5cf7a6ef78ef4049a4eb CONTENT_BYTES: 28486 ================================================================================================ # 02 — Source of Truth and Drift Control **Project:** Konnaxion **Module:** ethiKos **Upgrade:** Kintsugi **Document ID:** `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` **Status:** Canonical planning contract **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Audience:** Human maintainers, AI assistants, implementation agents, documentation generators **Purpose:** Prevent architectural, naming, route, model, API, and scope drift while generating and implementing the ethiKos Kintsugi upgrade. --- ## 1. Purpose This document defines the **source-of-truth hierarchy** and **drift-control rules** for the complete ethiKos Kintsugi upgrade documentation pack. The Kintsugi upgrade is intentionally being documented before implementation so that future AI-assisted work does not: - invent new route families; - rename existing backend models; - bypass current services; - import external civic-tech architectures directly; - confuse Korum, Konsultations, Smart Vote, and EkoH ownership; - turn Smart Vote readings into source facts; - turn EkoH into a voting engine; - mistake Kialo-style impact voting for topic-level stance voting; - generate implementation backlog before the contracts are stable. This document is binding for all other Kintsugi documentation files. If any generated file conflicts with this document, this document wins unless explicitly superseded by a later human-approved ADR. --- ## 2. Scope This document governs: - documentation generation; - parallel AI conversation generation; - source priority; - conflict resolution; - canonical naming; - first-pass scope; - deferred scope; - code-vs-doc interpretation; - OSS mimic-vs-annex interpretation; - route, API, model, frontend, and backend drift prevention. This document does **not** define the full implementation plan. It defines the rules that all implementation plans must obey. --- ## 3. Canonical Variables Used The following variables are binding across the complete Kintsugi documentation pack. ```yaml PROJECT: PLATFORM_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" FULL_UPDATE_NAME: "ethiKos Kintsugi Upgrade" GENERATION: DOCS_BEFORE_CODE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true GENERATE_ONE_FILE_PER_PARALLEL_CONVERSATION: true DO_NOT_REINTERPRET_SCOPE: true STRATEGY: IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ETHIKOS_FRAME_STABLE: true EXISTING_ROUTE_FAMILIES_STABLE: true PRIMARY_ROUTE_SURFACE: ETHIKOS: "/ethikos/*" DELIBERATE: "/ethikos/deliberate/*" DECIDE: "/ethikos/decide/*" IMPACT: "/ethikos/impact/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" OWNERSHIP: KORUM_OWNS: - "topics" - "arguments" - "argument graph" - "topic-level stances" - "debate moderation" KONSULTATIONS_OWNS: - "intake" - "consultations" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "derived aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshot context" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false WEIGHTED_OUTCOME_REQUIRES_REPRODUCIBILITY: true FIRST_PASS_OSS_SCOPE: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" DEFERRED_OSS_SCOPE: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ```` --- ## 4. Source-of-Truth Hierarchy All Kintsugi documents and future implementation tasks MUST obey the following priority order. When two sources conflict, the higher-priority source wins. --- ### 4.1 Priority 1 — Current Code Snapshot Reality The current Konnaxion code snapshot is the source of truth for: * existing frontend routes; * existing backend apps; * existing API prefixes; * existing DRF routers; * existing models; * existing serializers; * existing services; * existing shell/layout patterns; * existing smoke-test reality; * known implementation gaps; * known legacy calls. The code snapshot wins for implementation reality. #### Examples If a strategy document suggests a route such as: ```txt /platforms/konnaxion/ethikos/kintsugi ``` but the actual frontend has: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/impact/* ``` then the implementation plan MUST use the real `/ethikos/*` routes. If a generated document suggests GraphQL or WebSocket CRUD for basic Ethikos objects, but the backend currently exposes Django REST Framework ViewSets under `/api/ethikos/...`, the generated document is wrong. --- ### 4.2 Priority 2 — Boundaries and Ownership Contract The boundaries document is the source of truth for: * ethiKos pipeline stages; * Korum ownership; * Konsultations ownership; * Smart Vote ownership; * EkoH ownership; * baseline vs reading separation; * foreign tool boundaries; * Mimic vs Annex strategy; * canonical objects; * audit requirements; * write rules. The boundaries document wins for ownership and legitimacy rules. #### Binding principle ```txt Single truth, multiple readings. ``` This means: * the baseline outcome remains visible; * raw source events remain canonical; * Smart Vote readings are derived; * weighted/filtered outputs must be declared and reproducible; * EkoH provides context, not votes. --- ### 4.3 Priority 3 — Clean-Slate Kintsugi Planning Context The clean-slate planning context is the source of truth for: * first-pass scope; * deferred scope; * no full external merge; * partial native mimic; * docs before code inspection; * code inspection before backlog; * Kintsugi planning focus instead of bugfixing. The clean-slate plan wins for this upgrade’s execution order. #### Binding rule ```txt This phase is Kintsugi planning, not general bugfixing. ``` The only known bug that should remain visible in the Kintsugi documentation is: ```txt Deliberate preview drawer shows "Preview / No data" ``` This bug must be tracked as a known targeted defect, not as a reason to redesign the architecture. --- ### 4.4 Priority 4 — Kialo Core Documentation The Kialo core documentation is the source of truth for the Kialo-style structured deliberation pattern. It governs: * discussions; * theses; * claims; * pro/con claim relations; * sources; * impact voting; * guided voting; * perspectives; * minimaps; * anonymous participation; * participant roles; * suggestions; * templates; * exports; * small group patterns. Kialo is a first-pass inspiration source, but it MUST be implemented as native mimic inside ethiKos/Korum. #### Binding rule ```txt Kialo-style features extend /ethikos/deliberate/*. They do not create a new Kialo module. ``` --- ### 4.5 Priority 5 — First-Pass OSS Source Documents The following OSS source documents are inspiration sources only: * Consider.it; * Loomio; * Citizen OS; * Decidim; * CONSUL Democracy; * DemocracyOS. They may influence: * user experience; * workflow patterns; * data modeling; * permissions; * lifecycle concepts; * audit concepts; * accountability patterns. They MUST NOT override: * current Ethikos routes; * current backend ownership; * the Korum/Konsultations/Smart Vote/EkoH split; * the no-full-merge rule; * the source-of-truth hierarchy. --- ### 4.6 Priority 6 — Older Master Strategy Drafts Older master Kintsugi drafts are useful for framing and public narrative. They are not authoritative when they conflict with: * current code; * boundaries; * clean-slate scope; * current route reality; * first-pass/deferred source distinctions. Older docs MUST be corrected before reuse if they imply that the following are first-pass implementation targets: * Polis; * LiquidFeedback; * All Our Ideas; * Your Priorities; * OpenSlides. For this upgrade, those are deferred. --- ## 5. Conflict Resolution Rules When a contradiction appears, apply these rules in order. --- ### 5.1 Code vs Documentation ```yaml IF_A_DOC_CONFLICTS_WITH_CODE_SNAPSHOT: IMPLEMENTATION_REALITY: "code snapshot wins" ACTION: "Update the doc or mark the doc as conceptual only." ``` Example: * A doc proposes a route that does not exist. * The code already has `/ethikos/deliberate/[topic]`. * The generated plan MUST target `/ethikos/deliberate/[topic]`. --- ### 5.2 Boundaries vs OSS Pattern ```yaml IF_AN_OSS_PATTERN_CONFLICTS_WITH_BOUNDARIES: OWNERSHIP_REALITY: "boundaries document wins" ACTION: "Mimic the useful pattern without importing ownership, architecture, or data mutation rules." ``` Example: * An OSS tool stores votes directly in its own proposal model. * Ethikos must preserve Korum/Konsultations/Smart Vote ownership. * The OSS pattern may inspire UX, but not source-of-truth mutation. --- ### 5.3 Kialo Vocabulary vs Ethikos Backend ```yaml IF_KIALO_TERMS_CONFLICT_WITH_ETHIKOS_MODELS: BACKEND_REALITY: "Ethikos models win" ACTION: "Use Kialo terms as UX/conceptual language only." ``` Example: * Kialo uses `Claim`. * Current backend uses `EthikosArgument`. * Do not rename `EthikosArgument` to `Claim`. Correct mapping: ```txt Kialo Claim = conceptual UX object EthikosArgument = backend model ``` --- ### 5.4 Smart Vote vs Source Facts ```yaml IF_A_READING_CONFLICTS_WITH_BASELINE_EVENTS: SOURCE_FACT_REALITY: "baseline events win" ACTION: "Mark reading as derived, lens-bound, and reproducible." ``` Smart Vote readings do not replace the baseline. They are declared transformations over source events. --- ### 5.5 EkoH vs Voting ```yaml IF_EKOH_IS_USED_AS_A_VOTING_ENGINE: RESULT: "invalid design" ACTION: "Move EkoH role back to expertise/ethics/snapshot context." ``` EkoH may influence declared readings through context. EkoH does not own ballots, stances, or final votes. --- ### 5.6 Parallel AI Output Conflict ```yaml IF_TWO_PARALLEL_DOCS_DISAGREE: FIRST: "Check this document." SECOND: "Check canonical naming variables." THIRD: "Check boundaries document." FOURTH: "Check code snapshot." ACTION: "Patch the lower-priority doc." ``` Parallel generation MUST NOT be resolved by inventing a compromise. It must be resolved by source priority. --- ## 6. Drift Types to Prevent The following drift types are explicitly forbidden. --- ### 6.1 Route Drift Route drift occurs when a generated document invents or prioritizes routes that do not match the current frontend. Forbidden examples: ```txt /kialo /kintsugi /platforms/konnaxion/ethikos/kintsugi /api/deliberation/* /api/kialo/* ``` Canonical implementation routes: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` --- ### 6.2 Backend App Drift Backend app drift occurs when a generated document creates new backend apps without need. Forbidden first-pass apps: ```txt konnaxion.kialo konnaxion.kintsugi konnaxion.considerit konnaxion.loomio konnaxion.decidim konnaxion.consul konnaxion.democracyos ``` Canonical backend apps to respect: ```txt konnaxion.ethikos konnaxion.kollective_intelligence konnaxion.ekoh konnaxion.users ``` Kialo-style features MUST extend `konnaxion.ethikos` in first pass. --- ### 6.3 Model Naming Drift Model naming drift occurs when generated docs rename existing models or create duplicate concepts. Existing models MUST remain: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` Forbidden replacements: ```txt Claim instead of EthikosArgument DebatePost instead of EthikosArgument Opinion instead of EthikosStance KialoDiscussion instead of EthikosTopic ``` Allowed conceptual mappings: ```txt Kialo Discussion -> EthikosTopic Kialo Thesis -> EthikosTopic prompt/title/description Kialo Claim -> EthikosArgument Kialo Pro/Con edge -> EthikosArgument.parent + EthikosArgument.side ``` --- ### 6.4 Vote Semantics Drift Vote semantics drift occurs when different vote types are merged. The following MUST remain separate. | Type | Owner | Level | Range / Form | Meaning | | -------------------- | ------------- | --------------------- | ----------------- | ------------------------------- | | `EthikosStance` | Korum | Topic | `-3..+3` | User stance on topic | | `ArgumentImpactVote` | Korum | Argument/claim | `0..4` | Impact of a claim on its parent | | `BallotEvent` | Konsultations | Consultation/decision | Protocol-specific | Formal decision input | | `ReadingResult` | Smart Vote | Derived result | Lens-specific | Published derived aggregation | Forbidden equivalences: ```txt ArgumentImpactVote = EthikosStance ArgumentImpactVote = BallotEvent ReadingResult = source fact EkoH snapshot = vote ``` --- ### 6.5 Ownership Drift Ownership drift occurs when a document assigns responsibility to the wrong layer. Correct ownership: ```txt Korum: - topics - arguments - argument graph - topic-level stances - debate moderation Konsultations: - intake - consultations - ballots - result snapshots - impact tracking Smart Vote: - derived readings - lens declarations - aggregations - result publication EkoH: - expertise context - ethics context - cohort eligibility - snapshot context ``` Forbidden ownership changes: ```txt Smart Vote owns source ballots EkoH owns votes KeenKonnect owns Ethikos impact truth Foreign OSS tools write Korum core tables Foreign OSS tools write Konsultations core tables ``` --- ### 6.6 OSS Scope Drift OSS scope drift occurs when deferred sources are reintroduced into first-pass implementation. First-pass sources: ```txt Consider.it Kialo-style argument mapping Loomio Citizen OS Decidim CONSUL Democracy DemocracyOS ``` Deferred sources: ```txt Polis LiquidFeedback All Our Ideas Your Priorities OpenSlides ``` Deferred means: * may receive public credit; * may be mentioned as future inspiration; * must not drive first-pass data models; * must not drive first-pass routes; * must not become an implementation dependency. --- ### 6.7 API Drift API drift occurs when generated docs create endpoints that bypass current contracts. Canonical current endpoints: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ /api/kollective/votes/ ``` Compatibility aliases: ```txt /api/deliberate/... /api/deliberate/elite/... ``` Problematic legacy prefix: ```txt /api/home/* ``` Rules: * Do not expand `/api/home/*`. * Do not rename `/api/ethikos/*` to `/api/deliberation/*`. * Do not introduce GraphQL for core Ethikos CRUD in this upgrade. * Do not bypass the frontend service layer. --- ### 6.8 Frontend Shell Drift Frontend shell drift occurs when generated pages create layout systems outside the existing module shell. Rules: ```txt Use existing global layout. Use existing Ethikos shell. Do not create a second Ethikos shell. Do not create a Kintsugi shell. Do not create a Kialo shell. Do not create a second theme system. Do not duplicate top-level navigation. ``` Kialo-style UX must live under: ```txt /ethikos/deliberate/* ``` --- ### 6.9 Backlog Drift Backlog drift occurs when a planning document starts creating implementation tasks prematurely. Only the following document may define backlog template structure: ```txt 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` Implementation tasks MUST be generated only after: 1. documentation contracts are stable; 2. code inspection is complete; 3. route/API/model reality is verified; 4. ownership boundaries are confirmed. --- ## 7. Canonical Interpretation of External Sources This section defines how each external source may influence the Kintsugi upgrade. --- ### 7.1 Consider.it Status: ```txt first_pass_mimic ``` Allowed influence: * reason capture; * pro/con comparison; * deliberation compression; * participant reasoning clarity. Forbidden influence: * direct code import; * independent data ownership; * replacement of Korum. Target: ```txt /ethikos/deliberate/* ``` --- ### 7.2 Kialo-Style Argument Mapping Status: ```txt first_pass_mimic ``` Allowed influence: * thesis/claim structure; * argument tree; * pro/con edges; * source attachment; * claim impact voting; * minimap concept; * guided voting concept; * participant roles; * suggestions; * anonymity settings; * perspectives. Forbidden influence: * renaming `EthikosArgument`; * creating `/kialo` routes; * creating `konnaxion.kialo`; * treating claim impact votes as topic stances; * treating claim impact votes as Smart Vote ballots. Target: ```txt /ethikos/deliberate/* ``` --- ### 7.3 Loomio Status: ```txt first_pass_mimic ``` Allowed influence: * proposal lifecycle; * decision protocols; * time-boxed decision flow; * consent/objection patterns; * outcome publication. Forbidden influence: * replacing current auth; * replacing current Ethikos routes; * importing Loomio architecture. Target: ```txt /ethikos/decide/* ``` --- ### 7.4 Citizen OS Status: ```txt first_pass_mimic ``` Allowed influence: * collaborative drafting; * versioning; * amendments; * topic phase progression. Forbidden influence: * direct Etherpad integration in first pass unless separately approved; * replacing Ethikos route structure; * creating a foreign drafting truth source. Target: ```txt Drafting capability under ethiKos, likely connected to /ethikos/decide/* and /ethikos/deliberate/* ``` --- ### 7.5 Decidim Status: ```txt first_pass_mimic ``` Allowed influence: * participatory process phases; * accountability; * admin governance; * public process traceability; * components concept. Forbidden influence: * importing Decidim architecture; * creating a parallel process engine outside Ethikos; * overriding current Django/Next architecture. Targets: ```txt /ethikos/impact/* /ethikos/admin/* /ethikos/pulse/* ``` --- ### 7.6 CONSUL Democracy Status: ```txt first_pass_mimic ``` Allowed influence: * eligibility; * thresholds; * proposal gating; * civic participation rules; * administration concepts. Forbidden influence: * importing Rails architecture; * making CONSUL the process owner; * replacing Ethikos/Konsultations ownership. Targets: ```txt /ethikos/decide/* /ethikos/admin/* ``` --- ### 7.7 DemocracyOS Status: ```txt first_pass_mimic ``` Allowed influence: * proposal-centric debate; * policy discussion; * forum/space visibility; * role-based participation. Forbidden influence: * importing Node/Mongo architecture; * replacing Korum; * replacing current proposal/decision route structure. Targets: ```txt /ethikos/decide/* /ethikos/deliberate/* ``` --- ## 8. Source Priority Matrix | Source | Priority | Controls | May Override Code? | May Override Boundaries? | | --------------------- | -------: | ---------------------------------- | ------------------ | ------------------------ | | Current code snapshot | 1 | Implementation reality | Yes | No | | Boundaries document | 2 | Ownership, write rules, legitimacy | No | Yes | | Clean-slate plan | 3 | Execution scope and sequencing | No | No | | Kialo core docs | 4 | Structured deliberation pattern | No | No | | First-pass OSS docs | 5 | Pattern inspiration | No | No | | Older master drafts | 6 | Narrative framing | No | No | --- ## 9. Required Cross-Document References Every generated Kintsugi document SHOULD include a `Related Docs` section. The following references SHOULD be used consistently. ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md ``` Technical documents SHOULD also reference: ```txt 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md ``` --- ## 10. Parallel Generation Rules Because this documentation pack may be generated across multiple AI conversations, the following rules are mandatory. ### 10.1 One File Per Conversation Each parallel conversation MUST generate exactly one assigned file. Do not ask one conversation to generate the entire pack. ### 10.2 Paste Canonical Variables First Each parallel conversation MUST begin with the canonical variables block from: ```txt 04_CANONICAL_NAMING_AND_VARIABLES.md ``` Until that file exists, use the canonical variable block approved in planning. ### 10.3 Do Not Reinterpret Scope Each parallel conversation MUST treat the following as fixed: ```txt FULL_EXTERNAL_MERGE_ALLOWED = false ANNEX_FIRST_PASS_ALLOWED = false IMPLEMENTATION_STYLE = partial_native_mimic PRIMARY_ROUTE_SURFACE = /ethikos/* FIRST_PASS_SCOPE = Consider.it, Kialo-style, Loomio, Citizen OS, Decidim, CONSUL Democracy, DemocracyOS DEFERRED_SCOPE = Polis, LiquidFeedback, All Our Ideas, Your Priorities, OpenSlides ``` ### 10.4 Do Not Generate Backlog Prematurely No generated document may create implementation tasks unless the assigned file is: ```txt 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` Other documents may define requirements, contracts, constraints, mappings, and risks. --- ## 11. AI Drift-Control Checklist Every AI-generated Kintsugi document MUST pass this checklist. ### 11.1 Scope Check * [ ] Does the document keep `partial_native_mimic` as the implementation style? * [ ] Does the document avoid full OSS merge? * [ ] Does the document keep annex/sidecar tools deferred? * [ ] Does the document keep Polis, LiquidFeedback, All Our Ideas, Your Priorities, and OpenSlides out of first pass? ### 11.2 Route Check * [ ] Does the document target `/ethikos/*`? * [ ] Does it avoid `/kialo`, `/kintsugi`, and `/api/deliberation/*`? * [ ] Does it map work to Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin? ### 11.3 Backend Check * [ ] Does the document preserve `konnaxion.ethikos`? * [ ] Does it avoid creating `konnaxion.kialo`? * [ ] Does it preserve `EthikosTopic`, `EthikosStance`, `EthikosArgument`, and `EthikosCategory`? * [ ] Does it use DRF ViewSet/Serializer/Router as the default backend style? ### 11.4 Ownership Check * [ ] Does Korum own arguments and topic stances? * [ ] Does Konsultations own intake, ballots, results, and impact? * [ ] Does Smart Vote own readings only? * [ ] Does EkoH remain context, not voting? ### 11.5 Vote Semantics Check * [ ] Is `EthikosStance` kept distinct from `ArgumentImpactVote`? * [ ] Is `ArgumentImpactVote` kept distinct from `BallotEvent`? * [ ] Is `ReadingResult` kept distinct from source facts? * [ ] Are Smart Vote readings reproducible? ### 11.6 Kialo Check * [ ] Is Kialo treated as native mimic? * [ ] Are Kialo features scoped to `/ethikos/deliberate/*`? * [ ] Is `Claim` mapped conceptually to `EthikosArgument`? * [ ] Are anonymous identities protected? * [ ] Are suggested claims moderated by role? ### 11.7 Frontend Check * [ ] Does the document preserve the existing shell? * [ ] Does it avoid a second theme system? * [ ] Does it use the services layer? * [ ] Does it avoid raw fetch from page components unless explicitly documented? --- ## 12. Invalid Output Patterns The following outputs are invalid and MUST be rejected. ```txt "Create a new /kintsugi app." "Create a new /kialo route family." "Rename EthikosArgument to Claim." "Move Ethikos deliberation to a new konnaxion.kialo backend app." "Use Smart Vote to mutate stances." "Use EkoH as the voting engine." "Import Decidim/Loomio/CONSUL directly into Konnaxion." "Replace /api/ethikos/topics/ with /api/deliberation/topics/." "Implement Polis in first pass." "Use /api/home/* as the new canonical API." "Generate the implementation backlog before code inspection." ``` --- ## 13. Valid Output Patterns The following patterns are valid. ```txt "Map Kialo Claim to EthikosArgument conceptually." "Add ArgumentImpactVote as a separate claim-level vote type." "Keep EthikosStance as topic-level -3..+3 stance." "Use Smart Vote readings as derived, reproducible outputs." "Use EkoH snapshots as context for declared readings." "Extend /ethikos/deliberate/[topic] with argument-tree UX." "Extend /ethikos/decide/results with baseline vs lens readings." "Use Decidim as inspiration for /ethikos/impact/* accountability." "Use CONSUL as inspiration for eligibility and thresholds." "Use Loomio as inspiration for decision lifecycle." "Use Citizen OS as inspiration for drafting/versioning." "Keep all OSS sources as mimic-only in first pass." ``` --- ## 14. Review Procedure Before Generating Any Doc Before generating any file in the Kintsugi documentation pack, perform this review: 1. Identify the assigned filename. 2. Read the canonical variables. 3. Confirm the document’s scope. 4. Confirm which source priorities apply. 5. Confirm whether the doc is: * anti-drift; * strategy; * route/product; * technical contract; * OSS reading plan; * backlog template. 6. Generate only content relevant to that file. 7. Do not redefine global scope unless that is the assigned purpose. 8. Add anti-drift rules. 9. Add related docs. 10. Check against the invalid output patterns. --- ## 15. Non-Goals This document does not: * implement code; * define database migrations in detail; * write serializers; * write frontend services; * fix the Deliberate preview drawer bug; * generate the implementation backlog; * select final UI layouts; * import OSS code; * approve annex/sidecar architecture; * replace the boundaries document; * replace the canonical naming document. --- ## 16. Related Docs This document must be read before generating or using: ```txt 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 17. Final Binding Rule If a future AI-generated answer, document, backlog item, or code proposal conflicts with this document, the generated output MUST be corrected before use. ```yaml FINAL_DRIFT_CONTROL_RULE: IF_A_DOC_CONFLICTS_WITH_THIS_DOCUMENT: RESULT: "this document wins" IF_A_DOC_CONFLICTS_WITH_CODE_REALITY: RESULT: "code snapshot wins for implementation reality" IF_A_DOC_CONFLICTS_WITH_BOUNDARIES: RESULT: "boundaries win for ownership and write rules" IF_AN_OSS_PATTERN_CONFLICTS_WITH_ETHIKOS_ARCHITECTURE: RESULT: "mimic the pattern only; do not import the architecture" IF_KIALO_TERMS_CONFLICT_WITH_ETHIKOS_MODEL_NAMES: RESULT: "preserve Ethikos model names; use Kialo terms conceptually" IF_SMART_VOTE_OR_EKOH_ARE_USED_TO_MUTATE_SOURCE_FACTS: RESULT: "invalid design" IF_THE_OUTPUT_EXPANDS_FIRST_PASS_SCOPE: RESULT: "invalid scope drift" ``` This document is the drift-control root for the ethiKos Kintsugi upgrade. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 5d1c4984dca835a688f131c6c4baf4888b9f38ed5d0bdd6482431a075b2cb99a CONTENT_BYTES: 38639 ================================================================================================ # 03 — Boundaries and Ownership Contracts **Document ID:** `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical / Normative **Last aligned:** 2026-04-25 **Primary purpose:** Prevent architectural drift by fixing ownership, write rules, source-of-truth boundaries, and integration rules for the ethiKos Kintsugi upgrade. --- ## 1. Purpose This document defines the hard boundaries for the ethiKos Kintsugi upgrade. It answers: - Which component owns which truth? - Which component may compute, read, project, or publish? - Which component must never mutate upstream facts? - How do Korum, Konsultations, Smart Vote, EkoH, Kialo-style deliberation, and external OSS patterns coexist without corrupting the architecture? - Which boundaries must AI-assisted implementation never cross? This document is normative. The terms **MUST**, **MUST NOT**, **SHOULD**, **MAY**, and **FORBIDDEN** are intentional. Source basis: the existing Kintsugi boundaries document defines ethiKos v2 as a deliberation and decision-formation module, with a Stage 0→5 pipeline, hard submodule boundaries, Smart Vote/EkoH integration, foreign-tool integration without merges, canonical objects, and audit requirements. :contentReference[oaicite:0]{index=0} --- ## 2. Scope This document applies to the complete ethiKos Kintsugi upgrade. It governs: - Korum - Konsultations - Smart Vote - EkoH - Kollective Intelligence where it intersects with ethiKos - Kialo-style argument mapping under `/ethikos/deliberate/*` - OSS-inspired patterns used through mimic or future annex - Backend model ownership - Frontend route ownership - API/service ownership - Derived readings and result publication - Drafting, decision, and accountability boundaries It does **not** define every model field, serializer shape, frontend component, or implementation task. Those belong to the related technical-contract documents listed near the end. --- ## 3. Canonical Variables Used ```yaml DOCUMENT_NAME: "03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md" DOCUMENT_ROLE: "Canonical ownership and boundary contract" PROJECT_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true DOCS_BEFORE_CODE: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_BACKEND_APP: "konnaxion.ethikos" PRIMARY_API_PREFIX: "/api/ethikos/" KORUM_OWNS: - "topics" - "stances" - "arguments" - "threaded argument graph" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "consultations" - "ballot capture" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "derived readings" - "lens declarations" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "domain vectors" - "snapshot/audit context" FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" KIALO_MODULE_CREATED: false KIALO_CODE_IMPORTED: false ```` --- ## 4. Source Priority When documents, code, old plans, or generated AI output disagree, use this priority order. | Priority | Source | Governs | | -------: | ---------------------------- | ------------------------------------------------------------ | | 1 | Current code snapshot | Real routes, current files, actual models, current endpoints | | 2 | Kintsugi boundaries document | Ownership, write rules, single-truth policy | | 3 | Clean-slate Kintsugi plan | First-pass scope and no-merge strategy | | 4 | Kialo core notes | Structured deliberation behavior under Korum | | 5 | OSS source docs | Pattern inspiration only | | 6 | Older master Kintsugi docs | Strategy only after correcting scope and route reality | The current implementation confirms that the real ethiKos surface is `/ethikos/*`, with first-class page groups for Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin. --- ## 5. Core Principle: Single Truth, Multiple Readings ethiKos legitimacy depends on keeping source facts stable while allowing multiple declared interpretations. ### 5.1 Baseline The **baseline** is the canonical unweighted aggregation of recorded source events. Examples: * raw topic stances * raw consultation ballots * raw participation counts * raw argument graph state The baseline MUST remain visible whenever derived readings are published. ### 5.2 Reading / Lens A **reading** is an explicitly declared transformation, aggregation, filter, or weighting over baseline events. Examples: * cohort-filtered reading * expertise-weighted reading * ethics-adjusted reading * jurisdiction-specific reading * stakeholder-group reading * expert-panel reading Readings are computed by Smart Vote and may use EkoH snapshot context. The boundary source defines a reading/lens as a declared transformation or aggregation computed by Smart Vote and bound to audit context, often an EkoH snapshot. ### 5.3 Reproducibility Rule Every published reading MUST be reproducible. ```txt Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?) ``` A reading that cannot be recomputed from recorded inputs MUST NOT be treated as legitimate output. --- ## 6. Ownership Matrix | Component | Owns source truth? | Owns derived truth? | May mutate upstream facts? | Primary responsibility | | ------------------ | ------------------------: | ------------------------: | -------------------------------------------: | ------------------------------------------------------- | | Korum | Yes | Limited | Yes, only for debate artifacts it owns | Structured debate, topics, stances, arguments | | Konsultations | Yes | Limited | Yes, only for consultation artifacts it owns | Intake, ballots, consultation snapshots, impact | | Smart Vote | No | Yes | No | Readings, lenses, aggregation, result publication | | EkoH | No | Context only | No | Expertise, ethics, eligibility, snapshot context | | Kialo-style layer | No separate truth | No | No | Native deliberation UX pattern inside Korum | | External OSS tools | No | No | No | Inspiration or future sidecar through adapter | | KeenKonnect | No for civic result truth | Handoff only | No | Project/resource execution handoff after civic decision | | KonnectED | No for civic result truth | Learning/resource support | No | Educational resources, learning materials | | Kreative | No for civic result truth | No | No | Creative module, unrelated to civic truth | --- ## 7. Component Boundary Contracts ## 7.1 Korum Contract ### 7.1.1 Role Korum is the structured debate and deliberation submodule inside ethiKos. It owns the canonical debate layer. ### 7.1.2 Korum Owns Korum owns: * debate topics * argument threads * argument graph structure * topic-level stance events * argument moderation * deliberation-specific participation state * Kialo-style claim mapping when implemented natively In the current implementation, this maps to the canonical Ethikos models: * `EthikosTopic` * `EthikosStance` * `EthikosArgument` * `EthikosCategory` The current backend semantics confirm that topics are the main debate/consultation objects, stances store one user’s numeric position on a topic, arguments store threaded discussion entries and replies, and categories group topics thematically. ### 7.1.3 Korum MUST Korum MUST: * preserve `EthikosTopic` as the current canonical topic/debate container; * preserve `EthikosStance` as topic-level stance state; * preserve `EthikosArgument` as the current canonical argument/thread entry; * support Kialo-style structured deliberation through additive fields/tables or service logic; * distinguish topic-level stances from claim-level impact votes; * expose debate artifacts through ethiKos API/service contracts; * keep moderation actions auditable. ### 7.1.4 Korum MUST NOT Korum MUST NOT: * become the Smart Vote aggregation engine; * publish weighted outcomes directly; * mutate Smart Vote readings; * mutate EkoH expertise or ethics snapshots; * absorb Konsultations ballot truth without a declared boundary; * rename `EthikosArgument` to `Claim`; * create a separate `konnaxion.kialo` backend app in the first pass. --- ## 7.2 Konsultations Contract ### 7.2.1 Role Konsultations is the consultation, intake, ballot, and accountability submodule inside ethiKos. It owns the canonical consultation layer. ### 7.2.2 Konsultations Owns Konsultations owns: * issue intake * citizen suggestions * deduplication and scoping * consultation prompts * ballot capture * result snapshots * impact tracking * feedback loops * accountability records ### 7.2.3 Konsultations MUST Konsultations MUST: * preserve raw consultation input separately from derived readings; * make result snapshots auditable; * keep intake and ballot events reproducible; * provide handoff points to Smart Vote for reading computation; * provide handoff points to Impact for accountability; * remain inside ethiKos ownership, even when UI surfaces interact with other modules. ### 7.2.4 Konsultations MUST NOT Konsultations MUST NOT: * let Smart Vote mutate ballots; * let EkoH mutate ballots; * let external OSS tools write directly into consultation truth tables; * let KeenKonnect become the owner of civic impact truth; * merge citizen suggestions, formal ballots, and argument stances into one ambiguous vote object. --- ## 7.3 Smart Vote Contract ### 7.3.1 Role Smart Vote is the derived reading, aggregation, and result-publication layer. It belongs to Kollective Intelligence but is used by ethiKos to publish interpretable outcomes. The Kintsugi plan defines Smart Vote as a common reading layer that allows civic input to be compared, audited, analyzed through multiple lenses, and displayed without forcing a single “correct” outcome. ### 7.3.2 Smart Vote Owns Smart Vote owns: * `LensDeclaration` * `ReadingResult` * derived aggregations * baseline result publication * weighted result publication * cohort-filtered readings * result comparison payloads * reading audit metadata ### 7.3.3 Smart Vote MUST Smart Vote MUST: * read upstream events from Korum and/or Konsultations; * compute readings from immutable or versioned inputs; * store required audit metadata; * publish baseline and derived readings separately; * expose all weighting/filtering assumptions; * preserve reproducibility. Each published reading MUST include at minimum: ```yaml reading_key: "string" lens_hash: "content-addressable stable hash" snapshot_ref: "nullable string; required when EkoH context is used" computed_at: "ISO-8601 timestamp" topic_id_or_consultation_id: "integer or stable reference" results_payload: "JSON snapshot" ``` The boundaries source requires `reading_key`, `lens_hash`, `snapshot_ref`, `computed_at`, `topic/consultation_id`, and `results_payload` for each published reading. ### 7.3.4 Smart Vote MUST NOT Smart Vote MUST NOT: * mutate Korum source records; * mutate Konsultations source records; * hide the raw baseline; * silently replace baseline outcomes with weighted readings; * treat EkoH weighting as automatically legitimate without lens declaration; * store unexplained or unreproducible result transformations; * become the owner of raw votes, raw stances, raw arguments, or raw ballots. --- ## 7.4 EkoH Contract ### 7.4.1 Role EkoH provides expertise, ethics, cohort, and audit context. EkoH is not the voting engine. The boundaries source explicitly states that EkoH owns expertise/ethics ledger context, domain vectors, ethics multipliers, cohort eligibility, and snapshot/audit context, but is not the voting engine. ### 7.4.2 EkoH Owns EkoH owns: * expertise profiles * domain vectors * ethics context * cohort eligibility * credibility signals * snapshot references * audit context for weighted readings ### 7.4.3 EkoH MAY EkoH MAY: * provide `snapshot_ref` for Smart Vote readings; * provide cohort eligibility signals; * provide expertise-weighting context; * provide ethics-adjustment context; * provide trust markers for `/ethikos/trust/*`; * support explainability in `/ethikos/insights`. ### 7.4.4 EkoH MUST NOT EkoH MUST NOT: * record civic votes as the source of truth; * mutate Ethikos stances; * mutate consultation ballots; * mutate Smart Vote readings after publication; * decide outcomes directly; * become a substitute for transparent decision protocols. --- ## 7.5 Kialo-Style Argument Mapping Contract ### 7.5.1 Role Kialo-style argument mapping is the canonical structured-deliberation UX reference for Korum. It is not a separate product module. The Kialo core corpus adds deliberation patterns such as claim creation, sources, voting visibility, background info, perspectives, discussion roles, anonymity, suggested claims, and discussion lifecycle controls. ### 7.5.2 Mapping | Kialo-style concept | ethiKos/Korum mapping | | ------------------- | --------------------------------------------------- | | Discussion | `EthikosTopic` | | Thesis | Topic title / prompt / future thesis field | | Claim | `EthikosArgument` | | Pro/con relation | `EthikosArgument.parent` + `EthikosArgument.side` | | Source | `ArgumentSource` | | Impact vote | `ArgumentImpactVote` | | Suggested claim | `ArgumentSuggestion` | | Participant role | `DiscussionParticipantRole` | | Perspective | `DiscussionPerspective` or declared reading context | | Background info | Topic prompt/context block | ### 7.5.3 Kialo-Style Layer MUST The Kialo-style layer MUST: * live under `/ethikos/deliberate/*`; * extend Korum natively; * preserve `EthikosArgument` as the backend model name; * distinguish `ArgumentImpactVote` from `EthikosStance`; * distinguish claim-level evidence from topic-level background information; * support role-aware suggestions before publishing suggested claims; * preserve author visibility and vote visibility boundaries. ### 7.5.4 Kialo-Style Layer MUST NOT The Kialo-style layer MUST NOT: * create `/kialo` routes; * create `konnaxion.kialo`; * import Kialo code; * rename `EthikosArgument` to `Claim`; * treat impact votes as topic stances; * treat impact votes as Smart Vote ballots; * expose anonymous identities to normal participants. --- ## 7.6 Drafting Contract ### 7.6.1 Role Drafting converts deliberation and consultation outputs into text that can be reviewed, amended, and decided upon. Drafting is a bounded ethiKos capability. ### 7.6.2 Drafting Owns Drafting owns: * `Draft` * `DraftVersion` * `Amendment` * `RationalePacket` * version history * amendment metadata * linkage from arguments or consultations to text ### 7.6.3 Drafting MUST Drafting MUST: * be additive; * preserve the source debate/consultation artifacts; * link back to supporting arguments, ballot events, and rationale; * maintain version history; * preserve author and reviewer audit state. ### 7.6.4 Drafting MUST NOT Drafting MUST NOT: * overwrite Korum arguments; * overwrite Konsultations ballots; * treat drafted text as an outcome until a decision protocol closes; * collapse debate, drafting, and decision into one opaque object. --- ## 7.7 Impact / Accountability Contract ### 7.7.1 Role Impact tracks what happened after a decision or consultation result. Impact belongs to the ethiKos/Konsultations accountability truth, even when execution handoff points connect to KeenKonnect or other modules. ### 7.7.2 Impact Owns Impact owns: * `ImpactTrack` * `ImpactUpdate` * public progress status * outcome explanations * implementation feedback * accountability snapshots ### 7.7.3 Impact MUST Impact MUST: * remain linked to decision records and result snapshots; * distinguish planned, in-progress, blocked, completed, cancelled, and archived outcomes; * preserve public accountability history; * identify handoffs to execution/project modules without making those modules the civic truth owner. ### 7.7.4 Impact MUST NOT Impact MUST NOT: * treat KeenKonnect project state as the canonical civic outcome by default; * overwrite decision records; * hide cancelled or blocked outcomes; * publish impact claims without source linkage. The endpoint graph currently shows loose mappings between impact services and KeenKonnect projects, which means Kintsugi must clarify ownership rather than silently adopting KeenKonnect as the impact truth owner. --- ## 7.8 External OSS Tool Contract ### 7.8.1 Role External OSS tools are pattern sources. They are not merged into the ethiKos core during the first pass. ### 7.8.2 First-Pass Strategy The first-pass strategy is **native mimic**. First-pass sources: * Consider.it * Kialo-style argument mapping * Loomio * Citizen OS * Decidim * CONSUL Democracy * DemocracyOS Deferred sources: * Polis * LiquidFeedback * All Our Ideas * Your Priorities * OpenSlides ### 7.8.3 Mimic Use **Mimic** when: * Konnaxion needs sovereignty; * UX coherence matters; * source stack is incompatible; * source license or architecture is invasive; * the useful value is a pattern rather than a reusable component; * native ethiKos truth should remain canonical. ### 7.8.4 Annex Use **Annex** only when: * the tool can run as a sidecar; * the component is replaceable; * the license is acceptable; * no dual truth is introduced; * no direct core-table writes occur; * an adapter boundary exists. ### 7.8.5 Annex Adapter Requirements Any future annex MUST use: ```yaml ExternalArtifact: role: "append-only raw external payload with provenance" ProjectionMapping: role: "mapping from external identifiers to internal canonical IDs" ``` The existing boundaries document requires annex integrations to use `ExternalArtifact`, `ProjectionMapping`, and optional projections through ethiKos services rather than direct database writes. ### 7.8.6 External Tools MUST NOT External tools MUST NOT: * write directly to Korum core tables; * write directly to Konsultations core tables; * become source of truth for civic outcomes; * bypass ethiKos services; * bypass Smart Vote reading contracts; * bypass EkoH snapshot/audit boundaries; * replace the existing `/ethikos/*` route families. --- ## 8. Pipeline Ownership ethiKos Kintsugi uses a staged workflow. Each stage must have a clear owner and reusable output. | Stage | Name | Owner | Canonical outputs | | ----: | ------------------------ | ----------------------------- | -------------------------------------------------------------- | | 0 | Intake | Konsultations | `ProblemStatement`, `IntakeQueue`, `TopicTags` | | 1 | Discovery / Consultation | Konsultations | `OptionSet`, `ConstraintSet`, consultation landscape | | 2 | Deliberation | Korum | `ArgumentGraph`, `StanceEvents`, `ModerationLog` | | 3 | Drafting | ethiKos bounded capability | `Draft`, `DraftVersion`, `Amendment`, `RationalePacket` | | 4 | Decision | Smart Vote + protocol context | `BaselineResult`, `ReadingResult`, `DecisionRecord` | | 5 | Accountability | Konsultations / Impact | `ImpactTrack`, `ImpactUpdate`, public accountability snapshots | The original boundaries document defines ethiKos as a workflow kernel where each stage produces reusable output. --- ## 9. Current Implementation Boundary The current implementation must be respected. ### 9.1 Current Backend Core Current canonical Ethikos backend app: ```txt konnaxion.ethikos ``` Current canonical models: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` Current canonical endpoints: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` Compatibility aliases: ```txt /api/deliberate/... /api/deliberate/elite/... ``` The module contracts and technical references confirm these endpoints and models as the current canonical backend scope. ### 9.2 Current Frontend Surface Current canonical implementation surface: ```txt /ethikos/* ``` Implemented page groups: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` ### 9.3 Compatibility Rule Older conceptual route references MAY remain as documentation references, but implementation planning MUST target the real `/ethikos/*` route surface. --- ## 10. Write Rules ## 10.1 Core Table Writes Only the owning component may write to its source truth. | Table/Object family | Owner | Who may write | | ------------------- | -------------------- | --------------------------------------- | | `EthikosTopic` | Korum / ethiKos | ethiKos services | | `EthikosStance` | Korum | ethiKos stance services | | `EthikosArgument` | Korum | ethiKos argument services | | `EthikosCategory` | ethiKos | ethiKos admin/category services | | Ballot events | Konsultations | consultation services | | Result snapshots | Konsultations | consultation/result services | | `LensDeclaration` | Smart Vote | Smart Vote services | | `ReadingResult` | Smart Vote | Smart Vote compute/publication services | | EkoH snapshots | EkoH | EkoH services | | `ExternalArtifact` | Integration boundary | adapter services only | | `ProjectionMapping` | Integration boundary | adapter services only | ## 10.2 Direct DB Write Rule Direct cross-domain writes are forbidden. ```yaml KORUM_WRITES_SMART_VOTE_TABLES: false SMART_VOTE_WRITES_KORUM_TABLES: false SMART_VOTE_WRITES_KONSULTATIONS_TABLES: false EKOH_WRITES_VOTE_TABLES: false FOREIGN_TOOLS_WRITE_CORE_TABLES: false ``` ## 10.3 Service Boundary Rule All writes SHOULD pass through the owning service/API layer. Direct model imports across apps for mutation SHOULD be avoided unless explicitly documented and tested. --- ## 11. Vote-Type Separation The Kintsugi upgrade MUST preserve three distinct participation/result concepts. | Concept | Owner | Level | Range / Form | Meaning | | -------------------- | ---------- | -------------------- | ---------------------- | ------------------------------------------------------ | | `EthikosStance` | Korum | Topic-level | `-3..+3` | User stance on a topic | | `ArgumentImpactVote` | Korum | Claim/argument-level | `0..4` | Impact of a claim on parent; relevance/veracity signal | | `ReadingResult` | Smart Vote | Derived aggregation | JSON / declared schema | Published interpretation of baseline events | ## 11.1 Hard Rules ```yaml CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false ``` ## 11.2 Why This Matters If these concepts are merged, ethiKos loses auditability. Examples of forbidden drift: * using a Kialo-style impact vote as a topic stance; * using a topic stance as a ballot; * treating a weighted reading as raw truth; * hiding the unweighted baseline after publishing a weighted result. --- ## 12. Route Ownership ## 12.1 Canonical Product Surface The canonical ethiKos product surface is: ```txt /ethikos/* ``` ## 12.2 Route Family Ownership | Route family | Primary owner | Boundary role | | ----------------------- | ------------------------------ | --------------------------------------- | | `/ethikos/deliberate/*` | Korum | Debate, arguments, claim graph, stances | | `/ethikos/decide/*` | Smart Vote + decision protocol | Ballots, protocols, readings, results | | `/ethikos/impact/*` | Konsultations / Impact | Accountability, outcomes, feedback | | `/ethikos/pulse/*` | ethiKos analytics | Participation health, signals, trends | | `/ethikos/trust/*` | EkoH visibility | Trust, credentials, expertise markers | | `/ethikos/admin/*` | ethiKos governance | Moderation, roles, audit | | `/ethikos/learn/*` | ethiKos education | Guides, methodology, glossary | | `/ethikos/insights` | Smart Vote/EkoH interpretation | Readings, analytics, comparisons | ## 12.3 Route Anti-Drift Rules The upgrade MUST NOT: * create a separate `/kialo` product route; * create a top-level `/kintsugi` app outside ethiKos; * replace `/ethikos/deliberate/*` with `/debate`; * replace `/ethikos/decide/*` with `/vote`; * expand `/api/home/*`; * rename `/api/ethikos/...` to `/api/deliberation/...`. The project guidance explicitly instructs API generation to use the service layer, respect `/api/...` prefixes, avoid invented API paths, and avoid renaming `/api/ethikos/...` to `/api/deliberation/...`. --- ## 13. API Ownership ## 13.1 Canonical API Prefixes ```yaml ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" ``` ## 13.2 Compatibility Prefixes ```yaml DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." ``` ## 13.3 Legacy / Problematic Prefixes ```yaml API_HOME_PREFIX: "/api/home/*" RULE: "Do not expand usage. Replace, isolate, or mark legacy." ``` ## 13.4 API Boundary Rule Frontend code MUST use service wrappers for new or changed API calls. Pages and components SHOULD NOT call raw endpoints directly unless that exception is explicitly documented in the appropriate frontend/API contract. --- ## 14. Data Boundary Rules ## 14.1 Existing Models Must Remain Stable The Kintsugi upgrade MUST NOT rename or remove: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` ## 14.2 Additive Model Policy New capabilities SHOULD be added through non-breaking tables or fields. Allowed additive families: ```txt DecisionProtocol DecisionRecord LensDeclaration ReadingResult Draft DraftVersion Amendment RationalePacket ImpactTrack ImpactUpdate ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ExternalArtifact ProjectionMapping ``` ## 14.3 Forbidden Data Changes The upgrade MUST NOT: * delete existing Ethikos tables; * rename existing Ethikos models; * rename existing canonical endpoints; * collapse all civic input into one generic vote model; * store Smart Vote readings in Korum source tables; * store EkoH snapshots as hidden weights without declaration; * store foreign tool payloads directly in core Korum/Konsultations tables. --- ## 15. Moderation, Roles, and Visibility ## 15.1 Moderation Ownership Korum owns moderation for debate artifacts. Konsultations owns moderation for consultation intake and ballot-adjacent content. Admin surfaces under `/ethikos/admin/*` coordinate moderation, roles, and audit. ## 15.2 Kialo-Style Role Alignment Kialo-style roles MAY be mimicked as ethiKos discussion roles: ```txt owner admin editor writer suggester viewer ``` Kialo documentation distinguishes role-based permissions such as Owner, Admin, Editor, Writer, Suggester, and Viewer, which should inform ethiKos deliberation permissions without importing Kialo architecture. ## 15.3 Visibility Controls The Kialo-style deliberation layer MAY support: ```txt AUTHOR_VISIBILITY = never | admins_only | all VOTE_VISIBILITY = all | admins_only | self_only PARTICIPATION_TYPE = standard | anonymous ``` ## 15.4 Anonymity Rule Anonymous participation MAY hide public identity, but it MUST NOT remove auditability for authorized administrators. Anonymous identity MUST NOT be exposed to normal participants. --- ## 16. Audit Requirements Every boundary-crossing event MUST be auditable. ## 16.1 Minimum Audit Targets Audit records SHOULD exist for: * topic creation * topic closure * stance recording * argument creation * argument hiding/unhiding * source attachment * impact vote recording * suggested claim acceptance/rejection * draft version creation * amendment submission * decision opening/closing * reading computation * reading publication * EkoH snapshot usage * impact update * moderation action * external artifact ingestion * projection mapping creation ## 16.2 Minimum Audit Fields Where applicable, audit entries SHOULD include: ```yaml actor_id: "user or system actor" action: "stable action key" object_type: "canonical object type" object_id: "canonical object id" before: "optional JSON" after: "optional JSON" reason: "optional moderation/publication reason" created_at: "ISO-8601 timestamp" source_ref: "optional external/source reference" snapshot_ref: "optional EkoH or state snapshot" ``` --- ## 17. Foreign Tool Boundary ## 17.1 First-Pass Source Role First-pass OSS sources are inspiration only. | Source | First-pass boundary role | | ------------------- | ----------------------------------------------- | | Consider.it | Mimic reason/pro-con capture | | Kialo-style mapping | Mimic structured argument graph and permissions | | Loomio | Mimic proposal lifecycle and decision protocol | | Citizen OS | Mimic drafting and topic-phase patterns | | Decidim | Mimic process/accountability/admin patterns | | CONSUL Democracy | Mimic eligibility/threshold/governance patterns | | DemocracyOS | Mimic proposal-centric policy debate | ## 17.2 Deferred Sources Deferred sources MUST NOT drive first-pass architecture: ```txt Polis LiquidFeedback All Our Ideas Your Priorities OpenSlides ``` ## 17.3 Dependency Rule No first-pass source may become: * a required runtime dependency; * a direct data owner; * a direct database writer; * a new primary frontend shell; * a replacement for ethiKos routes. --- ## 18. Conflict Rules ## 18.1 If Korum and Smart Vote Conflict Korum source facts win for raw deliberation history. Smart Vote may publish a derived reading, but it may not mutate Korum. ## 18.2 If Konsultations and Smart Vote Conflict Konsultations source ballot/result snapshots win for raw consultation history. Smart Vote may publish declared readings, but it may not mutate ballots or snapshots. ## 18.3 If EkoH and Smart Vote Conflict EkoH provides context. Smart Vote computes readings. If EkoH context changes, Smart Vote may compute a new reading with a new `lens_hash` or `snapshot_ref`; it must not silently mutate the old reading. ## 18.4 If OSS Pattern and ethiKos Architecture Conflict ethiKos architecture wins. Mimic the useful pattern. Do not import the incompatible architecture. ## 18.5 If Old Docs and Current Code Conflict Current code wins for implementation reality. Old docs may be retained for strategy only after correction. --- ## 19. Non-Goals This document does not: * define every serializer field; * create implementation tasks; * propose migrations directly; * replace the API contract document; * replace the Smart Vote/EkoH reading contract; * replace the Kialo-style argument mapping contract; * replace the route-by-route upgrade plan; * authorize a full OSS merge; * authorize annex integration in the first pass; * solve the Deliberate preview drawer bug; * authorize any new top-level product app. --- ## 20. Anti-Drift Rules The following are absolute. ```yaml FORBIDDEN: - "Do not propose full external OSS merge." - "Do not create a new Kialo app." - "Do not create a new top-level Kintsugi frontend app." - "Do not rename EthikosArgument to Claim." - "Do not rename /api/ethikos/... to /api/deliberation/..." - "Do not convert EkoH into a voting engine." - "Do not let Smart Vote mutate upstream facts." - "Do not let foreign tools write to Korum/Konsultations core tables." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expand /api/home/*." - "Do not create a second layout shell." - "Do not create a second theme system." - "Do not produce implementation tasks in this document." ``` --- ## 21. Required Contract Blocks for Submodule Pages Each submodule page SHOULD include a short contract block pointing back to this document. ### 21.1 Korum Page Contract Block ```md ## Contract Korum owns ethiKos structured debate truth: topics, stances, arguments, argument graph structure, and debate moderation. Korum does not compute Smart Vote readings, does not mutate EkoH snapshots, and does not own consultation ballots. See: `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`. ``` ### 21.2 Konsultations Page Contract Block ```md ## Contract Konsultations owns ethiKos consultation truth: intake, suggestions, ballots, result snapshots, and impact tracking. Konsultations does not compute Smart Vote readings, does not mutate EkoH snapshots, and does not replace Korum argument truth. See: `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`. ``` ### 21.3 Smart Vote Page Contract Block ```md ## Contract Smart Vote owns derived readings and result publication. It reads baseline events, applies declared lenses, stores reproducible reading results, and keeps the baseline visible. Smart Vote never mutates Korum or Konsultations source facts. See: `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`. ``` ### 21.4 EkoH Page Contract Block ```md ## Contract EkoH owns expertise, ethics, cohort, and snapshot context. It may support Smart Vote readings through declared snapshot references. EkoH is not the voting engine and does not mutate civic source facts. See: `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`. ``` --- ## 22. Related Documents This document should be read with: ```txt 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 04_CANONICAL_NAMING_AND_VARIABLES.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 18_ADR_REGISTER.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 23. Acceptance Criteria This document is complete when future Kintsugi docs and implementation tasks can answer the following without ambiguity: * Who owns this object? * Who can write to it? * Is this source truth or a derived reading? * Is this baseline or lens output? * Is this Korum, Konsultations, Smart Vote, EkoH, or external? * Is this first-pass mimic or future annex? * Does this use the existing `/ethikos/*` route surface? * Does this preserve current models and endpoints? * Does this keep Smart Vote read-only on upstream facts? * Does this keep EkoH out of voting-engine responsibility? * Does this keep Kialo-style features inside Korum rather than creating a separate module? If any answer is unclear, the generating document or implementation task MUST be revised before code work proceeds. --- ## 24. Final Boundary Statement ethiKos Kintsugi is not a merge of civic platforms. It is a native Konnaxion upgrade that preserves a single source of civic truth while allowing multiple declared readings. Korum owns structured debate. Konsultations owns consultation flow and accountability. Smart Vote owns derived readings. EkoH owns expertise and ethics context. Kialo-style deliberation strengthens Korum without becoming a separate module. Foreign tools may inspire, and later may annex through adapters, but they do not own ethiKos truth. The baseline remains visible. The readings remain declared. The system remains auditable. The architecture remains sovereign. --- ## V4.1 addendum — EkoH rating disclosure ownership EkoH owns both its rating ledger and disclosure decisions for that ledger. `ConfidentialitySetting` continues to own identity presentation; `RatingVisibilitySetting` and EkoH scoped grants own rating disclosure. Consuming modules MUST NOT create a parallel rating-visibility policy. Smart Vote remains the owner of derived readings and MUST NOT mutate EkoH ratings. See `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/04_CANONICAL_NAMING_AND_VARIABLES.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 9d42166580537ff6684169fe12983e3aae2237133ef3ac5e0bd2707de1be3b99 CONTENT_BYTES: 38416 ================================================================================================ # 04 — Canonical Naming and Variables **Document ID:** `04_CANONICAL_NAMING_AND_VARIABLES.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical naming contract **Last aligned:** 2026-04-25 **Primary purpose:** prevent naming drift across documentation, frontend, backend, migrations, prompts, and parallel AI-generated files. --- ## 1. Purpose This document defines the canonical names, identifiers, slugs, routes, backend apps, model names, payload names, enum names, and reserved variables for the ethiKos Kintsugi upgrade. Every other Kintsugi documentation file MUST use these names unless it explicitly defines a local alias and maps that alias back to this document. This file exists because the Kintsugi documentation pack may be generated across parallel AI conversations. Without a fixed naming contract, different conversations may independently invent names such as `Deliberation`, `DebatePost`, `VoteLens`, `KialoClaim`, `WeightedTopicResult`, or `/api/deliberation/...`. Those names MUST NOT become canonical unless this document is amended. --- ## 2. Scope This document governs naming for: - product/module names; - submodule names; - Kintsugi strategy variables; - frontend route names; - backend app names; - backend model names; - proposed model names; - API endpoint names; - service-layer names; - Smart Vote and EkoH reading variables; - Kialo-style argument mapping variables; - mimic vs annex variables; - canonical object names; - canonical event names; - enum names and values; - known bug identifiers; - anti-drift constants. This document does **not** define full data schemas, serializers, migrations, UI layouts, or implementation tasks. Those belong to the related documents listed at the end. --- ## 3. Source Priority When naming conflicts occur, apply this priority order: | Priority | Source | Governs | |---:|---|---| | 1 | Code snapshot reality | Existing routes, files, current endpoints, current models, current implementation state | | 2 | Boundaries and ownership contract | Korum/Konsultations/Smart Vote/EkoH ownership, write rules, pipeline | | 3 | Clean-slate Kintsugi plan | First-pass scope, no full merge, docs first, code inspection second | | 4 | Kialo core corpus | Structured deliberation names for `/ethikos/deliberate/*` | | 5 | OSS source docs | Pattern inspiration only | | 6 | Prior master docs | Strategic framing after correcting scope and route reality | If this document conflicts with implementation reality, implementation reality wins for currently existing code names. If this document conflicts with a broader concept document, this document wins for naming. --- ## 4. Canonical Product Names | Concept | Canonical display name | Canonical code/name form | Notes | |---|---|---|---| | Platform | `Konnaxion` | `konnaxion` | Root platform | | Civic module | `ethiKos` | `ethikos` | Preserve stylized display name | | Upgrade | `Kintsugi` | `kintsugi` | Upgrade/program name, not a separate app | | Full upgrade | `ethiKos Kintsugi Upgrade` | `ethikos_kintsugi_upgrade` | Documentation pack/program | | Documentation pack | `ethiKos Kintsugi Update Documentation Pack` | `kintsugi_doc_pack` | Pack name | | Debate submodule | `Korum` | `korum` | Debate/argumentation ownership label | | Consultation submodule | `Konsultations` | `konsultations` | Intake/consultation/impact ownership label | | Decision/readings layer | `Smart Vote` | `smartvote` / `SmartVote` | UI text uses two words | | Expertise/ethics layer | `EkoH` | `ekoh` | Preserve capitalization | | Voting app | `Kollective Intelligence` | `kollective_intelligence` | Existing backend app name | | Collaboration module | `KeenKonnect` | `keenkonnect` | Existing platform module | | Learning/certification module | `KonnectED` | `konnected` | Existing platform module | | Creative module | `Kreative` | `kreative` | Existing platform module | --- ## 5. Global Strategy Variables ```yaml KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_ETHIKOS_FRAME_STABLE: true DOCS_BEFORE_CODE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true GENERATE_ONE_FILE_PER_PARALLEL_CONVERSATION: true ```` ### Meaning * `documentation-first architecture upgrade` means the docs define contracts before implementation backlog. * `partial native mimic` means selected external patterns are reimplemented natively inside ethiKos. * `FULL_EXTERNAL_MERGE_ALLOWED = false` forbids merging entire external civic platforms into the current Konnaxion stack. * `ANNEX_FIRST_PASS_ALLOWED = false` means first pass does not create sidecar integrations. * `EXISTING_ROUTE_FAMILIES_STABLE = true` means the current `/ethikos/*` route families remain the product surface. --- ## 6. First-Pass OSS Scope Variables ```yaml FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ``` ### Per-source status ```yaml OSS_SOURCE_STATUS: CONSIDER_IT: "first_pass_mimic" KIALO_STYLE: "first_pass_mimic" LOOMIO: "first_pass_mimic" CITIZEN_OS: "first_pass_mimic" DECIDIM: "first_pass_mimic" CONSUL_DEMOCRACY: "first_pass_mimic" DEMOCRACY_OS: "first_pass_mimic" POLIS: "deferred_public_credit_only" LIQUID_FEEDBACK: "deferred_public_credit_only" ALL_OUR_IDEAS: "deferred" YOUR_PRIORITIES: "deferred" OPENSLIDES: "deferred_possible_future_annex" ``` ### Naming rule External project names MAY appear in inspiration or matrix sections. They MUST NOT become Konnaxion route names, backend app names, or database namespaces in the first pass. Forbidden first-pass examples: ```txt /kialo /api/kialo/... konnaxion.kialo PolisEngine LiquidFeedbackVote OpenSlidesSession ``` --- ## 7. Ownership Variables ```yaml KORUM_OWNS: - "Ethikos topics used as debate/deliberation containers" - "Arguments" - "Threaded argument graph" - "Topic-level stance events" - "Moderation on debate artifacts" KONSULTATIONS_OWNS: - "Intake" - "Consultations" - "Citizen suggestions" - "Ballot capture" - "Result snapshots" - "Impact tracking" SMART_VOTE_OWNS: - "Derived readings" - "Lens declarations" - "Aggregations" - "Result publication" EKOH_OWNS: - "Expertise context" - "Ethics context" - "Cohort eligibility" - "Domain vectors" - "Snapshot and audit context" ``` ### Ownership rule Korum and Konsultations are ethiKos ownership domains. Smart Vote and EkoH interact with them through declared readings, snapshots, context, and derived artifacts. They MUST NOT mutate upstream debate or ballot facts. --- ## 8. Write-Rule Variables ```yaml FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_KORUM_RECORDS: false SMART_VOTE_MUTATES_KONSULTATIONS_RECORDS: false SMART_VOTE_WRITES_ONLY_DERIVED_ARTIFACTS: true EKOH_IS_VOTING_ENGINE: false EKOH_MUTATES_VOTES: false WEIGHTED_OUTCOME_REQUIRES_REPRODUCIBILITY: true READING_FORMULA: "Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?)" ``` ### Meaning * Foreign tools may be inspiration sources or future annexes. * Foreign tools MUST NOT write directly into Korum or Konsultations core tables. * Smart Vote writes readings, not facts. * EkoH supplies context, not votes. * Weighted or filtered outcomes must be reproducible from declared inputs. --- ## 9. Current Backend App Variables ```yaml BACKEND: ROOT_PACKAGE: "backend" DJANGO_PROJECT: "config" ROOT_URLCONF: "config.urls" API_ROUTER_FILE: "config/api_router.py" AUTH_USER_MODEL: "users.User" DEFAULT_API_STYLE: "Django REST Framework ViewSet + Serializer + Router" BACKEND_APPS: USERS_APP: "konnaxion.users" ETHIKOS_APP: "konnaxion.ethikos" KOLLECTIVE_INTELLIGENCE_APP: "konnaxion.kollective_intelligence" KEENKONNECT_APP: "konnaxion.keenkonnect" KONNECTED_APP: "konnaxion.konnected" KREATIVE_APP: "konnaxion.kreative" ``` ### Backend naming rules * Use `users.User`, never `auth.User`. * Use `konnaxion.ethikos`, not `konnaxion.deliberation`. * Use `konnaxion.kollective_intelligence`, not `konnaxion.smartvote` for the existing voting app. * Do not create `konnaxion.kialo` in first pass. * Do not rename existing apps. --- ## 10. Current Frontend Route Variables ```yaml FRONTEND: FRAMEWORK: "Next.js App Router" PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_LAYOUT_RULE: "All ethiKos pages remain inside the existing Ethikos/global shell." DO_NOT_CREATE_SECOND_SHELL: true DO_NOT_CREATE_KIALO_ROUTE_FAMILY: true DO_NOT_CREATE_KINTSUGI_TOP_LEVEL_APP: true USE_SERVICES_LAYER: true ``` ### Current ethiKos route families ```yaml ETHIKOS_ROUTE_FAMILIES: DECIDE: PREFIX: "/ethikos/decide/*" ROUTES: - "/ethikos/decide/elite" - "/ethikos/decide/public" - "/ethikos/decide/results" - "/ethikos/decide/methodology" DELIBERATE: PREFIX: "/ethikos/deliberate/*" ROUTES: - "/ethikos/deliberate/elite" - "/ethikos/deliberate/[topic]" - "/ethikos/deliberate/guidelines" TRUST: PREFIX: "/ethikos/trust/*" ROUTES: - "/ethikos/trust/profile" - "/ethikos/trust/badges" - "/ethikos/trust/credentials" PULSE: PREFIX: "/ethikos/pulse/*" ROUTES: - "/ethikos/pulse/overview" - "/ethikos/pulse/live" - "/ethikos/pulse/health" - "/ethikos/pulse/trends" IMPACT: PREFIX: "/ethikos/impact/*" ROUTES: - "/ethikos/impact/feedback" - "/ethikos/impact/outcomes" - "/ethikos/impact/tracker" LEARN: PREFIX: "/ethikos/learn/*" ROUTES: - "/ethikos/learn/changelog" - "/ethikos/learn/glossary" - "/ethikos/learn/guides" INSIGHTS: PREFIX: "/ethikos/insights" ROUTES: - "/ethikos/insights" ADMIN: PREFIX: "/ethikos/admin/*" ROUTES: - "/ethikos/admin/audit" - "/ethikos/admin/moderation" - "/ethikos/admin/roles" ``` ### Route interpretation variables ```yaml PRIMARY_DELIBERATION_ROUTE: "/ethikos/deliberate/*" PRIMARY_DECISION_ROUTE: "/ethikos/decide/*" PRIMARY_IMPACT_ROUTE: "/ethikos/impact/*" PRIMARY_ADMIN_ROUTE: "/ethikos/admin/*" PRIMARY_TRUST_ROUTE: "/ethikos/trust/*" PRIMARY_PULSE_ROUTE: "/ethikos/pulse/*" PRIMARY_LEARN_ROUTE: "/ethikos/learn/*" PRIMARY_INSIGHTS_ROUTE: "/ethikos/insights" ``` ### Route anti-drift rules Do not replace the implemented route surface with older conceptual routes such as: ```txt /debate /consult /reputation /platforms/konnaxion/ethikos/korum /platforms/konnaxion/ethikos/konsultations /platforms/konnaxion/ethikos/kintsugi ``` Those may be referenced as conceptual/public-doc surfaces, but the implementation upgrade targets `/ethikos/*`. --- ## 11. Current API Endpoint Variables ```yaml API_BASE: "/api/" CURRENT_ENDPOINTS_CANONICAL: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" CURRENT_ENDPOINTS_COMPATIBILITY: DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." LEGACY_OR_PROBLEMATIC_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" ``` ### Endpoint naming rules * Use `/api/ethikos/topics/`, not `/api/deliberation/topics/`. * Use `/api/ethikos/arguments/`, not `/api/claims/`. * Use `/api/kollective/votes/` for the current Kollective vote API. * Do not expand `/api/home/*`. * Compatibility aliases may be documented but should not become the preferred canonical API surface. --- ## 12. Current Backend Model Variables ```yaml CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_ETHIKOS_MODEL_SEMANTICS: EthikosCategory: "Topic grouping." EthikosTopic: "Main debate / consultation prompt container." EthikosStance: "Per-user numeric topic-level stance constrained to -3..+3." EthikosArgument: "Threaded discussion entry; may have parent and pro/con side." ``` ### Current model naming rules * `EthikosTopic` remains the canonical current topic/discussion container. * `EthikosArgument` remains the canonical current argument/claim record. * `EthikosStance` remains topic-level stance, not argument-level impact voting. * `EthikosCategory` remains the topic grouping model. * Do not rename `EthikosArgument` to `Claim`. * Do not rename `EthikosTopic` to `Discussion`. * Conceptual aliases are allowed only when explicitly mapped. --- ## 13. Current Model Field Semantics ```yaml ETHIKOS_TOPIC_FIELDS_CANONICAL: - "title" - "description" - "status" - "category" - "created_by" - "total_votes" - "last_activity" - "created_at" - "updated_at" - "expertise_category" ETHIKOS_TOPIC_STATUS_VALUES: - "open" - "closed" - "archived" ETHIKOS_STANCE_FIELDS_CANONICAL: - "user" - "topic" - "value" - "timestamp" ETHIKOS_STANCE_VALUE_RANGE: "-3..+3" ETHIKOS_STANCE_UNIQUENESS: "one stance per user/topic" ETHIKOS_ARGUMENT_FIELDS_CANONICAL: - "topic" - "user" - "content" - "side" - "parent" - "is_hidden" - "created_at" - "updated_at" ETHIKOS_ARGUMENT_SIDE_VALUES: - "pro" - "con" - "neutral" ETHIKOS_CATEGORY_FIELDS_CANONICAL: - "name" - "description" ``` --- ## 14. Proposed New Model Names The following names are reserved for future Kintsugi implementation planning. They are not necessarily implemented yet. ```yaml PROPOSED_NEW_MODELS: DECISION: - "DecisionProtocol" - "DecisionRecord" - "EligibilityRule" SMART_VOTE_READING: - "LensDeclaration" - "ReadingResult" DRAFTING: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" IMPACT: - "ImpactTrack" - "ImpactUpdate" EXTERNAL_TOOL_BOUNDARY: - "ExternalArtifact" - "ProjectionMapping" KIALO_STYLE: - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "ArgumentLink" - "ArgumentBookmark" - "DiscussionPerspective" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" - "DiscussionExport" ``` ### First-pass model priority ```yaml FIRST_PASS_MODEL_PRIORITY: MUST_CONSIDER: - "DecisionProtocol" - "DecisionRecord" - "LensDeclaration" - "ReadingResult" - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" - "ImpactTrack" - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" DEFER: - "ArgumentBookmark" - "ArgumentLink" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionPerspective" - "DiscussionExport" ``` ### Proposed model naming rules * Proposed models MUST be additive. * Proposed models MUST NOT replace current core models. * Proposed models MUST NOT require destructive migrations to existing Ethikos tables. * Proposed models MUST be confirmed in `08_DATA_MODEL_AND_MIGRATION_PLAN.md` before implementation. --- ## 15. Canonical Kialo-Style Naming Variables Kialo-style naming is conceptual and belongs under Korum / Deliberate. It does not create a separate Kialo module. ```yaml KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ROLE_IN_KINTSUGI: "Canonical structured deliberation UX reference for Korum." ``` ### Kialo-style canonical mapping ```yaml KIALO_CANONICAL_MAPPING: KIALO_DISCUSSION: "EthikosTopic" KIALO_THESIS: "Topic thesis/prompt field; current fallback is EthikosTopic.title + EthikosTopic.description" KIALO_CLAIM: "EthikosArgument" KIALO_PRO_CON_EDGE: "EthikosArgument.parent + EthikosArgument.side" KIALO_SOURCE: "ArgumentSource" KIALO_IMPACT_VOTE: "ArgumentImpactVote" KIALO_SUGGESTED_CLAIM: "ArgumentSuggestion" KIALO_PERSPECTIVE: "DiscussionPerspective or Smart Vote lens depending context" KIALO_PARTICIPANT_ROLE: "DiscussionParticipantRole" ``` ### Kialo-style value constants ```yaml KIALO_EDGE_SIDE_VALUES: - "pro" - "con" - "neutral" KIALO_IMPACT_VOTE_RANGE: "0..4" KIALO_IMPACT_VOTE_MEANING: "veracity + relevance to parent" KIALO_IMPACT_VOTE_IS_TOPIC_STANCE: false KIALO_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false KIALO_ROLES: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" KIALO_ANONYMITY_MODES: - "standard" - "anonymous" KIALO_AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" KIALO_VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" KIALO_DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" KIALO_MINIMAP_MODES: - "tree" - "sunburst" ``` ### Kialo-style first-pass features ```yaml KIALO_FIRST_PASS_FEATURES: - "Argument tree using current EthikosArgument parent + side" - "Claim/source links" - "Role-aware suggested claims" - "Impact vote separated from topic stance" - "Author visibility settings" - "Voting visibility settings" - "Basic topic info/background panel" ``` ### Kialo-style deferred features ```yaml KIALO_DEFERRED_FEATURES: - "Small group mode" - "Sunburst minimap" - "Clone-from-template" - "Export discussion" - "Custom perspectives" - "Claim extraction into new discussion" - "Move/link claim across discussions" ``` ### Kialo anti-drift rules ```yaml KIALO_ANTI_DRIFT_RULES: - "Do not rename EthikosArgument to Claim." - "Do not create konnaxion.kialo." - "Do not create /kialo routes." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expose anonymous identities to normal participants." - "Do not publish suggested claims without approval when role is suggester." ``` --- ## 16. Vote-Type Naming Variables There are three distinct vote/reading concepts. They MUST NOT be merged. ```yaml VOTE_TYPE_SEPARATION: ETHIKOS_STANCE: MODEL: "EthikosStance" RANGE: "-3..+3" LEVEL: "topic-level" OWNER: "Korum" MEANING: "User stance on topic." KIALO_IMPACT_VOTE: MODEL: "ArgumentImpactVote" RANGE: "0..4" LEVEL: "argument/claim-level" OWNER: "Korum" MEANING: "Impact of a claim on its parent; combines veracity and relevance." SMART_VOTE_READING: MODEL: "ReadingResult" RANGE: "not fixed; depends on lens and modality" LEVEL: "derived aggregation" OWNER: "Smart Vote" MEANING: "Published derived reading of baseline events." ``` ### Critical vote rules ```yaml CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false EKOH_IS_VOTING_ENGINE: false ``` --- ## 17. Smart Vote and EkoH Naming Variables ```yaml SMART_VOTE_NAMING: UI_TEXT: "Smart Vote" CODE_CLASS: "SmartVote" CODE_MODULE: "smartvote" URL_SLUG: "smart-vote" EKOH_NAMING: UI_TEXT: "EkoH" CODE_MODULE: "ekoh" SNAPSHOT_LEGACY_FIELD: "ekoh_snapshot_id" SNAPSHOT_CANONICAL_FIELD: "snapshot_ref" ``` ### Reading variables ```yaml SMART_VOTE_EKOH: BASELINE_READING: "raw_unweighted" WEIGHTED_READING: "declared_lens_output" READING_REPRODUCIBLE: true READING_INPUTS: - "BaselineEvents" - "LensDeclaration" - "SnapshotContext" SNAPSHOT_FIELD: "snapshot_ref" LEGACY_EKOH_SNAPSHOT_FIELD: "ekoh_snapshot_id" LENS_ID_FIELD: "reading_key" LENS_HASH_FIELD: "lens_hash" RESULT_PAYLOAD_FIELD: "results_payload" COMPUTED_AT_FIELD: "computed_at" ``` ### Minimum reading fields ```yaml READING_RESULT_MINIMUM_FIELDS: - "reading_key" - "lens_hash" - "snapshot_ref" - "computed_at" - "topic_id or consultation_id" - "results_payload" ``` ### Reading naming rules * `baseline` means raw unweighted result. * `reading` means derived result. * `lens` means declared transformation/aggregation logic. * `snapshot_ref` points to audit context. * `ekoh_snapshot_id` may appear as legacy/compatibility naming, but `snapshot_ref` is preferred in Kintsugi docs. * Do not use `weighted_vote` to describe upstream facts. * Do not use `SmartVoteResult` as a replacement for `ReadingResult` unless a later implementation ADR approves it. --- ## 18. Canonical Object Names ```yaml CANONICAL_OBJECTS: - "ProblemStatement" - "IntakeSubmission" - "IntakeQueue" - "Topic" - "TopicTag" - "Option" - "OptionSet" - "Constraint" - "ConstraintSet" - "Argument" - "ArgumentGraph" - "ArgumentEdge" - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "StanceEvent" - "BallotEvent" - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" - "DecisionProtocol" - "DecisionRecord" - "BaselineResult" - "ReadingResult" - "LensDeclaration" - "SnapshotRef" - "ImpactTrack" - "ImpactUpdate" - "ExternalArtifact" - "ProjectionMapping" - "ModerationAction" - "AuditEvent" ``` ### Object naming rules * Use `Argument`, not `DebatePost`. * Use `ArgumentGraph`, not `DebateTree`. * Use `StanceEvent`, not `OpinionVote`. * Use `BallotEvent`, not `VoteRecord`, when referring to raw ballot capture. * Use `ReadingResult`, not `WeightedResult`, when referring to Smart Vote outputs. * Use `LensDeclaration`, not `VoteLens`. * Use `ImpactTrack`, not `ProjectImpact`, when referring to ethiKos accountability truth. * Use `ExternalArtifact` and `ProjectionMapping` for annex boundaries. --- ## 19. Canonical Event Names ```yaml CANONICAL_EVENTS: - "TopicCreated" - "TopicClosed" - "StanceRecorded" - "ArgumentCreated" - "ArgumentUpdated" - "ArgumentHidden" - "ArgumentSourceAttached" - "ArgumentImpactVoteRecorded" - "ArgumentSuggestionSubmitted" - "ArgumentSuggestionAccepted" - "ArgumentSuggestionRejected" - "DraftCreated" - "DraftVersionCreated" - "AmendmentSubmitted" - "DecisionOpened" - "DecisionClosed" - "DecisionPublished" - "ReadingComputed" - "ReadingPublished" - "ReadingInvalidated" - "ImpactUpdated" - "ModerationActionRecorded" ``` ### Event naming rules * Event names use PascalCase. * Event names describe facts that occurred. * Event names MUST NOT include UI names unless the event is specifically a UI audit event. * `ReadingComputed` does not mean the result was published. * `DecisionClosed` does not mean the decision was implemented. --- ## 20. Payload Shape Names ```yaml REQUIRED_PAYLOAD_SHAPES: - "TopicPayload" - "StancePayload" - "ArgumentPayload" - "ArgumentTreePayload" - "ArgumentNodePayload" - "ArgumentSourcePayload" - "ArgumentImpactVotePayload" - "ArgumentSuggestionPayload" - "DecisionRecordPayload" - "DecisionProtocolPayload" - "LensDeclarationPayload" - "ReadingResultPayload" - "DraftPayload" - "DraftVersionPayload" - "AmendmentPayload" - "ImpactTrackPayload" - "DiscussionSettingsPayload" - "ParticipantRolePayload" ``` ### Payload constants ```yaml PAYLOAD_CONSTANTS: ID_TYPE_CURRENT_ETHIKOS: "integer" DATE_FORMAT: "ISO_8601" PAGINATION_STYLE: "DRF-compatible" ERROR_STYLE: "DRF-compatible" STANCE_VALUE_RANGE: "-3..+3" CLAIM_IMPACT_RANGE: "0..4" ``` ### Payload naming rules * Payload names use PascalCase. * API JSON fields use snake_case when aligned with Django/DRF. * Frontend TypeScript types MAY use PascalCase interfaces with camelCase internal field names only if the service layer maps them explicitly. * Avoid ad-hoc payload names such as `TopicDTO`, `VoteData`, or `KialoPayload` unless a service file already uses them and maps them to canonical names. --- ## 21. Enum Names and Values ```yaml ENUMS: TOPIC_STATUS: - "open" - "closed" - "archived" ARGUMENT_SIDE: - "pro" - "con" - "neutral" DECISION_STATUS: - "draft" - "open" - "closed" - "published" - "archived" DRAFT_STATUS: - "draft" - "review" - "accepted" - "superseded" - "archived" IMPACT_STATUS: - "planned" - "in_progress" - "blocked" - "completed" - "cancelled" READING_STATUS: - "pending" - "computed" - "published" - "invalidated" AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" PARTICIPATION_TYPE: - "standard" - "anonymous" DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" ``` ### Enum naming rules * Enum names use uppercase snake case in documentation. * Enum values use lowercase snake case unless matching existing implementation. * Do not invent synonyms like `active`, `finished`, `hidden`, `private_only`, or `moderators` unless an implementation contract adds them. * If current code uses `null` for neutral argument side, docs MAY mention compatibility but canonical Kintsugi naming is `neutral`. --- ## 22. Frontend Component Naming Variables ```yaml FRONTEND_SURFACES_TO_REFERENCE: EXISTING_LAYOUT_COMPONENTS: - "MainLayout" - "EthikosPageShell" - "PageContainer" - "Ant Design App context" DO_NOT_DUPLICATE: - "global shell" - "module shell" - "theme system" - "navigation system" ``` ### Kialo-style frontend surfaces ```yaml KIALO_STYLE_FRONTEND_SURFACES: - "ArgumentTreeView" - "ArgumentNodeCard" - "ArgumentMinimap" - "ArgumentSourcesPanel" - "GuidedVotingDrawer" - "PerspectiveSelector" - "SuggestedClaimsPanel" - "ParticipantRoleSettings" - "DiscussionSettingsPanel" - "AnonymousModeBanner" ``` ### Frontend naming rules * All new ethiKos pages remain under `/ethikos/*`. * All new ethiKos page UIs should use `EthikosPageShell` or the current shell pattern. * Do not create `KintsugiPageShell`. * Do not create `KialoPageShell`. * Do not create a new global navigation system. * Service functions should live in the existing service layer pattern. --- ## 23. Service-Layer Naming Variables ```yaml SERVICE_LAYER_POLICY: USE_EXISTING_SERVICES_FOLDER: true DO_NOT_INVENT_API_CLIENT_PATTERN: true ALL_NEW_API_CALLS_SHOULD_HAVE_SERVICE_WRAPPER: true NO_RAW_FETCH_FROM_COMPONENTS_UNLESS_DOCUMENTED: true ``` ### Service names to preserve or align ```yaml SERVICE_NAMES: ETHIKOS_SERVICE: "services/ethikos" DELIBERATE_SERVICE: "services/deliberate" DECIDE_SERVICE: "services/decide" IMPACT_SERVICE: "services/impact" LEARN_SERVICE: "services/learn" ADMIN_SERVICE: "services/admin" ``` ### Service naming rules * Prefer verbs such as `fetch`, `create`, `update`, `submit`, `publish`, `compute`. * Avoid external-source names in service function names unless clearly pattern-specific. * Use `fetchTopicPreview`, not `fetchKialoPreview`. * Use `submitArgumentImpactVote`, not `submitKialoVote`. * Use `fetchReadingResults`, not `fetchWeightedVotes`. --- ## 24. Mimic vs Annex Naming Variables ```yaml MIMIC_VS_ANNEX: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" MIMIC_FIRST_PASS: true ANNEX_REQUIRES_ISOLATION: true ANNEX_REQUIRES_REPLACEABILITY: true ANNEX_REQUIRES_NO_CORE_TABLE_WRITES: true ANNEX_REQUIRES_LICENSE_CLEARANCE: true ANNEX_REQUIRES_ADAPTER_LAYER: true FULL_CODE_IMPORT_DEFAULT: false ANNEX_BOUNDARY_OBJECTS: - "ExternalArtifact" - "ProjectionMapping" ``` ### Mimic naming rule Use external tool names only in matrix rows, comments, or source references. Do not embed external tool names in canonical backend models unless explicitly approved by an ADR. Correct: ```txt ArgumentImpactVote DecisionProtocol ImpactTrack ExternalArtifact ``` Incorrect: ```txt KialoVote LoomioProposal DecidimProcess ConsulThreshold DemocracyOSForum ``` --- ## 25. Known Bug Naming Variables ```yaml KNOWN_BUGS: BUG_001: ID: "BUG_001" TITLE: "Deliberate preview drawer shows 'Preview / No data'" STATUS: "known_open" CLASSIFICATION: "targeted_bugfix_not_architecture" DO_NOT_USE_TO_REDESIGN_KINTSUGI: true ``` ### Bug naming rules * Known bugs must be listed in `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md`. * Bugs must not drive architecture changes unless escalated through an ADR. * The preview drawer bug may require service/payload fixes, but it does not justify route or model redesign. --- ## 26. Documentation File Name Variables ```yaml DOCUMENT_PACK: 00: "00_KINTSUGI_START_HERE.md" 01: "01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md" 02: "02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md" 03: "03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md" 04: "04_CANONICAL_NAMING_AND_VARIABLES.md" 05: "05_CURRENT_STATE_BASELINE.md" 06: "06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md" 07: "07_API_AND_SERVICE_CONTRACTS.md" 08: "08_DATA_MODEL_AND_MIGRATION_PLAN.md" 09: "09_SMART_VOTE_EKOH_READING_CONTRACT.md" 10: "10_FIRST_PASS_INTEGRATION_MATRIX.md" 11: "11_MIMIC_VS_ANNEX_RULEBOOK.md" 12: "12_CANONICAL_OBJECTS_AND_EVENTS.md" 13: "13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md" 14: "14_FRONTEND_ALIGNMENT_CONTRACT.md" 15: "15_BACKEND_ALIGNMENT_CONTRACT.md" 16: "16_TEST_AND_SMOKE_CONTRACT.md" 17: "17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md" 18: "18_ADR_REGISTER.md" 19: "19_OSS_CODE_READING_PLAN.md" 20: "20_AI_GENERATION_GUARDRAILS.md" 21: "21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md" 22: "22_IMPLEMENTATION_BACKLOG_TEMPLATE.md" ``` ### Canonical folder ```yaml TARGET_DOC_FOLDER: CANONICAL_PATH: "docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/" ``` --- ## 27. Reserved Terms These terms are reserved and must keep their meanings. | Term | Canonical meaning | | ------------------- | --------------------------------------------------------------- | | `Baseline` | Raw unweighted aggregation of recorded events | | `Reading` | Declared derived aggregation, usually Smart Vote-owned | | `Lens` | Declared transformation/filtering/weighting rule | | `SnapshotRef` | Audit pointer for reproducible context | | `Korum` | Debate/argumentation ownership domain | | `Konsultations` | Intake/consultation/ballot/impact ownership domain | | `Smart Vote` | Reading and publication layer | | `EkoH` | Expertise/ethics context layer | | `Mimic` | Native pattern reimplementation | | `Annex` | Isolated sidecar/adapted external tool | | `ExternalArtifact` | Raw external artifact with provenance | | `ProjectionMapping` | Mapping from external IDs to internal canonical objects | | `Claim` | Conceptual Kialo-style argument unit; maps to `EthikosArgument` | | `Impact Vote` | Claim-level `0..4` score; not a topic stance | | `Stance` | Topic-level user stance `-3..+3` | --- ## 28. Forbidden Names and Substitutions | Forbidden or discouraged | Use instead | Reason | | ------------------------ | -------------------------------- | -------------------------------------- | | `DeliberationTopic` | `EthikosTopic` or `Topic` | Preserve existing model | | `DebatePost` | `EthikosArgument` or `Argument` | Preserve current semantics | | `OpinionVote` | `EthikosStance` or `StanceEvent` | Stance is canonical | | `KialoClaim` | `EthikosArgument` / `Argument` | No Kialo module in first pass | | `KialoVote` | `ArgumentImpactVote` | Avoid external naming | | `VoteLens` | `LensDeclaration` | Canonical Smart Vote naming | | `WeightedResult` | `ReadingResult` | Reading is broader and auditable | | `SmartVoteResult` | `ReadingResult` | Avoid coupling object name to UI layer | | `EkoHVote` | Not allowed | EkoH does not vote | | `/api/deliberation/...` | `/api/ethikos/...` | Preserve existing API | | `/kialo/*` | `/ethikos/deliberate/*` | Kialo is mimic only | | `konnaxion.kialo` | `konnaxion.ethikos` | No new backend app | | `KintsugiShell` | `EthikosPageShell` | No second shell | --- ## 29. Parallel AI Generation Header Every parallel AI conversation generating one Kintsugi doc SHOULD include the following instruction: ```text Use 04_CANONICAL_NAMING_AND_VARIABLES.md as binding context. Generate only the assigned document. Do not reinterpret scope. Do not introduce routes, models, endpoints, or architecture that conflict with the canonical variables. If a prior document conflicts with this naming file, this naming file wins for names. If this naming file conflicts with current code reality, current code reality wins for implemented names. ``` --- ## 30. Anti-Drift Rules ```yaml ANTI_DRIFT_RULES: - "Do not rename existing backend apps." - "Do not rename existing Ethikos models." - "Do not invent new route families." - "Do not create a separate Kialo module." - "Do not create a separate Kintsugi app." - "Do not convert EkoH into a voting engine." - "Do not let Smart Vote mutate upstream facts." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expand /api/home/*." - "Do not replace /api/ethikos/* with /api/deliberation/*." - "Do not use external OSS names as internal canonical model names." - "Do not generate implementation backlog inside naming/strategy docs." - "Do not use deferred OSS sources as first-pass implementation targets." ``` --- ## 31. Non-Goals This document does not: * define the complete Kintsugi strategy; * define database schema details; * define migrations; * define serializers; * define frontend components in detail; * define the route-by-route implementation plan; * define the Smart Vote formula; * define the EkoH snapshot schema; * define the Kialo-style feature implementation; * define the OSS code-reading procedure; * generate implementation tasks. Those belong to related docs. --- ## 32. Related Documents | File | Relationship | | ----------------------------------------------- | --------------------------------- | | `00_KINTSUGI_START_HERE.md` | Entry point and reading order | | `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` | Strategic frame | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Source priority and drift rules | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Ownership and write rules | | `05_CURRENT_STATE_BASELINE.md` | Current implementation state | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route mapping | | `07_API_AND_SERVICE_CONTRACTS.md` | API/service details | | `08_DATA_MODEL_AND_MIGRATION_PLAN.md` | Schema/migration details | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Smart Vote/EkoH reading rules | | `10_FIRST_PASS_INTEGRATION_MATRIX.md` | OSS pattern matrix | | `11_MIMIC_VS_ANNEX_RULEBOOK.md` | External integration strategy | | `12_CANONICAL_OBJECTS_AND_EVENTS.md` | Object/event definitions | | `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` | Payload and serializer contracts | | `14_FRONTEND_ALIGNMENT_CONTRACT.md` | Frontend rules | | `15_BACKEND_ALIGNMENT_CONTRACT.md` | Backend rules | | `16_TEST_AND_SMOKE_CONTRACT.md` | Test contract | | `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` | Known non-architecture issues | | `18_ADR_REGISTER.md` | Architecture decisions | | `19_OSS_CODE_READING_PLAN.md` | OSS code inspection procedure | | `20_AI_GENERATION_GUARDRAILS.md` | AI-specific guardrails | | `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` | Kialo-style deliberation contract | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Future backlog format | --- ## 33. Final Canonical Assertion The ethiKos Kintsugi upgrade is a documentation-first, partial-native-mimic architecture upgrade. The canonical implementation surface remains: ```txt /ethikos/* /api/ethikos/* konnaxion.ethikos EthikosTopic EthikosStance EthikosArgument EthikosCategory ``` Korum and Konsultations remain ethiKos ownership domains. Smart Vote publishes declared readings. EkoH provides expertise and ethics context. Kialo-style patterns strengthen `/ethikos/deliberate/*` without creating a Kialo module. External civic tools are first-pass inspirations, not direct merges. This document is the naming and variable authority for all other Kintsugi upgrade documentation. ``` Sources used for alignment: current ethiKos route/API/model reality, backend conventions, Smart Vote/EkoH boundary variables, and the Kialo-style deliberation corpus. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2} ``` --- ## V4.1 canonical EkoH access names ```yaml EKOH_RATING_VISIBILITY: [public, scoped, private] EKOH_RATING_ACCESS_LEVEL: [ratings, history] EKOH_ACCESS_MODELS: - RatingVisibilitySetting - RatingAccessScope - RatingScopeSubject - RatingAccessGrant EKOH_ACCESS_RESOLVER: resolve_rating_access ``` These names are canonical. Business-role names such as CEO or Supervisor are not EkoH role enums. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/05_CURRENT_STATE_BASELINE.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: a6b7d6c6495a1b32203ee08bd44b5bbb4a2792e55d61e08f63e928796a8a3251 CONTENT_BYTES: 29320 ================================================================================================ # 05 — Current State Baseline **File:** `05_CURRENT_STATE_BASELINE.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical baseline snapshot before Kintsugi upgrade **Last aligned:** 2026-04-25 **Purpose:** Freeze the current known implementation state so the Kintsugi upgrade does not drift into re-debugging, route invention, model renaming, or speculative architecture. --- ## 1. Purpose This document records the **current state of ethiKos and related Konnaxion infrastructure before the Kintsugi upgrade**. It is not a strategy document, not a backlog, and not a future-state architecture proposal. Its role is to answer: 1. What currently exists? 2. What currently works? 3. What current routes, endpoints, models, services, and module boundaries must be preserved? 4. What known defects must be tracked separately from the Kintsugi architecture work? 5. What implementation facts must future Kintsugi documents treat as fixed? The baseline is intentionally conservative. When future documents conflict with this baseline, they must explicitly explain whether they are describing: * current state, * target state, * migration step, * deferred capability. --- ## 2. Scope This baseline covers: * current repository snapshot structure; * current frontend route surface for ethiKos; * current backend app structure relevant to ethiKos; * current canonical API endpoints; * current canonical Ethikos models; * current service-layer and graph observations; * current smoke/build/runtime baseline; * current known defect; * current anti-drift constraints for the Kintsugi documentation pack. This baseline does **not** define: * the final Kintsugi target architecture; * the full implementation backlog; * the complete OSS integration plan; * future schema migrations; * future Smart Vote / EkoH weighting logic; * new UI components. Those belong in related documents listed near the end of this file. --- ## 3. Source Basis This baseline is derived from the uploaded Konnaxion repository snapshot, the technical reference docs, the contracts file, the endpoint graph, and the clean-slate Kintsugi carry-over plan. The snapshot index identifies the repository as `Konnaxion`, split into root, frontend, backend, docs, PlantUML, EndPoints-Graphs, scripts, and miscellaneous volumes. The technical reference identifies ethiKos as the platform’s structured deliberation and consultation module, with the current canonical backend centered on topics, stances, arguments, and categories. The clean-slate carry-over plan establishes the stable pre-Kintsugi baseline: frontend build works, smoke tests passed, backend local startup works with `uv`, CSRF/auth/category/topic creation were fixed, argument posting works, EkoH migration `0002...` was created and applied, and the remaining visible Ethikos bug is the Deliberate preview drawer showing “Preview / No data.” --- ## 4. Canonical Variables Used ```yaml DOCUMENT_ID: "05_CURRENT_STATE_BASELINE" DOCUMENT_ROLE: "Freeze current implementation reality before Kintsugi upgrade" PROJECT_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" CURRENT_BASELINE_DATE: "2026-04-25" PRIMARY_FRONTEND_SURFACE: "/ethikos/*" PRIMARY_BACKEND_APP: "konnaxion.ethikos" PRIMARY_API_PREFIX: "/api/ethikos/" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_CANONICAL_ENDPOINTS: - "/api/ethikos/topics/" - "/api/ethikos/stances/" - "/api/ethikos/arguments/" - "/api/ethikos/categories/" COMPATIBILITY_ENDPOINT_PREFIXES: - "/api/deliberate/..." - "/api/deliberate/elite/..." KNOWN_OPEN_BUG: id: "BUG-ETHIKOS-PREVIEW-DRAWER-001" label: "Deliberate preview drawer shows 'Preview / No data'" classification: "targeted_bugfix_not_architecture" KINTSUGI_ALLOWED_BASELINE_ACTIONS: - "document current state" - "preserve existing route families" - "preserve existing backend core" - "add non-breaking target-state docs" - "separate known bugfix from architecture" KINTSUGI_FORBIDDEN_BASELINE_ACTIONS: - "rename current models" - "replace current route families" - "invent new API prefixes" - "expand /api/home/* usage" - "treat preview drawer bug as reason for architecture redesign" ``` --- ## 5. Repository Snapshot Baseline The uploaded snapshot is a codedump split into multiple volumes. The master index identifies the following relevant volumes: | Volume | Purpose | | --------------------------------------------------- | ------------------- | | `Konnaxion_20260425_152801_01_ROOT.txt` | root files | | `Konnaxion_20260425_152801_02_frontend.txt` | frontend source | | `Konnaxion_20260425_152801_03_backend.txt` | backend source | | `Konnaxion_20260425_152801_04_docs.txt` | documentation | | `Konnaxion_20260425_152801_05_PlantUML.txt` | diagrams | | `Konnaxion_20260425_152801_06_EndPoints-Graphs.txt` | endpoint graph | | `Konnaxion_20260425_152801_07_scripts.txt` | scripts | | `Konnaxion_20260425_152801_99_OTHERS.txt` | miscellaneous files | The frontend volume contains 472 files, and the backend volume contains 309 files. ### Baseline rule Future Kintsugi documents must cite the snapshot reality when describing implementation state. Conceptual route names from older docs may be retained as product language, but implementation work must map onto the actual current repository structure. --- ## 6. Stable Operational Baseline The following operational state is considered fixed for the Kintsugi documentation pack: | Area | Current state | | ----------------------------- | --------------------------------------------------- | | Frontend build | Works | | Smoke tests | Passed | | Backend local startup | Works with `uv` | | Auth / CSRF | Fixed for the tested flows | | Category creation | Fixed | | Topic creation | Fixed | | Argument posting | Works | | EkoH migration | `0002...` created and applied | | Remaining visible Ethikos bug | Deliberate preview drawer shows “Preview / No data” | This baseline comes from the clean-slate carry-over plan and must not be re-litigated inside Kintsugi strategy docs. ### Anti-drift rule Kintsugi documentation must not restart the prior debugging narrative. The known remaining bug must be tracked as a targeted defect, not used to redesign the Kintsugi architecture. --- ## 7. Current Frontend Baseline ### 7.1 Primary route surface The current Ethikos frontend is implemented under: ```txt /ethikos/* ``` The implemented page groups are: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` The technical reference states that this route structure is deeper and more explicit than older simplified navigation concepts such as `/debate`, `/consult`, or `/reputation`. ### 7.2 Implemented route inventory #### Decide ```txt /ethikos/decide/elite /ethikos/decide/public /ethikos/decide/results /ethikos/decide/methodology ``` Current role: * decision-oriented surfaces; * results views; * methodology explanation; * public and elite decision participation surfaces. #### Deliberate ```txt /ethikos/deliberate/elite /ethikos/deliberate/[topic] /ethikos/deliberate/guidelines ``` Current role: * topic-centered deliberation; * argument threads; * stance capture; * guidelines. #### Trust ```txt /ethikos/trust/profile /ethikos/trust/badges /ethikos/trust/credentials ``` Current role: * credibility; * badges; * credentials; * legitimacy and expertise signaling. #### Pulse ```txt /ethikos/pulse/overview /ethikos/pulse/live /ethikos/pulse/health /ethikos/pulse/trends ``` Current role: * participation monitoring; * health signals; * live activity; * trends. #### Impact ```txt /ethikos/impact/feedback /ethikos/impact/outcomes /ethikos/impact/tracker ``` Current role: * feedback; * outcomes; * tracker views; * accountability surface. #### Learn ```txt /ethikos/learn/changelog /ethikos/learn/glossary /ethikos/learn/guides ``` Current role: * changelog; * glossary; * guides; * explanatory content. #### Insights ```txt /ethikos/insights ``` Current role: * analytics; * interpretation; * reporting surface. #### Admin ```txt /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles ``` Current role: * audit; * moderation; * role management. The docs volume and technical reference both confirm these implemented route families as first-class Ethikos page groups. --- ## 8. Frontend Shell and Layout Baseline Ethikos pages currently use the existing module/global shell structure. The technical reference states that the Ethikos frontend uses `EthikosPageShell` and `PageContainer` consistently. The frontend file index includes: ```txt frontend/app/ethikos/EthikosPageShell.tsx frontend/app/ethikos/layout.tsx ``` and route pages under all major Ethikos route families. ### Baseline rule Future Kintsugi UI work must: * keep the existing `/ethikos/*` route surface; * keep the existing shell pattern; * use `EthikosPageShell` where appropriate; * avoid creating a second Kintsugi shell; * avoid creating a separate Kialo route family; * avoid creating a separate top-level Kintsugi application. ### Forbidden ```txt /kintsugi/* /kialo/* /platforms/konnaxion/ethikos/kintsugi as implementation route new root-level Ethikos shell new independent civic-tech shell ``` Conceptual/public routes may appear in strategy docs, but implementation mapping must target the current `/ethikos/*` surface. --- ## 9. Current Backend Baseline ### 9.1 Backend stack The current backend is a Django / Django REST Framework project with local apps including: ```txt konnaxion.users konnaxion.kollective_intelligence konnaxion.ethikos konnaxion.keenkonnect konnaxion.konnected konnaxion.kreative ``` The AI technical instructions identify the backend as Django 5.1 + Django REST Framework + Celery + Redis, using a Cookiecutter-Django-style layout and PostgreSQL as the relational database. The same technical instructions state that generated backend code should assume: ```txt AUTH_USER_MODEL = "users.User" ROOT_URLCONF = "config.urls" ``` and should not refer to Django’s default `auth.User`. ### 9.2 Canonical backend app The canonical backend app for Ethikos is: ```txt konnaxion.ethikos ``` The contracts document states that Ethikos uses the `konnaxion.ethikos` backend app, exposed under `/api/ethikos/...` through the central DRF router. ### 9.3 Current DRF style The current API style is: ```txt Django REST Framework ViewSet + Serializer + Router ``` The backend code imports and uses Ethikos ViewSets including: ```txt CategoryViewSet TopicViewSet StanceViewSet ArgumentViewSet ``` The backend snapshot shows `CategoryViewSet` as a `ReadOnlyModelViewSet` and `TopicViewSet` as a `ModelViewSet` with authenticated-or-read-only permissions and owner-or-read-only behavior. --- ## 10. Current Canonical Ethikos API The current canonical Ethikos API endpoints are: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` The contracts file maps these endpoints respectively to topic, stance, argument, and category ViewSets. Compatibility aliases also exist: ```txt /api/deliberate/... /api/deliberate/elite/... ``` These aliases include the same Ethikos URLs under different namespaces and must be treated as compatibility surfaces, not separate backends. ### Baseline rule Future Kintsugi documents must not invent alternate CRUD prefixes such as: ```txt /api/deliberation/ /api/kintsugi/ /api/korum/ /api/kialo/ ``` unless a later implementation document explicitly defines a non-breaking migration and its ownership. --- ## 11. Current Canonical Ethikos Models Current canonical Ethikos tables/models: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` The technical reference and contracts document both identify these as the current canonical Ethikos model set. ### 11.1 `EthikosCategory` Current role: * groups topics thematically; * supports category filters; * exposed through `/api/ethikos/categories/` when registered. Known fields from contracts: ```txt name description ``` ### 11.2 `EthikosTopic` Current role: * main debate / consultation prompt; * main object used by Decide and Deliberate surfaces; * current candidate mapping for future Korum `Discussion` / `Thesis` container. Known semantics: ```txt title description status: open | closed | archived total_votes last_activity category created_by optional expertise_category timestamps ``` ### 11.3 `EthikosStance` Current role: * one user’s numeric position on a topic; * topic-level stance, not claim-level vote; * current basis for topic stance summaries and some consultation result calculations. Known semantics: ```txt user topic value: integer constrained to -3..+3 timestamp unique per user/topic ``` ### 11.4 `EthikosArgument` Current role: * discussion entry; * threaded reply; * current candidate mapping for future Kialo-style `Claim`; * supports pro/con classification and nesting. Known semantics: ```txt topic user content side: pro | con | null parent is_hidden timestamps ``` ### Baseline model rule Do not rename current models during Kintsugi documentation or first-pass implementation planning. Specifically: ```txt Do not rename EthikosArgument to Claim. Do not rename EthikosTopic to Discussion. Do not rename EthikosStance to Ballot. Do not rename EthikosCategory to Taxonomy. ``` Future documents may define conceptual mappings, but current model names remain stable. --- ## 12. Current Participation and Permission Baseline The technical reference states that the user model already contains Ethikos-specific semantics such as: ```txt is_ethikos_elite can_participate_in_ethikos ``` with participation rules for staff, klones, and explicitly flagged elite users. The backend snapshot also shows simple owner-or-read-only behavior for objects using either `created_by_id` or `user_id`. ### Baseline rule Kintsugi docs may propose richer participation and role contracts, but they must recognize that current implementation already has: * authenticated-or-read-only behavior; * owner-or-read-only behavior; * elite participation semantics; * staff/klone/elite participation rules. These must be extended carefully, not replaced implicitly. --- ## 13. Current Service-Layer Baseline Ethikos data access should go through service modules rather than raw component-level fetches. The contracts document states that data access goes through an Ethikos service module wrapping `/api/ethikos/...` and `/api/deliberate/...`, and that Ethikos pages are rendered inside the global shell using shared UI primitives. Current frontend service exports include: ```txt audit decide deliberate pulse ``` The frontend snapshot shows `frontend/services/index.ts` exporting several service modules. ### Baseline rule Future Kintsugi frontend work must: * use the existing services layer; * avoid raw API fetches directly inside route pages unless documented as legacy or exceptional; * preserve the service-wrapper pattern; * avoid inventing an unrelated client architecture. --- ## 14. Current Endpoint Graph Observations The endpoint graph identifies several important current-state mappings. ### 14.1 Deliberate service mappings are loose The endpoint graph maps `frontend/services/deliberate.ts` calls such as: ```txt /deliberate/topics/${id} /deliberate/topics/${id}/preview /deliberate/elite/topics ``` to backend `api/ethikos/topics`, with `TopicViewSet`, `EthikosTopic`, and `link_type = loose`. Interpretation: * the frontend deliberate service is conceptually mapped to Ethikos topics; * the mapping is not a fully strict one-to-one documented contract; * Kintsugi should stabilize this service/API contract before adding complex Kialo-style argument mapping. ### 14.2 Preview service exists as a concept The frontend service contains a `fetchTopicPreview` function that loads a topic from `ethikos/topics/{id}/`, then attempts to load arguments for that topic from `ethikos/arguments/`, and returns topic metadata plus a latest-statements slice. Interpretation: * preview behavior has a service-level shape; * runtime UI behavior still has a known visible defect from the baseline; * the bug must be tracked separately. ### 14.3 Impact service mappings are loose The endpoint graph maps several `frontend/services/impact.ts` calls to `api/keenkonnect/projects` with `ProjectViewSet`, `Project`, and `link_type = loose`. Interpretation: * current Impact views are partially backed by KeenKonnect project concepts; * Kintsugi target-state docs must clarify that civic accountability truth belongs to Ethikos/Konsultations, not KeenKonnect; * any future handoff from Impact to KeenKonnect must be explicit. ### 14.4 Learn service mixes static and backend-derived content The Learn service defines canonical local content and notes that glossary terms are synced from Ethikos categories, while category fetching must degrade safely because the backend categories endpoint may be optional. Interpretation: * Learn is partly static/semi-static; * Learn may read Ethikos categories; * Learn should not be treated as a full dynamic Kintsugi engine surface. --- ## 15. Current Konsultations Baseline Current Konsultations implementation is not yet a full independent backend module in the observed snapshot. The frontend snapshot includes: ```txt frontend/modules/konsultations/hooks/useConsultations.ts ``` as a stub, and other Konsultations hooks map consultation results and voting to Ethikos stances or Decide services. ### Current interpretation At baseline: * a “consultation” may be represented by an Ethikos topic; * consultation result calculations may aggregate `EthikosStance` rows; * public consultation voting may wrap Decide service behavior; * Konsultations is conceptually important but technically underdeveloped. ### Baseline rule Future Kintsugi documents must not pretend that a full Konsultations backend already exists unless they explicitly mark it as target state. --- ## 16. Current Smart Vote / EkoH Baseline The current Kintsugi baseline recognizes Smart Vote and EkoH as planned/related decision and expertise layers, but not as direct mutators of the Ethikos core. The boundaries document states that ethiKos v2 is a documentation and boundary upgrade first, must keep existing service code names, core tables, and routes stable, and should only add non-breaking fields/tables such as reading audit fields, `ExternalArtifact`, `ProjectionMapping`, and drafting tables. ### Baseline rule For current-state purposes: ```txt EthikosStance = existing topic-level stance Smart Vote Reading = target derived reading layer EkoH Snapshot = target expertise/context audit input ``` Future docs must preserve the separation between: * raw stance/ballot events; * Smart Vote readings; * EkoH expertise/ethics context. --- ## 17. Current Build / Smoke / Runtime Verification Baseline The baseline states: ```txt frontend build works Playwright smoke ran successfully backend local startup works with uv ``` The technical reference adds that Ethikos participates in the standard frontend production build and now builds cleanly, and that Ethikos pages are part of successful static generation / route preparation in the production build. It also states that runtime verification remains required for live API-backed behavior even after build success. ### Baseline implication Build success does not mean all live API-backed Ethikos behavior is complete. Kintsugi docs must distinguish: | Category | Meaning | | ----------------------- | --------------------------------------------- | | Build-safe | Compiles and participates in route generation | | Smoke-safe | Passed smoke verification | | API-backed runtime-safe | Verified live against backend | | Target-state | Planned future behavior | --- ## 18. Known Open Bug ### BUG-ETHIKOS-PREVIEW-DRAWER-001 ```yaml id: "BUG-ETHIKOS-PREVIEW-DRAWER-001" title: "Deliberate preview drawer shows 'Preview / No data'" status: "known_open" classification: "targeted_bugfix_not_architecture" surface: "/ethikos/deliberate/*" likely_area: - "frontend preview drawer" - "frontend/services/deliberate.ts" - "topic preview endpoint or response shape" - "runtime API data availability" ``` The clean-slate plan identifies this as the remaining visible Ethikos bug. The frontend service includes a `fetchTopicPreview` function that returns topic metadata and latest argument statements, which means the correct fix should likely verify runtime routing, response shape, and drawer consumption rather than redesigning the architecture. ### Bug handling rule This bug must be tracked in: ```txt 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md ``` It must not cause changes to: * Kintsugi scope; * ownership model; * first-pass OSS matrix; * Smart Vote / EkoH contracts; * route-family stability. --- ## 19. Current Things That Are Not Yet Canonical The technical reference explicitly states that the following broader concept-doc items are not part of the current canonical Ethikos implementation set: ```txt AI clones comparative analysis logs debate archives automated summaries ``` ### Baseline rule Future Kintsugi docs may describe these as possible later capabilities only if they are clearly marked as deferred or out-of-scope. --- ## 20. Current Legacy / Risk Areas ### 20.1 `/api/home/*` Previous endpoint graph analysis identified lingering or historical `/api/home/*` usage. This baseline treats `/api/home/*` as legacy/problematic. Rule: ```txt Do not expand /api/home/*. Do not define new Kintsugi features on /api/home/*. Replace or isolate legacy uses through canonical services. ``` ### 20.2 Loose service mappings Current loose mappings exist around: ```txt frontend/services/deliberate.ts frontend/services/impact.ts frontend/services/learn.ts ``` The endpoint graph shows multiple loose mappings from frontend service endpoints to backend viewsets/models. Rule: ```txt Loose mappings must be converted into explicit API/service contracts before complex Kintsugi implementation. ``` ### 20.3 Impact ownership ambiguity Current Impact service mappings touch KeenKonnect project APIs. Rule: ```txt Impact may hand off to KeenKonnect, but Kintsugi civic accountability truth belongs to Ethikos/Konsultations target state. ``` --- ## 21. Baseline Route-to-Role Table | Current route family | Current baseline role | Kintsugi implication | | ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ | | `/ethikos/decide/*` | Decision, results, methodology, public/elite participation | Extend into decision protocols and Smart Vote readings | | `/ethikos/deliberate/*` | Topics, stances, arguments, guidelines | Extend into Korum + Kialo-style structured argument mapping | | `/ethikos/trust/*` | Profile credibility, badges, credentials | Connect to EkoH context without making EkoH the voting engine | | `/ethikos/pulse/*` | Participation monitoring and trends | Extend into civic health signals | | `/ethikos/impact/*` | Feedback, outcomes, tracker | Formalize Konsultations accountability and reduce loose KeenKonnect dependency | | `/ethikos/learn/*` | Changelog, glossary, guides | Use for Kintsugi methodology and public education | | `/ethikos/insights` | Analytics and interpretation | Use for reading comparisons and Smart Vote/EkoH explanations | | `/ethikos/admin/*` | Audit, moderation, roles | Extend governance controls and audit trail | --- ## 22. Baseline Model-to-Target Mapping | Current model | Current meaning | Future Kintsugi mapping | Preserve name? | | ----------------- | ----------------------------------------- | ------------------------------------------------------------------ | -------------- | | `EthikosCategory` | Topic grouping | Taxonomy/category seed | Yes | | `EthikosTopic` | Debate / consultation prompt | Korum discussion container; Konsultations topic proxy where needed | Yes | | `EthikosStance` | User topic-level stance, `-3..+3` | Raw topic stance event / possible baseline result input | Yes | | `EthikosArgument` | Threaded argument/reply with pro/con side | Kialo-style claim node | Yes | --- ## 23. Current Baseline Invariants These statements must remain true unless a future migration document explicitly changes them: ```yaml ETHIKOS_PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_PRIMARY_BACKEND_APP: "konnaxion.ethikos" ETHIKOS_PRIMARY_API_PREFIX: "/api/ethikos/" ETHIKOS_CURRENT_MODELS_STABLE: true ETHIKOS_ARGUMENT_POSTING_WORKS: true ETHIKOS_STANCE_RANGE: "-3..+3" ETHIKOS_ARGUMENT_GRAPH_CURRENT_BASIS: "EthikosArgument.parent + EthikosArgument.side" ETHIKOS_COMPAT_ALIASES_EXIST: true ETHIKOS_PREVIEW_DRAWER_BUG_OPEN: true KONSULTATIONS_FULL_BACKEND_EXISTS: false SMART_VOTE_READINGS_ARE_TARGET_STATE: true EKOH_CONTEXT_IS_TARGET_STATE_FOR_WEIGHTED_READINGS: true ``` --- ## 24. Non-Goals This file does not: * define the Kintsugi future-state architecture; * introduce new models; * introduce new routes; * introduce new endpoints; * propose migrations; * define Smart Vote algorithms; * define EkoH scoring; * define Kialo-style payloads; * fix the preview drawer bug; * replace existing technical references; * supersede the ownership/boundaries document. --- ## 25. Anti-Drift Rules Future Kintsugi docs and AI-generated implementation plans must obey the following: ```txt Do not treat conceptual docs as implementation reality when code snapshot disagrees. Do not replace /ethikos/* with public/conceptual route names. Do not rename current Ethikos models. Do not create /api/kintsugi/* for first-pass CRUD. Do not create /api/kialo/*. Do not create konnaxion.kialo. Do not expand /api/home/*. Do not treat Konsultations as fully implemented backend current state. Do not treat Smart Vote readings as current Ethikos source facts. Do not treat EkoH as current voting engine. Do not use BUG-ETHIKOS-PREVIEW-DRAWER-001 as architecture justification. Do not generate backlog tasks inside this baseline file. ``` --- ## 26. Related Documents This baseline should be read with: ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 27. Final Baseline Statement The current ethiKos implementation is a working, build-safe structured deliberation module with a stable `/ethikos/*` frontend route surface, a canonical `konnaxion.ethikos` backend, REST endpoints under `/api/ethikos/*`, and four current canonical models: `EthikosCategory`, `EthikosTopic`, `EthikosStance`, and `EthikosArgument`. The Kintsugi upgrade must build on this baseline without replacing it. The only known visible Ethikos defect carried into the upgrade is: ```txt BUG-ETHIKOS-PREVIEW-DRAWER-001: Deliberate preview drawer shows “Preview / No data”. ``` That defect is a targeted runtime/UI bug, not a reason to redesign Ethikos architecture. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b451799a5f8ed8eb0ea1d5e8be4dbccf1bd611f2fa098e0ad0c31f7600950d89 CONTENT_BYTES: 34246 ================================================================================================ # 06 — Route-by-Route ethiKos Upgrade Plan **Document ID:** `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical planning document **Last aligned:** 2026-04-25 **Primary scope:** Existing `/ethikos/*` route family **Implementation mode:** Partial native mimic, no full external merge --- ## 1. Purpose This document maps the Kintsugi upgrade onto the existing ethiKos route surface. The goal is to prevent route drift, feature drift, and architecture drift while upgrading ethiKos from a structured debate module into a full civic deliberation, drafting, decision, reading, and accountability engine. This document defines: - which existing ethiKos routes remain canonical; - what each route family owns after the Kintsugi upgrade; - which OSS-inspired patterns are allowed on each route; - which backend domain each route should read from or write to; - which routes should be upgraded, kept stable, or deferred; - what must not be created as a parallel route family. --- ## 2. Scope This document covers the existing frontend route family: ```txt /ethikos/* ```` The canonical ethiKos route families are: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` This document does not define a new application, a new module shell, or a new top-level Kintsugi route. --- ## 3. Canonical Variables Used ```yaml PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_DELIBERATION_ROUTE: "/ethikos/deliberate/*" PRIMARY_DECISION_ROUTE: "/ethikos/decide/*" PRIMARY_IMPACT_ROUTE: "/ethikos/impact/*" PRIMARY_ADMIN_ROUTE: "/ethikos/admin/*" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true KORUM_OWNS: - topics - stances - arguments - argument moderation - structured deliberation KONSULTATIONS_OWNS: - intake - ballots - consultation results - impact tracking SMART_VOTE_OWNS: - readings - lenses - result publication EKOH_OWNS: - expertise context - ethics context - cohort eligibility - snapshots KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" KIALO_DISCUSSION_MAPPING: "Discussion -> EthikosTopic" KIALO_CLAIM_MAPPING: "Claim -> EthikosArgument" KIALO_EDGE_MAPPING: "parent + side" KIALO_IMPACT_VOTE_IS_TOPIC_STANCE: false LEGACY_OR_PROBLEMATIC_ENDPOINTS: - "/api/home/*" ``` --- ## 4. Non-goals The Kintsugi route upgrade MUST NOT: * create a new `/kintsugi` top-level application; * create a new `/kialo` route family; * create a separate `konnaxion.kialo` backend app; * replace existing `/ethikos/*` routes; * rename `EthikosArgument` to `Claim`; * rename `/api/ethikos/...` to `/api/deliberation/...`; * convert EkoH into a voting engine; * let Smart Vote mutate Korum or Konsultations source facts; * expand legacy `/api/home/*` usage; * create a second module shell or theme system; * treat Kialo-style impact votes as topic-level stances; * treat Kialo-style impact votes as Smart Vote ballots. --- ## 5. Current Route Surface The existing ethiKos frontend already contains the required product surface for the Kintsugi upgrade. ```txt /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles /ethikos/decide/elite /ethikos/decide/public /ethikos/decide/results /ethikos/decide/methodology /ethikos/deliberate/elite /ethikos/deliberate/[topic] /ethikos/deliberate/guidelines /ethikos/impact/feedback /ethikos/impact/outcomes /ethikos/impact/tracker /ethikos/insights /ethikos/learn/changelog /ethikos/learn/glossary /ethikos/learn/guides /ethikos/pulse/health /ethikos/pulse/live /ethikos/pulse/overview /ethikos/pulse/trends /ethikos/trust/badges /ethikos/trust/credentials /ethikos/trust/profile ``` These routes are sufficient for the Kintsugi first pass. New top-level civic routes SHOULD NOT be introduced unless a future ADR explicitly authorizes them. --- ## 6. Route Ownership Summary | Route family | Kintsugi role | Primary owner | Supporting layers | First-pass OSS inspiration | | ----------------------- | ----------------------------------------- | ------------------------------ | -------------------------------------- | ------------------------------------- | | `/ethikos/deliberate/*` | Structured deliberation | Korum | EkoH, Smart Vote readings later | Kialo-style, Consider.it, DemocracyOS | | `/ethikos/decide/*` | Decision protocols and result publication | Konsultations + Smart Vote | EkoH | Loomio, CONSUL Democracy, DemocracyOS | | `/ethikos/impact/*` | Accountability and outcomes | Konsultations | KeenKonnect handoff later | Decidim, CONSUL Democracy | | `/ethikos/pulse/*` | Civic health and live signals | ethiKos analytics | Korum, Konsultations, Smart Vote | Decidim-style process visibility | | `/ethikos/trust/*` | Expertise and trust context | EkoH | Smart Vote | EkoH internal model | | `/ethikos/admin/*` | Moderation, audit, roles | ethiKos admin | Korum, Konsultations, Smart Vote, EkoH | Decidim, CONSUL, Kialo permissions | | `/ethikos/learn/*` | Methodology and public explanation | ethiKos documentation UX | All layers | Native | | `/ethikos/insights` | Analytics and reading comparison | Smart Vote + ethiKos analytics | EkoH | Smart Vote, Decidim accountability | --- ## 7. Backend Alignment ### 7.1 Existing canonical backend endpoints Current ethiKos core API endpoints: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` Current compatibility aliases: ```txt /api/deliberate/... /api/deliberate/elite/... ``` Current related decision/vote endpoint: ```txt /api/kollective/votes/ ``` ### 7.2 Current core models ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` ### 7.3 Route upgrade principle Routes SHOULD continue to read/write through the existing service layer and canonical API endpoints. Legacy or problematic endpoints such as: ```txt /api/home/* ``` MUST NOT be expanded. They SHOULD be replaced, isolated, or documented as legacy. --- ## 8. Frontend Shell Alignment All ethiKos pages MUST remain inside the existing ethiKos/global shell. Pages MUST NOT: * create local full-page shells; * redefine a separate major page header outside the module shell; * define local breadcrumbs if handled globally; * create a second theme system; * bypass the established module layout pattern. Expected shell behavior: ```txt Global layout -> MainLayout -> ethiKos module layout -> EthikosPageShell -> Route page content ``` The Kintsugi upgrade is a route-content and service-contract upgrade, not a layout replacement. --- # 9. Route-by-Route Upgrade Plan --- ## 9.1 `/ethikos/deliberate/[topic]` ### Current role Topic-level deliberation page. ### Kintsugi role Primary Korum workspace for structured argumentation. This is the most important route for Kialo-style mimic. ### Canonical ownership ```yaml Primary owner: Korum Backend app: konnaxion.ethikos Current model base: - EthikosTopic - EthikosArgument - EthikosStance ``` ### First-pass upgrade targets This route SHOULD become the primary structured argument workspace. Required capabilities: ```txt Argument tree Claim detail panel Pro/con branch visualization Sources panel Topic background panel Topic-level stance capture Claim-level impact vote distinction Suggested claims queue Role-aware participation Author visibility awareness Preview drawer fix ``` ### Kialo-style mapping ```txt Kialo Discussion -> EthikosTopic Kialo Thesis -> EthikosTopic.title + description, later explicit thesis field Kialo Claim -> EthikosArgument Kialo Pro/Con relation -> EthikosArgument.parent + EthikosArgument.side Kialo Source -> ArgumentSource Kialo Impact Vote -> ArgumentImpactVote Kialo Suggested Claim -> ArgumentSuggestion ``` ### Vote separation This route MUST distinguish: ```txt EthikosStance: range: -3..+3 meaning: user stance on topic model: EthikosStance ArgumentImpactVote: range: 0..4 meaning: impact/relevance/veracity of a claim relative to its parent proposed model: ArgumentImpactVote ``` ### First-pass data additions ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` ### Deferred data additions ```txt ArgumentBookmark ArgumentLink DiscussionPerspective DiscussionTemplate DiscussionGroup DiscussionExport ``` ### OSS patterns | Source | Pattern | | ----------- | ------------------------------------------------------------ | | Kialo-style | claim graph, pro/con relation, sources, impact voting, roles | | Consider.it | reason capture and deliberative compression | | DemocracyOS | proposal-centric discussion framing | ### Required anti-drift rules ```txt Do not rename EthikosArgument to Claim. Do not create /kialo routes. Do not create konnaxion.kialo. Do not treat impact votes as stances. Do not treat impact votes as Smart Vote ballots. ``` ### Status ```txt Upgrade: required Priority: P0 Risk: medium ``` --- ## 9.2 `/ethikos/deliberate/elite` ### Current role Elite or expertise-oriented deliberation view. ### Kintsugi role Expert-informed deliberation workspace. This route SHOULD display deliberation through an expertise-aware lens without changing the baseline argument record. ### Canonical ownership ```yaml Primary owner: Korum Supporting context: EkoH Derived reading layer: Smart Vote, if needed ``` ### First-pass upgrade targets ```txt Expertise-aware topic list Expert contribution markers EkoH context visibility High-signal arguments Moderation status indicators Argument quality indicators ``` ### Data source rules This route MAY read EkoH context but MUST NOT let EkoH mutate Korum source facts. ### OSS patterns | Source | Pattern | | ----------- | ---------------------------------------- | | Kialo-style | structured argument tree | | Consider.it | reason quality and pro/con compression | | Decidim | process legitimacy and transparent roles | ### Status ```txt Upgrade: should Priority: P1 Risk: medium ``` --- ## 9.3 `/ethikos/deliberate/guidelines` ### Current role Guidelines and methodology page for deliberation. ### Kintsugi role Public explanation of Korum participation rules. ### First-pass upgrade targets ```txt Explain topic-level stance vs claim-level impact vote Explain pro/con argument tree Explain sources and evidence expectations Explain anonymous participation rules Explain suggested claim approval flow Explain moderation and role boundaries ``` ### Required cross-links ```txt /ethikos/deliberate/[topic] /ethikos/learn/glossary /ethikos/decide/methodology ``` ### Status ```txt Upgrade: required Priority: P1 Risk: low ``` --- ## 9.4 `/ethikos/decide/public` ### Current role Public decision or voting page. ### Kintsugi role Public-facing Konsultations decision workspace. ### Canonical ownership ```yaml Primary owner: Konsultations Reading publisher: Smart Vote Context provider: EkoH Related current endpoint: /api/kollective/votes/ ``` ### First-pass upgrade targets ```txt Public proposal list Open decision windows Baseline ballot capture Eligibility hints Decision protocol display Clear link to result methodology ``` ### Proposed model alignment ```txt DecisionProtocol DecisionRecord BallotEvent EligibilityRule ``` ### OSS patterns | Source | Pattern | | ---------------- | -------------------------------------- | | Loomio | proposal lifecycle and decision states | | CONSUL Democracy | eligibility, thresholds, civic gating | | DemocracyOS | proposal-centric public debate | ### Critical distinction This route captures or displays decision participation. It does not perform Smart Vote weighting directly in the source event. Smart Vote readings are derived later. ### Status ```txt Upgrade: required Priority: P0 Risk: medium ``` --- ## 9.5 `/ethikos/decide/elite` ### Current role Elite or expert-oriented decision page. ### Kintsugi role Expert-context decision workspace. ### Canonical ownership ```yaml Primary owner: Konsultations Context provider: EkoH Reading publisher: Smart Vote ``` ### First-pass upgrade targets ```txt Expert cohort visibility Eligibility context Expertise-weighted reading preview Baseline vs expert-context distinction Decision protocol metadata ``` ### Anti-drift rules ```txt Do not make EkoH the voting engine. Do not hide baseline public result. Do not replace raw ballots with weighted results. Do not mutate source ballots from this route. ``` ### OSS patterns | Source | Pattern | | ---------------- | --------------------------------------- | | Loomio | proposal lifecycle | | CONSUL Democracy | eligibility rules | | Decidim | transparent participatory process roles | ### Status ```txt Upgrade: should Priority: P1 Risk: medium-high ``` --- ## 9.6 `/ethikos/decide/results` ### Current role Results page. ### Kintsugi role Canonical result publication and reading comparison route. ### Canonical ownership ```yaml Baseline owner: Konsultations Derived readings owner: Smart Vote Snapshot context: EkoH ``` ### First-pass upgrade targets ```txt Baseline unweighted result Declared Smart Vote readings Reading metadata Lens declaration display Snapshot reference display Computed-at timestamp Comparison between baseline and derived readings ``` ### Required data concepts ```txt BaselineResult LensDeclaration ReadingResult SnapshotRef DecisionRecord ``` ### Required reading fields ```txt reading_key lens_hash snapshot_ref computed_at topic_id or consultation_id results_payload ``` ### Anti-drift rules ```txt Baseline result must remain visible. Derived readings must be labeled as readings. Derived readings must be reproducible. Smart Vote must not mutate source facts. ``` ### Status ```txt Upgrade: required Priority: P0 Risk: high ``` --- ## 9.7 `/ethikos/decide/methodology` ### Current role Methodology explanation page. ### Kintsugi role Public explanation of decision protocols, Smart Vote readings, and EkoH context. ### First-pass upgrade targets ```txt Explain baseline vs reading Explain Smart Vote lens declarations Explain EkoH snapshot context Explain eligibility rules Explain decision protocol states Explain audit/reproducibility requirements ``` ### Related docs ```txt 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md ``` ### Status ```txt Upgrade: required Priority: P1 Risk: low ``` --- ## 9.8 `/ethikos/impact/tracker` ### Current role Impact tracking route. ### Kintsugi role Canonical accountability tracker. ### Canonical ownership ```yaml Primary owner: Konsultations Downstream handoff: KeenKonnect optional, later ``` ### First-pass upgrade targets ```txt Decision-to-impact traceability Impact status Public milestones Implementation updates Blocked/completed/cancelled states Evidence links Accountability snapshots ``` ### Proposed model alignment ```txt ImpactTrack ImpactUpdate DecisionRecord ExternalArtifact ProjectionMapping ``` ### OSS patterns | Source | Pattern | | ---------------- | ----------------------------------- | | Decidim | accountability and process tracking | | CONSUL Democracy | public civic follow-through | ### Anti-drift rules ```txt Impact truth belongs to ethiKos/Konsultations. KeenKonnect may receive handoffs later. Do not make KeenKonnect Project the canonical civic impact source. ``` ### Status ```txt Upgrade: required Priority: P1 Risk: medium ``` --- ## 9.9 `/ethikos/impact/outcomes` ### Current role Outcome display. ### Kintsugi role Public outcome ledger. ### First-pass upgrade targets ```txt Published decision outcomes Outcome explanations Baseline result link Smart Vote reading link Implementation state Public accountability notes ``` ### Related routes ```txt /ethikos/decide/results /ethikos/impact/tracker /ethikos/insights ``` ### Status ```txt Upgrade: should Priority: P1 Risk: medium ``` --- ## 9.10 `/ethikos/impact/feedback` ### Current role Feedback route. ### Kintsugi role Post-decision feedback loop. ### First-pass upgrade targets ```txt Citizen feedback after decision Impact satisfaction signal Implementation concern capture Feedback-to-impact linkage Moderation state ``` ### Proposed model alignment ```txt ImpactTrack ImpactUpdate FeedbackSubmission ModerationAction ``` ### OSS patterns | Source | Pattern | | ---------------- | --------------------------------- | | Decidim | participatory accountability | | CONSUL Democracy | civic feedback and follow-through | ### Status ```txt Upgrade: should Priority: P2 Risk: low-medium ``` --- ## 9.11 `/ethikos/pulse/overview` ### Current role Pulse overview. ### Kintsugi role Civic process overview. ### First-pass upgrade targets ```txt Open topics Open decisions Active deliberations Participation volume Health summary Stage distribution ``` ### Data sources ```txt EthikosTopic EthikosArgument EthikosStance DecisionRecord ReadingResult ImpactTrack ``` ### Status ```txt Upgrade: should Priority: P2 Risk: low ``` --- ## 9.12 `/ethikos/pulse/live` ### Current role Live activity view. ### Kintsugi role Live civic activity stream. ### First-pass upgrade targets ```txt Recent arguments Recent stances Recent decision activity Recent moderation actions Recent impact updates ``` ### Anti-drift rule This route SHOULD display activity. It SHOULD NOT become a separate source of truth. ### Status ```txt Upgrade: should Priority: P2 Risk: low ``` --- ## 9.13 `/ethikos/pulse/health` ### Current role Health metrics. ### Kintsugi role Deliberation and decision health dashboard. ### First-pass upgrade targets ```txt Argument balance Participation diversity Moderation load Stance distribution Decision completion rate Impact follow-through rate ``` ### Related concepts ```txt ArgumentGraph StanceEvent DecisionRecord ReadingResult ImpactTrack ModerationAction ``` ### Status ```txt Upgrade: optional first pass Priority: P3 Risk: medium ``` --- ## 9.14 `/ethikos/pulse/trends` ### Current role Trends route. ### Kintsugi role Longitudinal civic intelligence route. ### First-pass upgrade targets ```txt Topic trend over time Stance trend over time Argument activity trend Decision trend Impact trend Reading comparison trend ``` ### Status ```txt Upgrade: optional first pass Priority: P3 Risk: medium ``` --- ## 9.15 `/ethikos/trust/profile` ### Current role Trust profile route. ### Kintsugi role User-facing EkoH trust and expertise context for civic participation. ### Canonical ownership ```yaml Primary owner: EkoH Civic display context: ethiKos ``` ### First-pass upgrade targets ```txt Expertise areas Trust context Civic contribution context Participation role context Readable explanation of influence boundaries ``` ### Anti-drift rules ```txt Trust profile does not grant hidden vote mutation. EkoH is context, not ballot engine. ``` ### Status ```txt Upgrade: should Priority: P2 Risk: medium ``` --- ## 9.16 `/ethikos/trust/badges` ### Current role Badge display. ### Kintsugi role Recognition and credibility surface. ### First-pass upgrade targets ```txt Civic participation badges Expertise badges Moderation trust markers Contribution quality markers ``` ### Status ```txt Upgrade: optional first pass Priority: P3 Risk: low ``` --- ## 9.17 `/ethikos/trust/credentials` ### Current role Credential display. ### Kintsugi role Credential and eligibility context. ### First-pass upgrade targets ```txt Credential display Eligibility explanation Expertise verification status Cohort participation context ``` ### Related routes ```txt /ethikos/decide/elite /ethikos/admin/roles /ethikos/decide/methodology ``` ### Status ```txt Upgrade: optional first pass Priority: P3 Risk: medium ``` --- ## 9.18 `/ethikos/insights` ### Current role Insights and analytics. ### Kintsugi role Cross-layer civic intelligence dashboard. ### Canonical ownership ```yaml Primary owner: ethiKos analytics Reading owner: Smart Vote Context provider: EkoH ``` ### First-pass upgrade targets ```txt Baseline result summaries Smart Vote reading summaries Topic-level participation analytics Argument graph analytics Impact/accountability analytics Cohort/lens comparison summaries ``` ### Data concepts ```txt EthikosTopic EthikosStance EthikosArgument DecisionRecord LensDeclaration ReadingResult ImpactTrack ``` ### Anti-drift rule Insights may aggregate and visualize. It MUST NOT mutate source facts. ### Status ```txt Upgrade: should Priority: P1 Risk: medium ``` --- ## 9.19 `/ethikos/admin/audit` ### Current role Audit route. ### Kintsugi role Canonical audit visibility surface. ### First-pass upgrade targets ```txt Topic events Argument events Stance events Decision events Reading computation events Moderation events Impact update events External artifact mapping events ``` ### Proposed event alignment ```txt TopicCreated StanceRecorded ArgumentCreated ArgumentUpdated ArgumentHidden ArgumentSourceAttached ArgumentImpactVoteRecorded DecisionOpened DecisionClosed ReadingComputed ImpactUpdated ModerationActionRecorded ``` ### OSS patterns | Source | Pattern | | ---------------- | ----------------------------------- | | Decidim | admin transparency and traceability | | CONSUL Democracy | governance controls | | Kialo-style | role and visibility controls | ### Status ```txt Upgrade: required Priority: P1 Risk: medium ``` --- ## 9.20 `/ethikos/admin/moderation` ### Current role Moderation route. ### Kintsugi role Korum and Konsultations moderation workspace. ### First-pass upgrade targets ```txt Moderate arguments Moderate suggested claims Moderate sources Moderate feedback Hide/unhide argument artifacts Review flagged participation Role-aware moderation permissions ``` ### Kialo-style requirements Suggested claims from restricted roles SHOULD require approval before publication. Anonymous participation MUST NOT expose identities to ordinary participants. ### Status ```txt Upgrade: required Priority: P1 Risk: medium-high ``` --- ## 9.21 `/ethikos/admin/roles` ### Current role Role management route. ### Kintsugi role Canonical civic role and permission control. ### First-pass upgrade targets ```txt Kialo-style discussion roles Decision eligibility roles Moderation roles Admin roles Expertise/credential visibility Author visibility rules Vote visibility rules ``` ### Required role values ```txt owner admin editor writer suggester viewer ``` ### Required visibility values ```txt author_visibility: - never - admins_only - all vote_visibility: - all - admins_only - self_only participation_type: - standard - anonymous ``` ### Status ```txt Upgrade: required Priority: P1 Risk: high ``` --- ## 9.22 `/ethikos/learn/glossary` ### Current role Glossary route. ### Kintsugi role Terminology stabilization route. ### First-pass upgrade targets The glossary SHOULD define: ```txt Kintsugi Korum Konsultations Smart Vote EkoH Baseline Reading Lens Snapshot Claim Argument Stance Impact Vote Decision Protocol Impact Track External Artifact Projection Mapping ``` ### Status ```txt Upgrade: required Priority: P2 Risk: low ``` --- ## 9.23 `/ethikos/learn/guides` ### Current role Guides route. ### Kintsugi role User guidance route for participation. ### First-pass upgrade targets ```txt How to deliberate How to add sources How to vote on a topic stance How to vote on claim impact How decisions work How Smart Vote readings work How accountability tracking works ``` ### Status ```txt Upgrade: should Priority: P2 Risk: low ``` --- ## 9.24 `/ethikos/learn/changelog` ### Current role Changelog route. ### Kintsugi role Public update log for Kintsugi rollout. ### First-pass upgrade targets ```txt Kintsugi phase history Route upgrade history Methodology changes Public feature status Known limitations ``` ### Status ```txt Upgrade: optional first pass Priority: P3 Risk: low ``` --- # 10. First-Pass Route Priorities ## P0 — Required for Kintsugi core ```txt /ethikos/deliberate/[topic] /ethikos/decide/public /ethikos/decide/results ``` ## P1 — Required for coherent governance ```txt /ethikos/deliberate/guidelines /ethikos/decide/elite /ethikos/decide/methodology /ethikos/impact/tracker /ethikos/impact/outcomes /ethikos/insights /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles ``` ## P2 — Should upgrade after core ```txt /ethikos/deliberate/elite /ethikos/impact/feedback /ethikos/pulse/overview /ethikos/pulse/live /ethikos/trust/profile /ethikos/learn/glossary /ethikos/learn/guides ``` ## P3 — Optional first pass ```txt /ethikos/pulse/health /ethikos/pulse/trends /ethikos/trust/badges /ethikos/trust/credentials /ethikos/learn/changelog ``` --- # 11. Route-to-Model Matrix | Route family | Current models | Proposed first-pass additions | Owner | | ----------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | `/ethikos/deliberate/*` | `EthikosTopic`, `EthikosArgument`, `EthikosStance` | `ArgumentSource`, `ArgumentImpactVote`, `ArgumentSuggestion`, `DiscussionParticipantRole`, `DiscussionVisibilitySetting` | Korum | | `/ethikos/decide/*` | `EthikosTopic`, Kollective vote models | `DecisionProtocol`, `DecisionRecord`, `BallotEvent`, `EligibilityRule` | Konsultations + Smart Vote | | `/ethikos/impact/*` | none canonical yet / possible loose project mapping | `ImpactTrack`, `ImpactUpdate` | Konsultations | | `/ethikos/pulse/*` | aggregate only | no source model required first pass | ethiKos analytics | | `/ethikos/trust/*` | EkoH context | no source model required first pass | EkoH | | `/ethikos/insights` | aggregate only | `ReadingResult`, `LensDeclaration` | Smart Vote + analytics | | `/ethikos/admin/*` | admin/audit/moderation records | `ModerationAction`, `AuditEvent` | ethiKos admin | | `/ethikos/learn/*` | static/content | no source model required | ethiKos docs UX | --- # 12. Route-to-OSS Pattern Matrix | Route | Consider.it | Kialo-style | Loomio | Citizen OS | Decidim | CONSUL | DemocracyOS | | ----------------------------- | ----------: | ----------: | ------: | ---------: | ------: | ------: | ----------: | | `/ethikos/deliberate/[topic]` | yes | yes | no | no | no | no | yes | | `/ethikos/deliberate/elite` | yes | yes | no | no | partial | no | partial | | `/ethikos/decide/public` | no | no | yes | partial | partial | yes | yes | | `/ethikos/decide/elite` | no | no | yes | partial | partial | yes | partial | | `/ethikos/decide/results` | no | no | yes | no | partial | yes | no | | `/ethikos/impact/tracker` | no | no | no | no | yes | yes | no | | `/ethikos/admin/*` | no | partial | partial | no | yes | yes | partial | | `/ethikos/learn/*` | partial | partial | partial | partial | partial | partial | partial | | `/ethikos/insights` | no | partial | partial | no | yes | partial | no | --- # 13. Legacy Endpoint Cleanup Notes The route upgrade should reduce or isolate legacy front-back links. Problematic pattern: ```txt /api/home/* ``` Policy: ```txt Do not expand this usage. Do not create new Kintsugi features on /api/home/*. Replace with /api/ethikos/*, /api/kollective/*, or future documented endpoints. If immediate replacement is unsafe, wrap behind service-layer adapter and mark legacy. ``` --- # 14. Known Bug Routing Note ## BUG-001 ```yaml title: "Deliberate preview drawer shows 'Preview / No data'" status: "known_open" route: "/ethikos/deliberate/[topic]" classification: "targeted bugfix, not architecture" ``` This bug SHOULD be fixed during or before the `/ethikos/deliberate/[topic]` Kialo-style upgrade. However, it MUST NOT be used as justification to redesign the route family, shell, or backend ownership model. Likely category: ```txt Preview drawer expects enriched topic preview shape, but receives raw topic or incompatible data. ``` Required handling: ```txt Document expected preview payload. Fix service-layer contract. Avoid new raw fetch in page component. ``` --- # 15. Anti-Drift Rules ## 15.1 Route rules ```txt Do not create /kintsugi as a product route. Do not create /kialo as a product route. Do not create /consult as a replacement for /ethikos/decide. Do not create /debate as a replacement for /ethikos/deliberate. Do not move ethiKos pages out of /ethikos/*. ``` ## 15.2 Backend rules ```txt Do not rename konnaxion.ethikos. Do not create konnaxion.kialo in first pass. Do not rename EthikosArgument to Claim. Do not remove EthikosStance. Do not rename /api/ethikos/* to /api/deliberation/*. Do not let Smart Vote mutate upstream facts. Do not let EkoH mutate ballots or stances. ``` ## 15.3 Frontend rules ```txt Do not create a second ethiKos shell. Do not bypass EthikosPageShell. Do not create a separate theme system. Do not add raw fetch calls directly in page components unless documented. Do not use route pages as data ownership sources. ``` ## 15.4 Voting rules ```txt EthikosStance = topic-level stance, range -3..+3. ArgumentImpactVote = claim-level impact score, range 0..4. Smart Vote Reading = derived result, reproducible from baseline events and lens declaration. These three must never be collapsed into one concept. ``` --- # 16. Implementation Sequencing Notes This document does not define the implementation backlog. It defines the route map that the backlog must obey. Recommended implementation order after the documentation pack is complete: ```txt 1. Fix /ethikos/deliberate/[topic] preview contract. 2. Stabilize deliberate service layer. 3. Add Kialo-style argument tree/source/impact-vote contracts. 4. Add decision protocol/result reading contracts. 5. Add Smart Vote result display contracts. 6. Add impact tracking contracts. 7. Add admin audit/moderation/roles contracts. 8. Add glossary and methodology pages. 9. Add pulse/insights refinements. ``` --- # 17. Related Docs This document depends on: ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- # 18. Final Route Contract The Kintsugi upgrade MUST land inside the existing ethiKos route surface. ```txt Kintsugi is not a new app. Kintsugi is not a new route family. Kintsugi is the route-by-route strengthening of ethiKos. ``` Canonical final mapping: ```txt /ethikos/deliberate/* = Korum structured deliberation /ethikos/decide/* = Konsultations decision + Smart Vote readings /ethikos/impact/* = Konsultations accountability /ethikos/pulse/* = civic health and live signals /ethikos/trust/* = EkoH context visibility /ethikos/admin/* = audit, moderation, roles /ethikos/learn/* = methodology and public explanation /ethikos/insights = analytics and reading comparison ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 092bfe82ef9f4bcbb31bb731fe298acbb79630835226a894738038b68ec78861 CONTENT_BYTES: 41133 ================================================================================================ # 07 — API and Service Contracts **Document ID:** `07_API_AND_SERVICE_CONTRACTS.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical contract draft **Audience:** frontend implementers, backend implementers, AI assistants, reviewers **Primary purpose:** prevent API/service drift during the Kintsugi upgrade. --- ## 1. Purpose This document defines the canonical API and frontend service contracts for the ethiKos Kintsugi upgrade. It fixes: * the backend API prefixes that are allowed; * the frontend service layer rules; * the existing ethiKos endpoints that MUST remain stable; * the compatibility aliases that MAY remain during migration; * the legacy endpoints that MUST NOT be expanded; * the new Kintsugi endpoint families that MAY be introduced later; * the anti-drift rules for generated code and parallel AI sessions. The current implementation uses Django REST Framework with a central API router. The router registers ethiKos topics, stances, arguments, optional categories, and Kollective Intelligence vote endpoints under `/api/...`. --- ## 2. Scope This document covers API and service contracts for: * ethiKos / Korum; * Konsultations; * Smart Vote; * EkoH reading context; * Kialo-style argument mapping; * Kintsugi drafting; * Kintsugi impact tracking; * frontend service modules; * legacy endpoint containment. This document does **not** define database schema details. Schema belongs to: ```txt 08_DATA_MODEL_AND_MIGRATION_PLAN.md ``` This document does **not** define serializer payloads in full detail. Payload shapes belong to: ```txt 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md ``` This document does **not** define frontend layout rules beyond API/service access. Frontend layout belongs to: ```txt 14_FRONTEND_ALIGNMENT_CONTRACT.md ``` --- ## 3. Canonical Variables Used ```yaml DOCUMENT_ID: "07_API_AND_SERVICE_CONTRACTS.md" PRIMARY_API_BASE: "/api/" PRIMARY_FRONTEND_ROUTE_SURFACE: "/ethikos/*" BACKEND_STYLE: "Django REST Framework ViewSet + Serializer + Router" API_ROUTER_FILE: "backend/config/api_router.py" ROOT_URLCONF: "config.urls" AUTH_USER_MODEL: "users.User" ETHIKOS_BACKEND_APP: "konnaxion.ethikos" KOLLECTIVE_BACKEND_APP: "konnaxion.kollective_intelligence" EKOH_BACKEND_APP: "konnaxion.ekoh" FRONTEND_SERVICE_LAYER_REQUIRED: true RAW_FETCH_FROM_COMPONENTS_ALLOWED: false GRAPHQL_FOR_CORE_CRUD_ALLOWED: false WEBSOCKET_FOR_CORE_CRUD_ALLOWED: false CANONICAL_ETHIKOS_ENDPOINTS: TOPICS: "/api/ethikos/topics/" STANCES: "/api/ethikos/stances/" ARGUMENTS: "/api/ethikos/arguments/" CATEGORIES: "/api/ethikos/categories/" CANONICAL_KOLLECTIVE_ENDPOINTS: VOTES: "/api/kollective/votes/" VOTE_RESULTS: "/api/kollective/vote-results/" COMPATIBILITY_ENDPOINTS: DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." LEGACY_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" LEGACY_ENDPOINT_POLICY: "Do not expand. Replace, isolate, or mark as legacy." ``` --- ## 4. Source of Truth For implementation reality, the source of truth is: ```txt backend/config/api_router.py ``` The router currently registers: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ optional /api/kollective/votes/ optional /api/kollective/vote-results/ optional ``` The existing technical contract also states that frontend code should access ethiKos through a service module wrapping `/api/ethikos/...` and `/api/deliberate/...`, not through ad hoc component-level calls. When this document conflicts with older speculative docs, this document wins for API/service alignment. When this document conflicts with the code snapshot, the code snapshot wins for current implementation reality, and this document should be updated. --- ## 5. Core API Principles ### 5.1 REST First Kintsugi API work MUST use REST over HTTP by default. ```yaml DEFAULT_API_STYLE: "REST" DEFAULT_BACKEND_PATTERN: "DRF ViewSet + Serializer + Router" DEFAULT_FRONTEND_PATTERN: "services/* wrapper" ``` GraphQL MUST NOT be introduced for ethiKos CRUD unless a future ADR explicitly approves it. WebSockets MUST NOT be introduced for ethiKos CRUD. Realtime features MAY later use WebSockets only for live updates, not for canonical record creation. --- ### 5.2 Service Layer Required Frontend pages MUST NOT directly call backend endpoints unless the file is itself part of the service layer. Allowed: ```ts import { fetchTopicDetail } from "@/services/deliberate"; import { getEthikosTopics } from "@/services/ethikos"; ``` Avoid: ```ts fetch("/api/ethikos/topics/"); ``` Preferred service locations: ```txt frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/admin.ts frontend/services/trust.ts frontend/services/learn.ts frontend/services/insights.ts ``` The existing AI guidance explicitly says that frontend API calls should use the services layer, respect `/api/...` prefixes, avoid inventing paths, and avoid renaming `/api/ethikos/...` to `/api/deliberation/...`. --- ### 5.3 Canonical Prefixes Must Stay Stable The following prefixes MUST NOT be renamed: ```txt /api/ethikos/ /api/kollective/ /api/users/ /api/keenkonnect/ /api/konnected/ /api/kreative/ ``` For this upgrade, ethiKos Kintsugi work MUST primarily use: ```txt /api/ethikos/* /api/kollective/* ``` Future EkoH-specific endpoints MAY use: ```txt /api/ekoh/* ``` only if already present or added by an explicit backend contract. --- ### 5.4 Compatibility Aliases Are Transitional The following aliases MAY remain during the Kintsugi upgrade: ```txt /api/deliberate/... /api/deliberate/elite/... ``` They MUST NOT become the preferred canonical API. Preferred API: ```txt /api/ethikos/* ``` Compatibility API: ```txt /api/deliberate/* ``` --- ### 5.5 Legacy `/api/home/*` Must Not Expand The endpoint graph shows direct legacy calls to `/api/home/categories/`, `/api/home/debatecategory/`, `/api/home/debatetopic/`, `/api/home/responseformat/`, `/api/home/publicvote/`, and `/api/home/debatetopic/${topic.id}/vote`. These are direct API usages outside the intended ethiKos/Kollective service contracts. Policy: ```yaml API_HOME_USAGE: STATUS: "legacy/problematic" MAY_ADD_NEW_CALLS: false MAY_WRAP_FOR_MIGRATION: true MUST_REPLACE_LONG_TERM: true TARGET_REPLACEMENT: TOPICS: "/api/ethikos/topics/" STANCES: "/api/ethikos/stances/" ARGUMENTS: "/api/ethikos/arguments/" VOTES: "/api/kollective/votes/" ``` --- ## 6. Current Canonical Endpoint Registry ## 6.1 ethiKos Core ### `/api/ethikos/topics/` Backend: ```yaml ROUTE: "/api/ethikos/topics/" VIEWSET: "TopicViewSet" MODEL: "EthikosTopic" APP: "konnaxion.ethikos" OWNER: "Korum / ethiKos core" ``` Allowed operations: ```yaml LIST: METHOD: "GET" PATH: "/api/ethikos/topics/" AUTH: "public read allowed" CREATE: METHOD: "POST" PATH: "/api/ethikos/topics/" AUTH: "authenticated" RETRIEVE: METHOD: "GET" PATH: "/api/ethikos/topics/{id}/" AUTH: "public read allowed" UPDATE: METHOD: "PATCH" PATH: "/api/ethikos/topics/{id}/" AUTH: "owner/admin" DELETE: METHOD: "DELETE" PATH: "/api/ethikos/topics/{id}/" AUTH: "owner/admin" ``` Known supported query params: ```yaml QUERY_PARAMS: category: "Filter by category id." status: "Filter by topic status." ``` Topic creation MUST resolve category by `category` or `category_id`, not by arbitrary label strings at the backend boundary. Existing frontend service code already resolves category labels to IDs before posting to `ethikos/topics/`. --- ### `/api/ethikos/topics/{id}/preview/` Backend: ```yaml ROUTE: "/api/ethikos/topics/{id}/preview/" VIEWSET_ACTION: "TopicViewSet.preview" MODEL: "EthikosTopic" APP: "konnaxion.ethikos" OWNER: "Korum / ethiKos core" ``` Purpose: ```txt Return a minimal topic preview for the Deliberate preview drawer. ``` Required behavior: * MUST return topic metadata even if related arguments fail to load. * MUST NOT return an empty shape when the topic exists. * MUST be resilient enough to prevent the visible `Preview / No data` drawer bug. Frontend service SHOULD expose: ```ts fetchTopicPreview(id: string): Promise ``` Current implementation already contains a frontend `fetchTopicPreview` that retrieves topic metadata from `ethikos/topics/{topicId}/` and attempts to load latest arguments from `ethikos/arguments/?topic=`. --- ### `/api/ethikos/stances/` Backend: ```yaml ROUTE: "/api/ethikos/stances/" VIEWSET: "StanceViewSet" MODEL: "EthikosStance" APP: "konnaxion.ethikos" OWNER: "Korum" ``` Semantic contract: ```yaml STANCE_LEVEL: "topic-level" STANCE_RANGE: "-3..+3" ONE_STANCE_PER_USER_TOPIC: true IS_KIALO_IMPACT_VOTE: false IS_SMART_VOTE_READING: false ``` Allowed operations: ```yaml LIST: METHOD: "GET" PATH: "/api/ethikos/stances/" CREATE_OR_UPDATE: METHOD: "POST" PATH: "/api/ethikos/stances/" AUTH: "authenticated" RETRIEVE: METHOD: "GET" PATH: "/api/ethikos/stances/{id}/" UPDATE: METHOD: "PATCH" PATH: "/api/ethikos/stances/{id}/" AUTH: "owner/admin" DELETE: METHOD: "DELETE" PATH: "/api/ethikos/stances/{id}/" AUTH: "owner/admin" ``` Known supported query params: ```yaml QUERY_PARAMS: topic: "Filter by topic id." ``` Frontend examples MAY aggregate stances by topic for consultation-style result buckets. Current Konsultations result hooks already map a consultation to an Ethikos topic and aggregate rows from `GET /api/ethikos/stances/?topic=`. --- ### `/api/ethikos/arguments/` Backend: ```yaml ROUTE: "/api/ethikos/arguments/" VIEWSET: "ArgumentViewSet" MODEL: "EthikosArgument" APP: "konnaxion.ethikos" OWNER: "Korum" ``` Semantic contract: ```yaml ARGUMENT_LEVEL: "topic discussion / claim-like argument" ARGUMENT_TREE_SUPPORTED: true TREE_MECHANISM: "parent + side" SIDE_VALUES: - "pro" - "con" - null KIALO_CLAIM_MAPPING: "EthikosArgument" ``` Allowed operations: ```yaml LIST: METHOD: "GET" PATH: "/api/ethikos/arguments/" CREATE: METHOD: "POST" PATH: "/api/ethikos/arguments/" AUTH: "authenticated" RETRIEVE: METHOD: "GET" PATH: "/api/ethikos/arguments/{id}/" UPDATE: METHOD: "PATCH" PATH: "/api/ethikos/arguments/{id}/" AUTH: "owner/admin" DELETE: METHOD: "DELETE" PATH: "/api/ethikos/arguments/{id}/" AUTH: "owner/admin" ``` Known supported query params: ```yaml QUERY_PARAMS: topic: "Filter by topic id." parent: "Optional future filter for child arguments." side: "Optional future filter for pro/con/neutral side." ``` Rules: * `EthikosArgument` MUST NOT be renamed to `Claim`. * Kialo-style “claim” language MAY be used in UI, but backend model naming remains `EthikosArgument`. * `EthikosArgument.side` MUST NOT be used as a Smart Vote ballot. * `EthikosArgument.parent + side` is the first-pass argument graph contract. --- ### `/api/ethikos/categories/` Backend: ```yaml ROUTE: "/api/ethikos/categories/" VIEWSET: "CategoryViewSet" or "EthikosCategoryViewSet" MODEL: "EthikosCategory" APP: "konnaxion.ethikos" OWNER: "Korum / ethiKos core" OPTIONAL: true ``` Current router registers categories only if the ViewSet exists. Allowed operations: ```yaml LIST: METHOD: "GET" PATH: "/api/ethikos/categories/" AUTH: "public read allowed" RETRIEVE: METHOD: "GET" PATH: "/api/ethikos/categories/{id}/" AUTH: "public read allowed" ``` First-pass policy: ```yaml CATEGORY_CREATION_FROM_FRONTEND: false CATEGORY_READ_ONLY_DEFAULT: true ``` --- ## 6.2 Kollective Intelligence / Smart Vote ### `/api/kollective/votes/` Backend: ```yaml ROUTE: "/api/kollective/votes/" VIEWSET: "VoteViewSet" APP: "konnaxion.kollective_intelligence" OWNER: "Kollective Intelligence / Smart Vote" OPTIONAL_IN_CURRENT_ROUTER: true ``` Current router registers `kollective/votes` optionally when `VoteViewSet` exists. Contract: ```yaml PURPOSE: "Formal vote capture for decision workflows." MUST_NOT_REPLACE_ETHIKOS_STANCES: true MUST_NOT_REPLACE_KIALO_IMPACT_VOTES: true USED_BY: - "/ethikos/decide/public" - "/ethikos/decide/elite" - "/ethikos/decide/results" ``` Frontend service: ```txt frontend/services/decide.ts ``` Current endpoint graph marks `services/decide.ts` as loosely mapped to `api/kollective/votes`, so Kintsugi must convert this loose mapping into a formal contract before implementation. --- ### `/api/kollective/vote-results/` Backend: ```yaml ROUTE: "/api/kollective/vote-results/" VIEWSET: "VoteResultViewSet" APP: "konnaxion.kollective_intelligence" OWNER: "Kollective Intelligence / Smart Vote" OPTIONAL_IN_CURRENT_ROUTER: true ``` Contract: ```yaml PURPOSE: "Raw or baseline vote result retrieval." MUST_NOT_MIX_WITH_READING_RESULT: true ``` Kintsugi readings SHOULD be separated into explicit reading result models/endpoints, not hidden inside baseline vote results. --- ## 6.3 Users ### `/api/users/me/` Backend: ```yaml ROUTE: "/api/users/me/" OWNER: "users" PURPOSE: "Current authenticated user" ``` Use cases: * frontend session awareness; * ownership checks; * admin visibility; * role-aware Kintsugi UI. The smoke test verifies `/api/users/me/` as part of the platform baseline. --- ## 7. Kintsugi Proposed Endpoint Families The endpoints in this section are **proposed contracts**, not necessarily current implementation. They MUST NOT be generated as code until the corresponding data model and serializer contracts are approved. --- ## 7.1 Decision Protocols ```yaml PROPOSED_ENDPOINT: "/api/ethikos/decision-protocols/" APP: "konnaxion.ethikos" MODEL: "DecisionProtocol" OWNER: "Konsultations / Decision layer coordination" STATUS: "proposed" ``` Purpose: ```txt Define reusable decision protocol templates for ethiKos decision workflows. ``` Expected service: ```txt frontend/services/decide.ts ``` Allowed first-pass operations: ```yaml LIST: "GET /api/ethikos/decision-protocols/" RETRIEVE: "GET /api/ethikos/decision-protocols/{id}/" CREATE: "POST /api/ethikos/decision-protocols/" UPDATE: "PATCH /api/ethikos/decision-protocols/{id}/" ``` Non-goal: ```txt Do not use DecisionProtocol as a replacement for Smart Vote readings. ``` --- ## 7.2 Decision Records ```yaml PROPOSED_ENDPOINT: "/api/ethikos/decision-records/" APP: "konnaxion.ethikos" MODEL: "DecisionRecord" OWNER: "Konsultations + Smart Vote publication boundary" STATUS: "proposed" ``` Purpose: ```txt Represent a concrete decision instance attached to an ethiKos topic, consultation, or proposal. ``` Expected service: ```txt frontend/services/decide.ts ``` Contract: ```yaml DECISION_RECORD_MAY_REFERENCE: - "EthikosTopic" - "DecisionProtocol" - "BaselineResult" - "ReadingResult" DECISION_RECORD_MUST_NOT: - "mutate raw stances" - "mutate raw ballots" - "hide baseline result" ``` --- ## 7.3 Lens Declarations ```yaml PROPOSED_ENDPOINT: "/api/kollective/lens-declarations/" APP: "konnaxion.kollective_intelligence" MODEL: "LensDeclaration" OWNER: "Smart Vote" STATUS: "proposed" ``` Purpose: ```txt Declare the formula, cohort, weighting, and audit context used to compute a Smart Vote reading. ``` Contract: ```yaml REQUIRED_CONCEPTS: - "reading_key" - "lens_hash" - "snapshot_ref" - "computed_at" ``` Smart Vote readings must remain reproducible and must not mutate baseline facts. The boundary document explicitly requires reading audit fields such as `reading_key`, `lens_hash`, `ekoh_snapshot_id` or `snapshot_ref`. --- ## 7.4 Reading Results ```yaml PROPOSED_ENDPOINT: "/api/kollective/reading-results/" APP: "konnaxion.kollective_intelligence" MODEL: "ReadingResult" OWNER: "Smart Vote" STATUS: "proposed" ``` Purpose: ```txt Publish derived Smart Vote readings computed from baseline events and declared lenses. ``` Contract: ```yaml READING_RESULT_IS_DERIVED: true READING_RESULT_IS_SOURCE_FACT: false MUST_INCLUDE_BASELINE_REFERENCE: true MUST_INCLUDE_LENS_DECLARATION_REFERENCE: true MAY_INCLUDE_EKOH_SNAPSHOT_REFERENCE: true ``` Allowed first-pass operations: ```yaml LIST: "GET /api/kollective/reading-results/" RETRIEVE: "GET /api/kollective/reading-results/{id}/" CREATE: "POST /api/kollective/reading-results/" ``` Write policy: ```txt Only trusted backend/admin processes should create computed readings. ``` --- ## 7.5 Drafts ```yaml PROPOSED_ENDPOINT: "/api/ethikos/drafts/" APP: "konnaxion.ethikos" MODEL: "Draft" OWNER: "ethiKos bounded drafting capability" STATUS: "proposed" ``` Purpose: ```txt Represent draft text created from deliberation and consultation workflows. ``` Expected services: ```txt frontend/services/drafting.ts frontend/services/decide.ts ``` Contract: ```yaml DRAFT_MAY_REFERENCE: - "EthikosTopic" - "DecisionRecord" - "RationalePacket" DRAFT_MUST_NOT: - "overwrite topic" - "overwrite arguments" - "be stored inside EthikosArgument" ``` --- ## 7.6 Draft Versions ```yaml PROPOSED_ENDPOINT: "/api/ethikos/draft-versions/" APP: "konnaxion.ethikos" MODEL: "DraftVersion" OWNER: "ethiKos bounded drafting capability" STATUS: "proposed" ``` Purpose: ```txt Version history for collaborative drafting. ``` Contract: ```yaml VERSION_HISTORY_REQUIRED: true MUST_BE_APPEND_FRIENDLY: true MUST_SUPPORT_AUDIT: true ``` --- ## 7.7 Amendments ```yaml PROPOSED_ENDPOINT: "/api/ethikos/amendments/" APP: "konnaxion.ethikos" MODEL: "Amendment" OWNER: "ethiKos bounded drafting capability" STATUS: "proposed" ``` Purpose: ```txt Represent proposed edits to a draft. ``` Contract: ```yaml AMENDMENT_MAY_REFERENCE: - "Draft" - "DraftVersion" - "EthikosArgument" AMENDMENT_STATUS_VALUES: - "draft" - "submitted" - "accepted" - "rejected" - "superseded" ``` --- ## 7.8 Impact Tracks ```yaml PROPOSED_ENDPOINT: "/api/ethikos/impact-tracks/" APP: "konnaxion.ethikos" MODEL: "ImpactTrack" OWNER: "Konsultations accountability" STATUS: "proposed" ``` Purpose: ```txt Track implementation, feedback, outcomes, and public accountability after a decision. ``` Expected service: ```txt frontend/services/impact.ts ``` Current risk: ```txt The existing endpoint graph loosely maps impact service calls to KeenKonnect ProjectViewSet/Project. ``` Policy: ```yaml IMPACT_TRUTH_OWNER: "ethiKos / Konsultations" KEENKONNECT_MAY_RECEIVE_HANDOFF: true KEENKONNECT_MUST_NOT_OWN_CIVIC_IMPACT_TRUTH: true ``` The current graph shows `/impact/feedback`, `/impact/outcomes`, and `/impact/tracker` loosely mapped to `api/keenkonnect/projects`; Kintsugi must formalize native ethiKos/Konsultations impact endpoints instead of relying on KeenKonnect as the source of truth. --- ## 7.9 External Artifacts ```yaml PROPOSED_ENDPOINT: "/api/ethikos/external-artifacts/" APP: "konnaxion.ethikos" MODEL: "ExternalArtifact" OWNER: "Mimic/Annex boundary" STATUS: "proposed" ``` Purpose: ```txt Represent external civic-tech artifacts without allowing external tools to write into core ethiKos tables. ``` Contract: ```yaml FOREIGN_TOOLS_WRITE_CORE_TABLES: false EXTERNAL_ARTIFACT_IS_REFERENCE_ONLY: true ``` --- ## 7.10 Projection Mappings ```yaml PROPOSED_ENDPOINT: "/api/ethikos/projection-mappings/" APP: "konnaxion.ethikos" MODEL: "ProjectionMapping" OWNER: "Mimic/Annex boundary" STATUS: "proposed" ``` Purpose: ```txt Map external artifacts to native ethiKos objects without duplicating canonical truth. ``` Contract: ```yaml PROJECTION_MAPPING_MAY_LINK: - "ExternalArtifact" - "EthikosTopic" - "EthikosArgument" - "DecisionRecord" - "ImpactTrack" PROJECTION_MAPPING_MUST_NOT: - "modify source facts" - "replace native ownership" ``` --- ## 8. Kialo-Style Endpoint Contracts The Kialo-style contract is native mimic inside ethiKos. ```yaml KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_APP: false CREATE_KIALO_ROUTE_FAMILY: false IMPORT_KIALO_CODE: false ``` --- ## 8.1 Argument Sources ```yaml PROPOSED_ENDPOINT: "/api/ethikos/argument-sources/" APP: "konnaxion.ethikos" MODEL: "ArgumentSource" OWNER: "Korum" STATUS: "proposed" ``` Purpose: ```txt Attach source/citation evidence to an EthikosArgument. ``` Expected service: ```txt frontend/services/deliberate.ts ``` Contract: ```yaml ARGUMENT_SOURCE_MUST_REFERENCE: "EthikosArgument" ARGUMENT_SOURCE_MUST_NOT_CREATE_ARGUMENT: true ``` --- ## 8.2 Argument Impact Votes ```yaml PROPOSED_ENDPOINT: "/api/ethikos/argument-impact-votes/" APP: "konnaxion.ethikos" MODEL: "ArgumentImpactVote" OWNER: "Korum" STATUS: "proposed" ``` Purpose: ```txt Capture Kialo-style claim impact ratings at argument/claim level. ``` Contract: ```yaml IMPACT_VOTE_RANGE: "0..4" IMPACT_VOTE_LEVEL: "argument-level" IS_TOPIC_STANCE: false IS_SMART_VOTE_BALLOT: false IS_BASELINE_READING: false ``` Must remain separate from: ```txt /api/ethikos/stances/ /api/kollective/votes/ /api/kollective/reading-results/ ``` --- ## 8.3 Argument Suggestions ```yaml PROPOSED_ENDPOINT: "/api/ethikos/argument-suggestions/" APP: "konnaxion.ethikos" MODEL: "ArgumentSuggestion" OWNER: "Korum" STATUS: "proposed" ``` Purpose: ```txt Allow users with limited permissions to suggest claims/arguments before publication. ``` Contract: ```yaml SUGGESTER_ROLE_REQUIRES_APPROVAL: true SUGGESTION_IS_NOT_PUBLISHED_ARGUMENT: true ACCEPTED_SUGGESTION_MAY_CREATE_ARGUMENT: true ``` --- ## 8.4 Discussion Participant Roles ```yaml PROPOSED_ENDPOINT: "/api/ethikos/discussion-participant-roles/" APP: "konnaxion.ethikos" MODEL: "DiscussionParticipantRole" OWNER: "Korum" STATUS: "proposed" ``` Purpose: ```txt Represent owner/admin/editor/writer/suggester/viewer roles for a topic discussion. ``` Contract: ```yaml ROLE_VALUES: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" ``` --- ## 8.5 Discussion Visibility Settings ```yaml PROPOSED_ENDPOINT: "/api/ethikos/discussion-visibility-settings/" APP: "konnaxion.ethikos" MODEL: "DiscussionVisibilitySetting" OWNER: "Korum" STATUS: "proposed" ``` Purpose: ```txt Control author visibility, vote visibility, and anonymous participation settings. ``` Contract: ```yaml AUTHOR_VISIBILITY_VALUES: - "never" - "admins_only" - "all" VOTE_VISIBILITY_VALUES: - "all" - "admins_only" - "self_only" PARTICIPATION_TYPE_VALUES: - "standard" - "anonymous" ``` --- ## 9. Frontend Service Contracts ## 9.1 `frontend/services/ethikos.ts` Role: ```txt Canonical low-level service wrapper for /api/ethikos/*. ``` Responsibilities: ```yaml MUST_WRAP: - "/api/ethikos/topics/" - "/api/ethikos/stances/" - "/api/ethikos/arguments/" - "/api/ethikos/categories/" MAY_WRAP_PROPOSED: - "/api/ethikos/argument-sources/" - "/api/ethikos/argument-impact-votes/" - "/api/ethikos/argument-suggestions/" - "/api/ethikos/decision-records/" - "/api/ethikos/drafts/" - "/api/ethikos/impact-tracks/" ``` Must export typed functions, not raw path strings scattered across pages. --- ## 9.2 `frontend/services/deliberate.ts` Role: ```txt Route/domain service for /ethikos/deliberate/* screens. ``` Current responsibilities: ```yaml FETCH_ELITE_TOPICS: true CREATE_ELITE_TOPIC: true FETCH_TOPIC_DETAIL: true FETCH_TOPIC_PREVIEW: true ``` Target responsibilities: ```yaml SHOULD_USE_CANONICAL_ETHIKOS_SERVICE: true SHOULD_NOT_CALL_LEGACY_HOME_API: true MAY_ADAPT_UI_SHAPES: true MUST_NOT_OWN_RAW_HTTP_CLIENT: true ``` Allowed backend targets: ```txt /api/ethikos/topics/ /api/ethikos/topics/{id}/preview/ /api/ethikos/arguments/ /api/ethikos/stances/ /api/ethikos/categories/ ``` Future allowed targets: ```txt /api/ethikos/argument-sources/ /api/ethikos/argument-impact-votes/ /api/ethikos/argument-suggestions/ /api/ethikos/discussion-participant-roles/ /api/ethikos/discussion-visibility-settings/ ``` --- ## 9.3 `frontend/services/decide.ts` Role: ```txt Route/domain service for /ethikos/decide/* screens. ``` Current graph status: ```yaml CURRENT_MAPPING: "loose" CURRENT_BACKEND_TARGET: "api/kollective/votes" ``` Allowed backend targets: ```txt /api/kollective/votes/ /api/kollective/vote-results/ ``` Future allowed targets: ```txt /api/ethikos/decision-protocols/ /api/ethikos/decision-records/ /api/kollective/lens-declarations/ /api/kollective/reading-results/ ``` Rules: * MUST NOT write to `EthikosStance` when capturing formal ballots. * MUST NOT hide baseline results behind weighted readings. * MUST distinguish public ballot, elite ballot, result publication, and Smart Vote reading. --- ## 9.4 `frontend/services/impact.ts` Role: ```txt Route/domain service for /ethikos/impact/* screens. ``` Current graph status: ```yaml CURRENT_MAPPING: "loose" CURRENT_BACKEND_TARGET: "api/keenkonnect/projects" ``` Target backend: ```txt /api/ethikos/impact-tracks/ ``` Transitional policy: ```yaml MAY_READ_KEENKONNECT_HANDOFFS: true MUST_NOT_TREAT_KEENKONNECT_PROJECT_AS_IMPACT_TRUTH: true MUST_MIGRATE_TO_NATIVE_IMPACT_CONTRACT: true ``` --- ## 9.5 `frontend/services/pulse.ts` Role: ```txt Route/domain service for /ethikos/pulse/* screens. ``` Allowed current backend targets: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ ``` Future allowed targets: ```txt /api/ethikos/impact-tracks/ /api/kollective/reading-results/ ``` Rules: * Pulse may aggregate. * Pulse must not mutate. * Pulse must not define new truth. --- ## 9.6 `frontend/services/insights.ts` Role: ```txt Route/domain service for /ethikos/insights. ``` Allowed current backend targets: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/kollective/vote-results/ ``` Future allowed targets: ```txt /api/kollective/lens-declarations/ /api/kollective/reading-results/ ``` Rules: * Insights may compare baseline and derived readings. * Insights must label all weighted/filtered readings clearly. * Insights must not mutate upstream facts. --- ## 9.7 `frontend/services/admin.ts` Role: ```txt Route/domain service for /ethikos/admin/* screens. ``` Current graph status: ```yaml CURRENT_MAPPING: "unmapped" ``` Future allowed targets: ```txt /api/ethikos/moderation-actions/ /api/ethikos/discussion-participant-roles/ /api/ethikos/discussion-visibility-settings/ /api/ethikos/audit-events/ ``` Until backend endpoints exist, admin services MUST use mock/demo data only if clearly marked. --- ## 10. Request / Response Rules ## 10.1 ID Types ```yaml CURRENT_ETHIKOS_ID_TYPE: "integer" FRONTEND_ROUTE_PARAM_TYPE: "string" SERVICE_LAYER_RESPONSIBILITY: "convert route string ids to numeric ids before API calls" ``` Example: ```ts const topicId = Number(id); if (!Number.isFinite(topicId)) { throw new Error("Invalid topic id"); } ``` --- ## 10.2 Date Format ```yaml DATE_FORMAT: "ISO_8601" DATE_FIELDS_COMMON: - "created_at" - "updated_at" - "last_activity" - "timestamp" - "computed_at" ``` Services MAY adapt dates for UI display, but MUST NOT change canonical API date fields. --- ## 10.3 Pagination Current DRF endpoints may return either arrays or paginated results depending on ViewSet configuration. Service functions SHOULD normalize where needed. Recommended helper behavior: ```ts type DrfList = T[] | { results: T[] }; function unwrapList(value: DrfList): T[] { return Array.isArray(value) ? value : value.results; } ``` --- ## 10.4 Errors Backend errors SHOULD remain DRF-compatible. Frontend services SHOULD normalize errors into: ```ts type ServiceError = { message: string; status?: number; details?: unknown; }; ``` Do not hide backend validation errors during Kintsugi work. --- ## 11. Authentication, Authorization, and CSRF ## 11.1 Authentication Current assumptions: ```yaml AUTH_USER_MODEL: "users.User" AUTH_REQUIRED_FOR_WRITES: true PUBLIC_READ_ALLOWED_FOR_CORE_DELIBERATION: true ``` Default rules: ```yaml GET_PUBLIC_TOPICS: "allowed" GET_PUBLIC_ARGUMENTS: "allowed" GET_PUBLIC_CATEGORIES: "allowed" POST_TOPIC: "authenticated" POST_STANCE: "authenticated" POST_ARGUMENT: "authenticated" POST_VOTE: "authenticated" POST_READING_RESULT: "trusted/admin/system" ``` --- ## 11.2 Ownership Current backend permissions include an owner-or-read-only pattern for topics, stances, and arguments. Topic ownership uses `created_by`; stance/argument ownership uses `user`. Contract: ```yaml TOPIC_OWNER_FIELD: "created_by" STANCE_OWNER_FIELD: "user" ARGUMENT_OWNER_FIELD: "user" SAFE_METHODS_PUBLIC_READ: true WRITE_OWNER_OR_ADMIN: true ``` --- ## 11.3 CSRF For browser-originated writes, service modules MUST use the existing request helper or client mechanism that already handles CSRF/session behavior. Do not implement a second CSRF client. Do not bypass CSRF to “fix” write failures. --- ## 12. Endpoint Status Matrix | Endpoint | Status | Owner | Frontend service | Notes | | ------------------------------------- | -----------------: | ----------------------- | ---------------------------------------- | -------------------------------- | | `/api/ethikos/topics/` | canonical current | Korum | `ethikos`, `deliberate`, `pulse` | Keep stable | | `/api/ethikos/topics/{id}/preview/` | current/target | Korum | `deliberate` | Must fix preview shape if needed | | `/api/ethikos/stances/` | canonical current | Korum | `ethikos`, `decide`, `pulse`, `insights` | Topic-level stance only | | `/api/ethikos/arguments/` | canonical current | Korum | `ethikos`, `deliberate`, `pulse` | Argument graph base | | `/api/ethikos/categories/` | optional current | ethiKos core | `ethikos`, `deliberate` | Read-only default | | `/api/kollective/votes/` | optional current | Smart Vote / Kollective | `decide` | Formal vote, not stance | | `/api/kollective/vote-results/` | optional current | Smart Vote / Kollective | `decide`, `insights` | Baseline result, not reading | | `/api/deliberate/...` | compatibility | Korum | `deliberate` | Transitional alias | | `/api/deliberate/elite/...` | compatibility | Korum | `deliberate` | Transitional alias | | `/api/home/*` | legacy/problematic | legacy | none preferred | Do not expand | | `/api/ethikos/decision-protocols/` | proposed | Konsultations/Decision | `decide` | Requires model/serializer | | `/api/ethikos/decision-records/` | proposed | Konsultations/Decision | `decide` | Requires model/serializer | | `/api/kollective/lens-declarations/` | proposed | Smart Vote | `decide`, `insights` | Requires model/serializer | | `/api/kollective/reading-results/` | proposed | Smart Vote | `decide`, `insights` | Derived readings | | `/api/ethikos/drafts/` | proposed | Drafting | `drafting`, `decide` | Bounded drafting | | `/api/ethikos/draft-versions/` | proposed | Drafting | `drafting` | Version history | | `/api/ethikos/amendments/` | proposed | Drafting | `drafting` | Amendment workflow | | `/api/ethikos/impact-tracks/` | proposed | Konsultations | `impact` | Native impact truth | | `/api/ethikos/argument-sources/` | proposed | Korum | `deliberate` | Kialo-style sources | | `/api/ethikos/argument-impact-votes/` | proposed | Korum | `deliberate` | Not stance, not ballot | | `/api/ethikos/argument-suggestions/` | proposed | Korum | `deliberate` | Role-aware suggestions | --- ## 13. Compatibility Rules ## 13.1 Compatibility Aliases Compatibility aliases may exist: ```txt /api/deliberate/... /api/deliberate/elite/... ``` Rules: ```yaml MAY_KEEP_FOR_EXISTING_FRONTEND: true MAY_USE_FOR_TRANSITION: true MUST_NOT_BE_PRIMARY_FOR_NEW_DOCS: true MUST_NOT_EXPAND_IF_CANONICAL_ETHIKOS_ENDPOINT_EXISTS: true ``` --- ## 13.2 Legacy Home API Legacy home endpoints: ```txt /api/home/categories/ /api/home/debatecategory/ /api/home/debatetopic/ /api/home/responseformat/ /api/home/publicvote/ /api/home/debatetopic/{id}/vote ``` Rules: ```yaml MAY_ADD_NEW_HOME_ENDPOINTS: false MAY_WRAP_EXISTING_HOME_ENDPOINTS_TEMPORARILY: true MUST_CREATE_REPLACEMENT_PLAN: true TARGET_REPLACEMENT_PREFIXES: - "/api/ethikos/" - "/api/kollective/" ``` --- ## 14. Service Function Naming Rules Service function names SHOULD be domain-readable and stable. Preferred examples: ```ts fetchEthikosTopics() fetchTopicDetail(topicId) fetchTopicPreview(topicId) createEthikosTopic(payload) submitTopicStance(topicId, value) fetchTopicArguments(topicId) createTopicArgument(payload) fetchPublicBallots() submitPublicVote(ballotId, payload) fetchDecisionResults() fetchReadingResults(params) fetchImpactTracks() updateImpactTrackStatus(id, payload) submitArgumentImpactVote(argumentId, value) submitArgumentSuggestion(topicId, payload) attachArgumentSource(argumentId, payload) ``` Avoid vague names: ```ts getData() postVote() loadStuff() submit() fetchPreviewData() ``` --- ## 15. Cross-Service Ownership Rules ## 15.1 Deliberate / Korum Allowed data sources: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` Future allowed data sources: ```txt /api/ethikos/argument-sources/ /api/ethikos/argument-impact-votes/ /api/ethikos/argument-suggestions/ ``` Must not call: ```txt /api/home/* ``` --- ## 15.2 Decide / Smart Vote Allowed data sources: ```txt /api/kollective/votes/ /api/kollective/vote-results/ ``` Future allowed data sources: ```txt /api/ethikos/decision-protocols/ /api/ethikos/decision-records/ /api/kollective/lens-declarations/ /api/kollective/reading-results/ ``` Must not confuse: ```txt EthikosStance != Vote ArgumentImpactVote != Vote ReadingResult != Vote ``` --- ## 15.3 Impact / Konsultations Target data source: ```txt /api/ethikos/impact-tracks/ ``` Transitional data source: ```txt /api/keenkonnect/projects/ ``` Rule: ```txt KeenKonnect may represent project handoff, but it must not own civic accountability truth. ``` --- ## 15.4 Trust / EkoH Allowed future data source: ```txt /api/ekoh/* ``` or existing EkoH-backed services if present. Trust screens MAY display: * expertise context; * credential context; * ethical context; * cohort eligibility context. Trust screens MUST NOT: * compute formal votes; * mutate Smart Vote readings; * mutate ethiKos stances. --- ## 16. Backend Implementation Rules When adding a new endpoint: 1. Add model only if approved by `08_DATA_MODEL_AND_MIGRATION_PLAN.md`. 2. Add serializer only if payload is approved by `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md`. 3. Add ViewSet in the owning app. 4. Register the route in `backend/config/api_router.py`. 5. Add tests. 6. Update this document if the endpoint becomes canonical. Required backend pattern: ```python router.register("ethikos/", ViewSet, basename="ethikos-") ``` or for Kollective: ```python router.register("kollective/", ViewSet, basename="kollective-") ``` Do not register Kintsugi endpoints under: ```txt /api/home/* /api/deliberation/* /api/kialo/* /api/kintsugi/* ``` unless a future ADR explicitly changes the route policy. --- ## 17. Frontend Implementation Rules When adding or changing a frontend API call: 1. Add or update a function in `frontend/services/*`. 2. Use the existing shared request helper. 3. Keep path fragments relative to `/api/` if that is the current service convention. 4. Normalize IDs and payloads in the service layer. 5. Keep page components focused on UI state and rendering. 6. Update related tests or smoke coverage. Do not: ```txt - add raw fetches inside page components; - duplicate HTTP client code; - introduce a second API helper; - bypass CSRF/session handling; - call /api/home/* for new Kintsugi work; - create /api/kialo/* for Kialo-style features; - create /api/kintsugi/* as a parallel API universe. ``` --- ## 18. Testing Contract Minimum tests for current canonical endpoints: ```yaml ETHIKOS_TOPICS: - "GET list" - "POST create authenticated" - "GET detail" ETHIKOS_STANCES: - "POST value within -3..+3" - "Reject value outside -3..+3" - "Filter by topic" ETHIKOS_ARGUMENTS: - "POST top-level argument" - "POST child argument with parent" - "Filter by topic" ETHIKOS_CATEGORIES: - "GET list if ViewSet exists" KOLLECTIVE_VOTES: - "POST vote if VoteViewSet exists" ``` The existing smoke test already verifies API docs access, `/api/users/me/`, Ethikos topic list, stance POST, argument POST, and Kollective vote behavior where present. Future tests for Kintsugi endpoints must be added only when the endpoints are implemented. --- ## 19. Anti-Drift Rules The following are absolute rules for this document. ```yaml ANTI_DRIFT_RULES: - "Do not rename /api/ethikos/... to /api/deliberation/..." - "Do not create /api/kialo/*." - "Do not create /api/kintsugi/* as a parallel core API." - "Do not expand /api/home/*." - "Do not treat compatibility aliases as canonical." - "Do not let frontend pages bypass the service layer." - "Do not use GraphQL for core CRUD." - "Do not use WebSockets for core CRUD." - "Do not treat EthikosStance as Smart Vote ballot." - "Do not treat ArgumentImpactVote as EthikosStance." - "Do not treat ReadingResult as source fact." - "Do not let Smart Vote mutate Korum or Konsultations core records." - "Do not let EkoH become the voting engine." - "Do not make KeenKonnect Project the source of truth for civic impact." ``` --- ## 20. Non-Goals This document does not authorize: * a full external OSS merge; * a new Kialo backend app; * a new Kintsugi backend app; * a replacement of existing ethiKos routes; * a replacement of existing ethiKos models; * a GraphQL rewrite; * a realtime rewrite; * direct database writes from external tools; * moving civic impact truth into KeenKonnect; * using `/api/home/*` as the future decision API. --- ## 21. Related Documents ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 22. Final Contract Summary The Kintsugi upgrade MUST preserve the current API center of gravity: ```txt /api/ethikos/* /api/kollective/* ``` The frontend MUST preserve the current service center of gravity: ```txt frontend/services/* ``` The first-pass Kintsugi upgrade MUST formalize and extend existing contracts, not create a parallel system. Canonical current endpoints: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ /api/kollective/votes/ /api/kollective/vote-results/ ``` Forbidden drift endpoints: ```txt /api/home/* /api/kialo/* /api/kintsugi/* /api/deliberation/* ``` Final rule: ```txt If a new API or service path does not map clearly to Korum, Konsultations, Smart Vote, EkoH, or an approved Kintsugi boundary object, it must not be introduced. ``` --- ## V4.1 EkoH profile access extension `GET /api/v1/ekoh/profile/{uid}/` remains the canonical EkoH profile endpoint. The response now carries `rating_visibility`, `rating_publication_basis`, and a backend-resolved `rating_access` decision. `expertise`, `ethics_score`, and `score_history` MUST be null when the caller lacks the required EkoH rating access. The service authority is `resolve_rating_access(viewer, subject)`. See `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b83853c2b000e3f8b8b1b5b5add01a3bc6f9ce45cede69b3bdeabf2f345e400a CONTENT_BYTES: 47559 ================================================================================================ # 08 — Data Model and Migration Plan **File:** `08_DATA_MODEL_AND_MIGRATION_PLAN.md` **Doc pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Draft for parallel documentation generation **Mode:** Documentation-first architecture planning **Primary owner:** ethiKos / Kintsugi planning **Related docs:** * `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` * `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` * `04_CANONICAL_NAMING_AND_VARIABLES.md` * `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` * `07_API_AND_SERVICE_CONTRACTS.md` * `09_SMART_VOTE_EKOH_READING_CONTRACT.md` * `12_CANONICAL_OBJECTS_AND_EVENTS.md` * `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` * `15_BACKEND_ALIGNMENT_CONTRACT.md` * `20_AI_GENERATION_GUARDRAILS.md` * `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` --- ## 1. Purpose This document defines the **data model and migration plan** for the ethiKos Kintsugi upgrade. The purpose is to provide a stable, non-drifting database design strategy that allows ethiKos to evolve from its current structured deliberation core into the Kintsugi civic pipeline without breaking existing routes, models, services, serializers, or migrations. The Kintsugi upgrade MUST preserve the current ethiKos backend core: * `EthikosCategory` * `EthikosTopic` * `EthikosStance` * `EthikosArgument` The current ethiKos backend is canonically centered on topics, stances, arguments, and categories, with frontend routes already implemented under `/ethikos/*` and backend API routes under `/api/ethikos/*`. This document does **not** define final implementation code. It defines the intended model boundaries, migration sequence, ownership rules, field semantics, and anti-drift constraints that future code generation MUST follow. --- ## 2. Scope This document covers: 1. Current ethiKos data baseline. 2. Models that MUST be preserved. 3. Models that MAY be added for the Kintsugi first pass. 4. Models that SHOULD be deferred. 5. Migration sequencing. 6. Ownership boundaries between Korum, Konsultations, Smart Vote, EkoH, and annex/mimic integrations. 7. Required constraints, indexes, and immutability rules. 8. Explicit anti-drift rules for future AI-assisted implementation. This document does **not** cover: * Final serializer definitions. * Final endpoint implementation. * Frontend component implementation. * Full OSS repository integration. * Full backlog sequencing. * Direct import of external civic-tech codebases. * Replacement of the existing ethiKos backend app. --- ## 3. Canonical Variables Used The following variables are binding for this document. ```yaml DOCUMENT_NAME: "08_DATA_MODEL_AND_MIGRATION_PLAN.md" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false PRIMARY_BACKEND_APP: "konnaxion.ethikos" PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_API_PREFIX: "/api/ethikos/*" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" BREAK_EXISTING_MODELS: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_FIELDS: false ADD_NON_BREAKING_TABLES_ALLOWED: true ADD_NON_BREAKING_FIELDS_ALLOWED: true KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" KIALO_CLAIM_MAPPING: "Claim -> EthikosArgument" KIALO_IMPACT_VOTE_IS_TOPIC_STANCE: false SMART_VOTE_MUTATES_SOURCE_FACTS: false FOREIGN_TOOLS_WRITE_CORE_TABLES: false ``` --- ## 4. Source-of-Truth Priority When data model questions conflict, use this priority order: 1. **Current code snapshot** Determines current files, apps, routes, models, migrations, serializers, and registered endpoints. 2. **Boundaries and ownership contracts** Determines which module owns which data and which module is allowed to write. 3. **Kintsugi clean-slate plan** Determines first-pass scope, deferred scope, and documentation-first ordering. 4. **Kialo-style argument mapping contract** Determines structured deliberation concepts for Korum / Deliberate. 5. **OSS source docs** Provide pattern inspiration only. They do not override ethiKos architecture. 6. **Older conceptual docs** Useful only after being corrected against the current route and model reality. --- ## 5. Current Data Baseline ### 5.1 Current backend app The current canonical backend app for ethiKos is: ```txt konnaxion.ethikos ``` The backend uses Django REST Framework ViewSets, serializers, and a central API router. The project documentation and code snapshot identify `/api/ethikos/topics/`, `/api/ethikos/stances/`, `/api/ethikos/arguments/`, and `/api/ethikos/categories/` as the canonical ethiKos API routes, with compatibility aliases under `/api/deliberate/...` and `/api/deliberate/elite/...`. ### 5.2 Current canonical models The current canonical models are: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` The current technical reference defines these as the canonical current ethiKos tables, with `EthikosTopic` as the debate/consultation prompt, `EthikosStance` as a topic-level numeric stance, and `EthikosArgument` as a threaded discussion entry with optional parent and side semantics. ### 5.3 Current model semantics #### `EthikosCategory` Purpose: ```txt Thematic grouping for ethiKos topics. ``` Current role: * Groups topics. * Supports category selection at topic creation. * Used by frontend filtering and topic organization. Preservation rule: ```yaml RENAME_MODEL: false DELETE_MODEL: false BREAK_EXISTING_SERIALIZER_FIELDS: false ``` --- #### `EthikosTopic` Purpose: ```txt Main debate, deliberation, or consultation prompt container. ``` Current role: * Holds topic title and description. * Tracks status such as `open`, `closed`, `archived`. * Links to category. * Links to creator. * May include `expertise_category`. * Acts as the current root object for both deliberation and decision surfaces. Preservation rule: ```yaml RENAME_MODEL: false DELETE_MODEL: false USE_AS_KIALO_DISCUSSION_CONTAINER: true USE_AS_KONSULTATION_TOPIC_CONTAINER: true ``` Kintsugi mapping: ```yaml EthikosTopic: Korum: "Discussion / thesis container" Konsultations: "Consultation prompt / issue container" Kialo-style: "Discussion" DemocracyOS-style: "Proposal debate container" Loomio-style: "Proposal discussion anchor" ``` --- #### `EthikosStance` Purpose: ```txt Per-user topic-level stance. ``` Current role: * Stores one user’s position on one topic. * Uses numeric stance value constrained to `-3..+3`. * Must remain distinct from Kialo-style argument impact voting and Smart Vote readings. Preservation rule: ```yaml RENAME_MODEL: false DELETE_MODEL: false STANCE_VALUE_RANGE: "-3..+3" CLAIM_IMPACT_VOTE_IS_STANCE: false SMART_VOTE_READING_IS_STANCE: false ``` Kintsugi mapping: ```yaml EthikosStance: Owner: "Korum" Level: "topic-level" Meaning: "User stance on a topic" Not: "claim-level impact vote" Not: "Smart Vote reading" ``` --- #### `EthikosArgument` Purpose: ```txt Threaded argument / claim under an ethiKos topic. ``` Current role: * Stores argument text. * Links to topic. * Links to user. * Supports optional `parent`. * Supports optional `side`, such as pro/con. * Supports moderation visibility through `is_hidden`. The backend model includes `parent`, `side`, and `is_hidden`, which makes it suitable as the native foundation for Kialo-style claim graphs without renaming or replacing it. Preservation rule: ```yaml RENAME_MODEL: false DELETE_MODEL: false DO_NOT_RENAME_TO_CLAIM: true USE_AS_KIALO_CLAIM: true ``` Kintsugi mapping: ```yaml EthikosArgument: Korum: "Argument node" Kialo-style: "Claim" Consider.it-style: "Reason" DemocracyOS-style: "Discussion argument" ``` --- ## 6. Non-Breaking Migration Policy The Kintsugi data model MUST follow a non-breaking migration strategy. ### 6.1 Allowed The following are allowed: ```yaml ADD_NEW_TABLES: true ADD_NULLABLE_FIELDS: true ADD_FIELDS_WITH_SAFE_DEFAULTS: true ADD_INDEXES: true ADD_CONSTRAINTS_ONLY_AFTER_DATA_VALIDATION: true ADD_READ_ONLY_DERIVED_TABLES: true ADD_SERVICE_LAYER_AROUND_EXISTING_MODELS: true ``` ### 6.2 Forbidden The following are forbidden in the Kintsugi first pass: ```yaml RENAME_EXISTING_TABLES: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_TABLES: false DELETE_EXISTING_FIELDS: false CHANGE_PRIMARY_KEY_TYPES: false CHANGE_EXISTING_ENDPOINT_PREFIXES: false CHANGE_ETHIKOS_STANCE_RANGE: false MERGE_SMART_VOTE_INTO_ETHIKOS_STANCE: false MERGE_KIALO_IMPACT_VOTES_INTO_ETHIKOS_STANCE: false CREATE_KIALO_APP: false CREATE_FULL_OSS_IMPORT_TABLES: false ``` ### 6.3 Migration safety rule Every Kintsugi migration MUST be safe under the following assumption: ```txt Existing ethiKos topics, stances, arguments, categories, users, and votes already exist and must remain readable after migration. ``` --- ## 7. Ownership Boundaries ### 7.1 Korum-owned data Korum owns the structured debate layer. Korum-owned objects: ```txt EthikosTopic EthikosStance EthikosArgument ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ModerationAction ``` Korum MAY write: * topic deliberation metadata; * argument graph metadata; * topic-level stances; * claim-level impact votes; * claim sources; * suggested claims; * visibility settings. Korum MUST NOT write: * Smart Vote derived readings; * EkoH expertise scores; * Konsultations ballot results; * external tool source tables. --- ### 7.2 Konsultations-owned data Konsultations owns intake, ballots, result snapshots, and impact tracking. Konsultations-owned objects: ```txt IntakeSubmission DecisionRecord BallotEvent ImpactTrack ImpactUpdate ``` Konsultations MAY write: * intake submissions; * consultation options; * ballot events; * baseline result snapshots; * impact tracking updates. Konsultations MUST NOT write: * Kialo-style claim impact votes; * Smart Vote weighted readings; * EkoH expertise snapshots. --- ### 7.3 Smart Vote-owned data Smart Vote owns derived readings and published interpretations. Smart Vote-owned objects: ```txt LensDeclaration ReadingResult BaselineResult ``` Smart Vote MAY write: * declared lens definitions; * computed reading results; * publication metadata; * reproducibility metadata. Smart Vote MUST NOT mutate: * `EthikosTopic` * `EthikosStance` * `EthikosArgument` * Konsultations ballot source events * EkoH expertise source records The Smart Vote / EkoH integration settings already indicate a separate Smart Vote / EkoH integration layer, with Smart Vote aggregation scheduled separately from ethiKos CRUD behavior. --- ### 7.4 EkoH-owned data EkoH owns expertise, ethics, cohort, and snapshot context. EkoH MAY provide: * expertise categories; * cohort eligibility; * score snapshots; * contextual analysis; * ethics/expertise metadata. EkoH MUST NOT: * become the voting engine; * mutate baseline votes; * mutate topic stances; * mutate Kialo-style impact votes; * publish readings without Smart Vote boundary. --- ### 7.5 External tool boundary data External tools may only be represented through boundary objects. External tool boundary objects: ```txt ExternalArtifact ProjectionMapping ``` Foreign tools MUST NOT write directly to: ```txt EthikosTopic EthikosStance EthikosArgument DecisionRecord ReadingResult ImpactTrack ``` --- ## 8. Proposed First-Pass Model Set The following models are first-pass candidates. They are not all mandatory for the first migration, but they define the allowed model vocabulary. ### 8.1 Decision models #### `DecisionProtocol` Purpose: ```txt Defines how a decision is opened, evaluated, closed, and published. ``` Owner: ```txt Konsultations / Decide ``` Suggested fields: ```yaml id: BigAutoField key: SlugField(unique=True) label: CharField description: TextField(blank=True) protocol_type: CharField is_active: BooleanField(default=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `protocol_type` values: ```txt simple_majority stance_distribution consent_check ranked_option expertise_weighted_reading manual_publication ``` Migration notes: * Add as a standalone table. * No existing data backfill required. * Safe first migration candidate. --- #### `DecisionRecord` Purpose: ```txt Represents a formal decision process derived from a topic, consultation, or proposal. ``` Owner: ```txt Konsultations / Decide ``` Suggested fields: ```yaml id: BigAutoField topic: ForeignKey(EthikosTopic, null=True, blank=True) protocol: ForeignKey(DecisionProtocol, null=True, blank=True) title: CharField description: TextField(blank=True) status: CharField opened_at: DateTimeField(null=True, blank=True) closed_at: DateTimeField(null=True, blank=True) published_at: DateTimeField(null=True, blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `status` values: ```txt draft open closed published archived ``` Constraints: ```yaml closed_at_required_when_status_closed: true published_at_required_when_status_published: true ``` Indexes: ```yaml - ["topic"] - ["status"] - ["created_by"] - ["opened_at"] - ["closed_at"] ``` Migration notes: * Add after `DecisionProtocol`. * Existing closed topics MAY later be backfilled into `DecisionRecord`, but first migration SHOULD NOT require this. * Backfill must be optional and reversible. --- #### `EligibilityRule` Purpose: ```txt Defines who can participate in a decision, ballot, or reading cohort. ``` Owner: ```txt Konsultations / Admin ``` Suggested fields: ```yaml id: BigAutoField decision: ForeignKey(DecisionRecord, null=True, blank=True) key: SlugField label: CharField rule_type: CharField rule_payload: JSONField(default=dict, blank=True) is_active: BooleanField(default=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `rule_type` values: ```txt public authenticated ethikos_elite staff ekoh_cohort manual_allowlist ``` Migration notes: * First pass optional. * Useful for CONSUL-style eligibility and route-level elite/public distinction. * Should not replace existing permissions immediately. --- ## 9. Smart Vote / Reading Models ### 9.1 `LensDeclaration` Purpose: ```txt Declares how a Smart Vote reading is computed. ``` Owner: ```txt Smart Vote ``` Suggested fields: ```yaml id: BigAutoField reading_key: SlugField(unique=True) label: CharField description: TextField(blank=True) lens_type: CharField lens_payload: JSONField(default=dict, blank=True) lens_hash: CharField(max_length=128) is_active: BooleanField(default=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `lens_type` values: ```txt raw_unweighted cohort_filtered expertise_weighted ethics_adjusted domain_specific comparative ``` Constraints: ```yaml reading_key_unique: true lens_hash_required: true ``` Migration notes: * Add before `ReadingResult`. * `raw_unweighted` SHOULD be seeded as the baseline lens. * Hash calculation can be service-level; migration does not need to compute all hashes initially. --- ### 9.2 `ReadingResult` Purpose: ```txt Stores a computed Smart Vote reading for a topic, decision, or consultation snapshot. ``` Owner: ```txt Smart Vote ``` Suggested fields: ```yaml id: BigAutoField lens: ForeignKey(LensDeclaration) topic: ForeignKey(EthikosTopic, null=True, blank=True) decision: ForeignKey(DecisionRecord, null=True, blank=True) snapshot_ref: CharField(max_length=255, blank=True) results_payload: JSONField(default=dict) input_hash: CharField(max_length=128, blank=True) lens_hash: CharField(max_length=128) computed_at: DateTimeField published_at: DateTimeField(null=True, blank=True) status: CharField created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `status` values: ```txt pending computed published invalidated ``` Constraints: ```yaml must_reference_topic_or_decision: true lens_hash_required: true results_payload_required: true ``` Indexes: ```yaml - ["lens"] - ["topic"] - ["decision"] - ["status"] - ["computed_at"] - ["snapshot_ref"] ``` Migration notes: * Add after `LensDeclaration`. * Do not compute readings in schema migration. * Computation belongs in service/task layer. * Existing stance data remains source data and must not be overwritten. --- ## 10. Drafting Models ### 10.1 `Draft` Purpose: ```txt Represents a collaborative draft derived from a topic, decision, or consultation process. ``` Owner: ```txt ethiKos bounded drafting capability ``` Suggested fields: ```yaml id: BigAutoField topic: ForeignKey(EthikosTopic, null=True, blank=True) decision: ForeignKey(DecisionRecord, null=True, blank=True) title: CharField summary: TextField(blank=True) status: CharField created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `status` values: ```txt draft review accepted superseded archived ``` Migration notes: * Add as standalone drafting table. * Does not replace `EthikosTopic.description`. * Does not store argument graph content directly. --- ### 10.2 `DraftVersion` Purpose: ```txt Stores immutable versions of a Draft. ``` Owner: ```txt ethiKos bounded drafting capability ``` Suggested fields: ```yaml id: BigAutoField draft: ForeignKey(Draft) version_number: PositiveIntegerField body: TextField summary: TextField(blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) ``` Constraints: ```yaml unique_draft_version_number: ["draft", "version_number"] version_body_immutable_after_creation: true ``` Indexes: ```yaml - ["draft", "version_number"] - ["created_at"] ``` Migration notes: * Add after `Draft`. * Do not update existing versions in place except through admin-only correction workflows. * Normal changes create new versions. --- ### 10.3 `Amendment` Purpose: ```txt Represents a proposed change to a draft or draft version. ``` Owner: ```txt ethiKos bounded drafting capability ``` Suggested fields: ```yaml id: BigAutoField draft: ForeignKey(Draft) base_version: ForeignKey(DraftVersion, null=True, blank=True) title: CharField body: TextField rationale: TextField(blank=True) status: CharField submitted_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) resolved_at: DateTimeField(null=True, blank=True) ``` Suggested `status` values: ```txt submitted under_review accepted rejected withdrawn superseded ``` Migration notes: * Add after `DraftVersion`. * Must not mutate `DraftVersion` directly. * Accepted amendments may produce a new `DraftVersion`. --- ### 10.4 `RationalePacket` Purpose: ```txt Captures the argumentation, evidence, and decision rationale attached to a draft, decision, or amendment. ``` Owner: ```txt ethiKos bounded drafting capability / Decide ``` Suggested fields: ```yaml id: BigAutoField topic: ForeignKey(EthikosTopic, null=True, blank=True) decision: ForeignKey(DecisionRecord, null=True, blank=True) draft: ForeignKey(Draft, null=True, blank=True) amendment: ForeignKey(Amendment, null=True, blank=True) summary: TextField supporting_arguments: ManyToManyField(EthikosArgument, blank=True) payload: JSONField(default=dict, blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) ``` Migration notes: * First pass optional. * Useful for turning deliberation outputs into decision-ready explanations. * Must reference arguments rather than copy argument text unless snapshotting is explicitly required. --- ## 11. Impact Models ### 11.1 `ImpactTrack` Purpose: ```txt Tracks implementation, follow-through, and accountability after a decision. ``` Owner: ```txt Konsultations / Impact ``` Suggested fields: ```yaml id: BigAutoField decision: ForeignKey(DecisionRecord, null=True, blank=True) topic: ForeignKey(EthikosTopic, null=True, blank=True) title: CharField description: TextField(blank=True) status: CharField owner_label: CharField(blank=True) public_summary: TextField(blank=True) started_at: DateTimeField(null=True, blank=True) due_at: DateTimeField(null=True, blank=True) completed_at: DateTimeField(null=True, blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `status` values: ```txt planned in_progress blocked completed cancelled ``` Indexes: ```yaml - ["decision"] - ["topic"] - ["status"] - ["due_at"] ``` Migration notes: * Impact data belongs to ethiKos/Konsultations truth. * KeenKonnect project references may be linked later, but KeenKonnect must not become the canonical source of civic impact truth. --- ### 11.2 `ImpactUpdate` Purpose: ```txt Stores timestamped updates on an ImpactTrack. ``` Owner: ```txt Konsultations / Impact ``` Suggested fields: ```yaml id: BigAutoField impact_track: ForeignKey(ImpactTrack) title: CharField body: TextField status_after_update: CharField(blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) ``` Migration notes: * Add after `ImpactTrack`. * Supports accountability timeline without mutating old updates. --- ## 12. Kialo-Style Argument Mapping Models The Kialo-style models extend Korum / Deliberate. They MUST live under the ethiKos backend scope during the first pass. Kialo-style source material distinguishes claim voting, source attachment, author visibility, voting visibility, and discussion topology. Claim impact voting is explicitly based on a claim’s veracity and relevance to its parent, with ratings from `0` to `4`; this must remain separate from topic-level ethiKos stances. ### 12.1 `ArgumentSource` Purpose: ```txt Attaches a source, citation, quote, or evidence note to an EthikosArgument. ``` Owner: ```txt Korum / Deliberate ``` Suggested fields: ```yaml id: BigAutoField argument: ForeignKey(EthikosArgument) source_type: CharField label: CharField(blank=True) url: URLField(blank=True) citation: TextField(blank=True) quote: TextField(blank=True) note: TextField(blank=True) created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `source_type` values: ```txt url citation textbook paper news other ``` Indexes: ```yaml - ["argument"] - ["created_by"] ``` Migration notes: * First-pass recommended. * Does not change `EthikosArgument.content`. * Supports Kialo-style source/citation behavior. --- ### 12.2 `ArgumentImpactVote` Purpose: ```txt Stores claim-level impact votes on an EthikosArgument. ``` Owner: ```txt Korum / Deliberate ``` Suggested fields: ```yaml id: BigAutoField argument: ForeignKey(EthikosArgument) user: ForeignKey(settings.AUTH_USER_MODEL) value: PositiveSmallIntegerField created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Constraints: ```yaml unique_user_argument_vote: ["argument", "user"] value_min: 0 value_max: 4 ``` Indexes: ```yaml - ["argument"] - ["user"] - ["value"] ``` Critical distinction: ```yaml ArgumentImpactVote_IS_EthikosStance: false ArgumentImpactVote_IS_BallotEvent: false ArgumentImpactVote_IS_SmartVoteReading: false ``` Migration notes: * First-pass recommended. * Do not merge into `EthikosStance`. * Do not use for Smart Vote ballot aggregation unless a future reading explicitly declares it as an input. --- ### 12.3 `ArgumentSuggestion` Purpose: ```txt Stores proposed claims submitted by users who do not have direct write permission or when moderation requires approval. ``` Owner: ```txt Korum / Deliberate ``` Suggested fields: ```yaml id: BigAutoField topic: ForeignKey(EthikosTopic) parent_argument: ForeignKey(EthikosArgument, null=True, blank=True) suggested_side: CharField(blank=True) content: TextField status: CharField submitted_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) reviewed_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True) created_argument: ForeignKey(EthikosArgument, null=True, blank=True) created_at: DateTimeField(auto_now_add=True) reviewed_at: DateTimeField(null=True, blank=True) ``` Suggested `status` values: ```txt submitted accepted rejected withdrawn superseded ``` Constraints: ```yaml accepted_suggestion_should_reference_created_argument: true ``` Migration notes: * First-pass recommended if role-aware participation is introduced. * Accepting a suggestion creates an `EthikosArgument`; the suggestion itself remains an audit record. --- ### 12.4 `DiscussionParticipantRole` Purpose: ```txt Assigns a user a role within a topic/discussion. ``` Owner: ```txt Korum / Admin ``` Suggested fields: ```yaml id: BigAutoField topic: ForeignKey(EthikosTopic) user: ForeignKey(settings.AUTH_USER_MODEL) role: CharField created_by: ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, related_name="+") created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `role` values: ```txt owner admin editor writer suggester viewer ``` Constraints: ```yaml unique_topic_user_role: ["topic", "user"] ``` Migration notes: * Optional first-pass. * Should not replace Django permissions globally. * Applies only to ethiKos topic/discussion participation. --- ### 12.5 `DiscussionVisibilitySetting` Purpose: ```txt Stores discussion-level visibility, anonymity, author display, voting visibility, and topology settings. ``` Owner: ```txt Korum / Admin ``` Suggested fields: ```yaml id: BigAutoField topic: OneToOneField(EthikosTopic) participation_type: CharField author_visibility: CharField vote_visibility: CharField discussion_topology: CharField allow_claim_voting: BooleanField(default=False) allow_suggestions: BooleanField(default=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested values: ```yaml participation_type: - standard - anonymous author_visibility: - never - admins_only - all vote_visibility: - all - admins_only - self_only discussion_topology: - single_thesis - multi_thesis ``` Kialo-style author display and vote visibility settings are discussion-level controls; author attribution can be hidden, admin-only, or visible to all, and vote visibility can be configured so all users, only admins, or only the voter can see impact votes. Migration notes: * Recommended first-pass if Kialo-style permissions are implemented. * Existing topics can receive default settings via data migration or lazy creation. * Recommended defaults: ```yaml participation_type: "standard" author_visibility: "all" vote_visibility: "all" discussion_topology: "single_thesis" allow_claim_voting: false allow_suggestions: true ``` --- ## 13. External Tool Boundary Models ### 13.1 `ExternalArtifact` Purpose: ```txt Stores metadata about an external artifact without importing or merging the external tool into core ethiKos. ``` Owner: ```txt Integration boundary ``` Suggested fields: ```yaml id: BigAutoField source_system: CharField artifact_type: CharField external_id: CharField(blank=True) title: CharField(blank=True) metadata: JSONField(default=dict, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `source_system` values: ```txt consider_it kialo_style loomio citizen_os decidim consul_democracy democracy_os other ``` Migration notes: * First pass optional. * Required only if an annex/adapter boundary is introduced. * Does not authorize external tools to write core tables. --- ### 13.2 `ProjectionMapping` Purpose: ```txt Maps external artifacts to native ethiKos objects without making the external artifact the source of truth. ``` Owner: ```txt Integration boundary ``` Suggested fields: ```yaml id: BigAutoField external_artifact: ForeignKey(ExternalArtifact) target_model: CharField target_id: CharField mapping_type: CharField mapping_payload: JSONField(default=dict, blank=True) created_at: DateTimeField(auto_now_add=True) updated_at: DateTimeField(auto_now=True) ``` Suggested `mapping_type` values: ```txt inspiration projection import_snapshot export_snapshot reference_link ``` Migration notes: * First pass optional. * Required for future annex safety. * Do not use this as a shortcut for full OSS merge. --- ## 14. Deferred Kialo-Style Models The following models are useful but SHOULD be deferred unless the first-pass scope explicitly expands. ### 14.1 `ArgumentBookmark` Purpose: ```txt Allows users to bookmark claims or branches. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Useful UX feature, but not necessary for Kintsugi data legitimacy or migration foundation. ``` --- ### 14.2 `ArgumentLink` Purpose: ```txt Links claims across branches or discussions. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Cross-discussion links add graph complexity and should follow after the core argument tree is stable. ``` --- ### 14.3 `DiscussionTemplate` Purpose: ```txt Stores reusable discussion structures. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Template cloning is useful but not essential to first-pass Korum/Kintsugi alignment. ``` --- ### 14.4 `DiscussionGroup` Purpose: ```txt Supports small group discussion modes. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Small-group mode introduces group partitioning, moderation complexity, and visibility concerns. ``` --- ### 14.5 `DiscussionPerspective` Purpose: ```txt Stores perspective-specific views of claim impact or argument interpretation. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Perspectives overlap with Smart Vote lenses and must be designed jointly with reading contracts. ``` --- ### 14.6 `DiscussionExport` Purpose: ```txt Tracks generated exports of discussions or argument trees. ``` Status: ```yaml FIRST_PASS: false DEFERRED: true ``` Reason: ```txt Export is a downstream capability; it should follow after canonical object and snapshot policies are stable. ``` --- ## 15. Migration Sequence The migration sequence MUST minimize risk and keep each migration reversible where practical. ### 15.1 Phase 0 — Baseline verification Before any Kintsugi migration: ```txt Verify current migrations apply cleanly. Verify EthikosCategory exists. Verify EthikosTopic creation works. Verify EthikosStance creation works. Verify EthikosArgument creation works. Verify EkoH migration 0002 has already been applied. ``` No schema changes in this phase. --- ### 15.2 Phase 1 — Safe Korum extensions Recommended first migration group: ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` Reason: * Extends existing Deliberate/Korum data. * Uses `EthikosTopic` and `EthikosArgument` as anchors. * Does not affect current topic, stance, or argument writes. * Enables Kialo-style claim graph refinement. Required migration properties: ```yaml depends_on: - "ethikos existing latest migration" data_backfill_required: false safe_for_empty_tables: true safe_for_existing_topics: true ``` Optional data migration: ```txt Create default DiscussionVisibilitySetting for existing topics. ``` This data migration should be safe, idempotent, and rerunnable. --- ### 15.3 Phase 2 — Decision and drafting foundation Recommended second migration group: ```txt DecisionProtocol DecisionRecord Draft DraftVersion Amendment RationalePacket ``` Reason: * Adds Decide/Drafting foundation. * Does not alter `EthikosTopic`. * Allows topics to become decision anchors without changing topic semantics. Required migration properties: ```yaml decision_protocol_seed_allowed: true existing_topic_backfill_required: false draft_version_body_immutable_policy_documented: true ``` Optional seed data: ```txt DecisionProtocol: raw_stance_distribution DecisionProtocol: consent_check DecisionProtocol: manual_publication ``` --- ### 15.4 Phase 3 — Smart Vote reading foundation Recommended third migration group: ```txt LensDeclaration ReadingResult ``` Reason: * Adds the reading layer after source data and decision anchors exist. * Keeps Smart Vote derived outputs separate from stances and ballots. Required migration properties: ```yaml seed_baseline_lens: true compute_readings_in_migration: false require_lens_hash: true require_snapshot_ref_field: true ``` Recommended seed data: ```yaml LensDeclaration: reading_key: "raw_unweighted" label: "Raw unweighted baseline" lens_type: "raw_unweighted" ``` --- ### 15.5 Phase 4 — Impact foundation Recommended fourth migration group: ```txt ImpactTrack ImpactUpdate ``` Reason: * Adds accountability layer after decisions exist. * Prevents premature coupling to KeenKonnect project data. Required migration properties: ```yaml impact_can_reference_decision: true impact_can_reference_topic: true keenkonnect_is_not_canonical_impact_truth: true ``` --- ### 15.6 Phase 5 — External boundary foundation Recommended fifth migration group: ```txt ExternalArtifact ProjectionMapping ``` Reason: * Enables future annex/adapter safety. * Not required for first-pass native mimic if no external artifacts are persisted. Required migration properties: ```yaml foreign_tools_write_core_tables: false external_artifacts_are_not_source_truth: true projection_mapping_is_boundary_only: true ``` --- ## 16. Model Dependency Map ```txt EthikosCategory └── EthikosTopic ├── EthikosStance ├── EthikosArgument │ ├── EthikosArgument.parent │ ├── ArgumentSource │ ├── ArgumentImpactVote │ └── ArgumentSuggestion.parent_argument ├── DiscussionVisibilitySetting ├── DiscussionParticipantRole ├── DecisionRecord │ ├── ReadingResult │ ├── Draft │ └── ImpactTrack ├── Draft │ ├── DraftVersion │ └── Amendment └── ReadingResult DecisionProtocol └── DecisionRecord LensDeclaration └── ReadingResult ImpactTrack └── ImpactUpdate ExternalArtifact └── ProjectionMapping ``` --- ## 17. Index Strategy ### 17.1 Required indexes The following indexes SHOULD be included where models are implemented. ```yaml EthikosTopic: existing: - ["status"] - ["category"] - ["created_by"] EthikosStance: required: - ["topic"] - ["user"] - ["value"] EthikosArgument: existing_or_required: - ["topic"] - ["user"] - ["parent"] - ["side"] - ["is_hidden"] ArgumentSource: required: - ["argument"] - ["created_by"] ArgumentImpactVote: required: - ["argument"] - ["user"] - ["value"] ArgumentSuggestion: required: - ["topic"] - ["parent_argument"] - ["status"] - ["submitted_by"] DecisionRecord: required: - ["topic"] - ["protocol"] - ["status"] - ["opened_at"] - ["closed_at"] ReadingResult: required: - ["lens"] - ["topic"] - ["decision"] - ["status"] - ["computed_at"] - ["snapshot_ref"] ImpactTrack: required: - ["decision"] - ["topic"] - ["status"] - ["due_at"] ``` ### 17.2 Unique constraints Recommended unique constraints: ```yaml EthikosStance: - ["topic", "user"] ArgumentImpactVote: - ["argument", "user"] DiscussionVisibilitySetting: - ["topic"] DiscussionParticipantRole: - ["topic", "user"] DraftVersion: - ["draft", "version_number"] LensDeclaration: - ["reading_key"] ReadingResult: recommended_contextual_uniqueness: - ["lens", "topic", "decision", "snapshot_ref", "input_hash"] ``` --- ## 18. Data Integrity Rules ### 18.1 Topic-level stance integrity ```yaml EthikosStance.value: min: -3 max: 3 ``` Rules: * A stance is a user’s position on a topic. * A stance is not a claim impact vote. * A stance is not a ballot event unless an explicit decision protocol says it is used as one of its inputs. * A stance is not a Smart Vote reading. --- ### 18.2 Claim-level impact vote integrity ```yaml ArgumentImpactVote.value: min: 0 max: 4 ``` Rules: * Impact votes evaluate an argument/claim. * Impact votes evaluate relevance and veracity relative to the parent claim. * Impact votes do not replace topic stances. * Impact votes must support visibility rules. * Impact votes may be hidden from peers depending on `DiscussionVisibilitySetting.vote_visibility`. --- ### 18.3 Reading integrity ```yaml ReadingResult: must_have_lens: true must_have_results_payload: true must_have_lens_hash: true must_have_computed_at: true ``` Rules: * Readings are derived outputs. * Readings must be reproducible. * Readings must not mutate baseline records. * Readings must declare their lens. * Readings must be invalidated, not silently overwritten, when source assumptions change. --- ### 18.4 Draft version integrity Rules: * `DraftVersion` is immutable after creation. * New draft changes create new versions. * Amendments may produce draft versions. * Drafts do not replace topics. * Drafts do not replace decisions. --- ### 18.5 External artifact integrity Rules: * External artifacts are boundary references. * Projection mappings are not source truth. * External artifacts must not own core ethiKos records. * Direct writes from external systems into core tables are forbidden. --- ## 19. Backfill Policy Backfills MUST be optional, explicit, and idempotent. ### 19.1 Allowed backfills Allowed: ```txt Create default DiscussionVisibilitySetting rows for existing topics. Seed baseline LensDeclaration. Seed basic DecisionProtocol rows. ``` ### 19.2 Forbidden backfills Forbidden in first-pass migration: ```txt Convert all closed EthikosTopic rows into DecisionRecord automatically. Convert all EthikosStance rows into ballots automatically. Convert all EthikosArgument rows into a new Claim table. Convert all current frontend mock data into database records. Compute Smart Vote readings inside schema migrations. ``` ### 19.3 Idempotency rule Every data migration MUST be safe to rerun in development. Pattern: ```txt get_or_create by stable key do not duplicate rows do not mutate user-generated text do not infer sensitive identity data ``` --- ## 20. App Placement Policy ### 20.1 First-pass app placement First-pass Kintsugi data model extensions SHOULD live in: ```txt konnaxion.ethikos ``` Unless a pre-existing canonical app already owns the data. ### 20.2 Smart Vote and EkoH exceptions Smart Vote / EkoH data MAY live in their existing integration apps if they already exist in the codebase. Allowed: ```txt konnaxion.smart_vote konnaxion.ekoh ``` Required boundary: ```txt Smart Vote/EkoH models must not mutate ethiKos source models. ``` ### 20.3 Forbidden new apps The following new apps MUST NOT be created in the first pass: ```txt konnaxion.kialo konnaxion.loomio konnaxion.decidim konnaxion.consul konnaxion.democracyos konnaxion.polis konnaxion.liquid_feedback ``` --- ## 21. Suggested Migration File Grouping The final migration numbering will depend on the current repository state. The following names are conceptual. ```txt 000X_kintsugi_korum_argument_extensions.py 000X_kintsugi_decision_and_drafting_foundation.py 000X_kintsugi_smart_vote_reading_foundation.py 000X_kintsugi_impact_foundation.py 000X_kintsugi_external_artifact_boundaries.py ``` If implemented in separate apps: ```txt ethikos/000X_kintsugi_korum_argument_extensions.py ethikos/000X_kintsugi_decision_and_drafting_foundation.py ethikos/000X_kintsugi_impact_foundation.py ethikos/000X_kintsugi_external_artifact_boundaries.py smart_vote/000X_lens_declaration_and_reading_result.py ``` --- ## 22. Serializer and API Implications This document does not define final serializers, but the model plan implies future serializers for: ```txt ArgumentSourceSerializer ArgumentImpactVoteSerializer ArgumentSuggestionSerializer DiscussionVisibilitySettingSerializer DiscussionParticipantRoleSerializer DecisionProtocolSerializer DecisionRecordSerializer LensDeclarationSerializer ReadingResultSerializer DraftSerializer DraftVersionSerializer AmendmentSerializer RationalePacketSerializer ImpactTrackSerializer ImpactUpdateSerializer ExternalArtifactSerializer ProjectionMappingSerializer ``` Serializer implementation MUST be defined in: ```txt 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md ``` Endpoint implementation MUST be defined in: ```txt 07_API_AND_SERVICE_CONTRACTS.md ``` --- ## 23. Admin Implications The following models SHOULD be registered in Django admin when implemented: ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting DecisionProtocol DecisionRecord LensDeclaration ReadingResult Draft DraftVersion Amendment RationalePacket ImpactTrack ImpactUpdate ExternalArtifact ProjectionMapping ``` Admin list views SHOULD include: ```txt status topic decision created_by created_at updated_at ``` Admin MUST protect: ```txt DraftVersion immutability ReadingResult reproducibility fields anonymous participation identity boundaries source fact records ``` --- ## 24. Testing Requirements Every implemented migration group MUST include tests or smoke checks. ### 24.1 Migration checks Required checks: ```txt python manage.py makemigrations --check python manage.py migrate python manage.py check ``` ### 24.2 Data integrity checks Required checks: ```txt Existing topics remain readable. Existing stances remain readable. Existing arguments remain readable. New ArgumentImpactVote cannot exceed 4. New ArgumentImpactVote cannot be below 0. EthikosStance still enforces -3..+3. ReadingResult requires a lens. DraftVersion uniqueness holds per draft. ``` ### 24.3 API smoke implications The current smoke baseline already verifies topic, stance, argument, and Kollective vote flows. The Kintsugi migration plan must preserve those current flows and add checks only after endpoints are implemented. --- ## 25. Rollback Strategy ### 25.1 Schema rollback Each migration SHOULD be reversible where possible. Safe rollback candidates: ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting DecisionProtocol DecisionRecord Draft DraftVersion Amendment RationalePacket ImpactTrack ImpactUpdate ExternalArtifact ProjectionMapping ``` ### 25.2 Data rollback limits The following should be considered audit-sensitive and should not be casually deleted in production: ```txt ReadingResult DecisionRecord DraftVersion ArgumentImpactVote ImpactUpdate ModerationAction ``` ### 25.3 Rollback principle ```txt Development rollback may drop new Kintsugi tables. Production rollback should disable new features first, preserve audit records where possible, and only drop schema after explicit review. ``` --- ## 26. Anti-Drift Rules Future AI-generated implementation MUST obey the following: ```txt Do not rename EthikosArgument to Claim. Do not create a separate Claim model to replace EthikosArgument in first pass. Do not create a Kialo backend app. Do not create a Kialo route family. Do not treat Kialo impact votes as Ethikos stances. Do not treat Kialo impact votes as Smart Vote ballots. Do not treat Smart Vote readings as source facts. Do not mutate source facts from Smart Vote. Do not mutate source facts from EkoH. Do not let foreign tools write to core ethiKos tables. Do not expand /api/home/*. Do not make KeenKonnect the canonical owner of ethiKos impact tracking. Do not compute readings in schema migrations. Do not backfill decisions from topics unless explicitly approved. Do not add destructive migrations. Do not rename existing API prefixes. ``` --- ## 27. Implementation Readiness Checklist Before implementing any model from this plan: ```txt [ ] Confirm latest current migrations. [ ] Confirm current Ethikos models. [ ] Confirm current serializers. [ ] Confirm current API router registrations. [ ] Confirm existing smoke tests still pass. [ ] Confirm whether smart_vote and ekoh apps are active in settings. [ ] Confirm whether new models live in ethikos or smart_vote. [ ] Confirm payload shapes in doc 13. [ ] Confirm API contracts in doc 07. [ ] Confirm AI guardrails in doc 20. [ ] Confirm Kialo contract in doc 21. ``` --- ## 28. Final First-Pass Recommendation The safest first-pass migration set is: ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting DecisionProtocol DecisionRecord LensDeclaration ReadingResult Draft DraftVersion Amendment ImpactTrack ``` The minimum viable first migration is: ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionVisibilitySetting ``` The migration that MUST NOT happen is: ```txt Rename EthikosArgument to Claim. ``` The single most important data distinction is: ```txt EthikosStance != ArgumentImpactVote != SmartVote ReadingResult ``` --- ## 29. Related Documents This document must be interpreted with: ```txt 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 07_API_AND_SERVICE_CONTRACTS.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 15_BACKEND_ALIGNMENT_CONTRACT.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md ``` If this document conflicts with the current code snapshot, the code snapshot wins for implementation reality. If this document conflicts with `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`, the boundaries document wins for ownership and write rules. If this document conflicts with `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md`, this document wins for migration sequencing, but the Kialo contract wins for Kialo-style semantics. --- ## V4.1 additive EkoH disclosure models V4.1 adds `RatingVisibilitySetting`, `RatingAccessScope`, `RatingScopeSubject`, and `RatingAccessGrant` inside `konnaxion.ekoh`. This is an additive migration only. Existing EkoH score, ethics, history, audit, and confidentiality models remain unchanged. No organisation/department business model is added to EkoH; external concepts map through generic scope keys. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 88d6a04ada7a672966a3839da4568f9d64fb265582cb134f5d4eb2bd229518ab CONTENT_BYTES: 34332 ================================================================================================ # 09 — Smart Vote + EkoH Reading Contract **File:** `09_SMART_VOTE_EKOH_READING_CONTRACT.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Normative contract **Audience:** backend, frontend, analytics, Smart Vote, EkoH, ethiKos, future AI/code-generation sessions **Primary goal:** prevent drift between raw democratic facts, Smart Vote readings, and EkoH-derived context. --- ## 1. Purpose This document defines the contract between **ethiKos**, **Smart Vote**, and **EkoH** for the Kintsugi upgrade. The core rule is: > ethiKos preserves one canonical set of source facts, while Smart Vote may publish multiple declared, reproducible readings of those facts. This contract exists to prevent four classes of drift: 1. treating weighted results as source facts; 2. treating EkoH as the voting engine; 3. mixing topic-level stances, claim-level impact votes, and Smart Vote readings; 4. allowing derived outputs to mutate Korum or Konsultations records. The source boundary document defines the principle as **single truth, multiple readings**: baseline outcomes remain visible, while Smart Vote readings are explicitly declared, reproducible transformations bound to an audit context, often an EkoH snapshot. --- ## 2. Scope This document governs: * baseline results; * Smart Vote readings; * lens declarations; * EkoH snapshots; * weighted / filtered / cohort-specific outputs; * audit fields required for published readings; * how readings are shown in `/ethikos/decide/*`, `/ethikos/insights`, `/ethikos/pulse/*`, and related analytics views; * the separation between `EthikosStance`, `ArgumentImpactVote`, `Vote`, `VoteResult`, and `ReadingResult`. This document does **not** define the full data model for all Kintsugi entities. That belongs in: * `08_DATA_MODEL_AND_MIGRATION_PLAN.md` * `12_CANONICAL_OBJECTS_AND_EVENTS.md` * `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` --- ## 3. Canonical variables used ```yaml DOCUMENT_ID: "09_SMART_VOTE_EKOH_READING_CONTRACT.md" PROJECT: PLATFORM_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" PRIMARY_ROUTE_SURFACE: "/ethikos/*" OWNERSHIP: KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "ballots" - "consultation results" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lenses" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" READING_CONTRACT: BASELINE_READING: "raw_unweighted" WEIGHTED_READING: "declared_lens_output" READING_REPRODUCIBLE: true READING_INPUTS: - "BaselineEvents" - "LensDeclaration" - "SnapshotContext" SNAPSHOT_FIELD: "snapshot_ref" LEGACY_EKOH_SNAPSHOT_FIELD: "ekoh_snapshot_id" LENS_ID_FIELD: "reading_key" LENS_HASH_FIELD: "lens_hash" RESULT_PAYLOAD_FIELD: "results_payload" COMPUTED_AT_FIELD: "computed_at" VOTE_TYPE_SEPARATION: ETHIKOS_STANCE_RANGE: "-3..+3" KIALO_IMPACT_VOTE_RANGE: "0..4" SMART_VOTE_READING_IS_SOURCE_FACT: false EKOH_IS_VOTING_ENGINE: false SMART_VOTE_MUTATES_SOURCE_FACTS: false ``` --- ## 4. Source basis This contract is grounded in the following current project facts: 1. ethiKos v2 defines **single truth, multiple readings** and assigns Smart Vote to computation/publication of outcomes as readings, while keeping it read-only on Korum/Konsultations facts. 2. The current Smart Vote backend already contains `Vote`, `VoteResult`, `VoteModality`, and `VoteLedger` concepts, including `raw_value`, `weighted_value`, target typing, and aggregate vote results. 3. EkoH and Smart Vote are configured as Django apps under `konnaxion.ekoh` and `konnaxion.smart_vote`, with periodic tasks for EkoH score recalculation, contextual analysis, and Smart Vote aggregation. 4. Existing technical references define EkoH weighting parameters, Smart Vote modalities, and ethiKos stance scale values. 5. Current frontend routes already expose EkoH and Smart Vote surfaces such as EkoH score, expertise, badges, voting weight, Konsensus, and activity feed. --- ## 5. Core principle ## 5.1 Single truth The source truth is the set of recorded civic events. Examples: ```yaml SOURCE_FACTS: - "EthikosStance" - "EthikosArgument" - "BallotEvent" - "Vote" - "ModerationAction" ``` Source facts are owned by the module that captured them. ```yaml SOURCE_FACT_OWNERSHIP: EthikosStance: "Korum" EthikosArgument: "Korum" BallotEvent: "Konsultations" Vote: "Smart Vote / Kollective voting substrate" ModerationAction: "Korum or Konsultations depending target" ``` A source fact is not a reading. A source fact must not change just because a new lens is introduced. --- ## 5.2 Multiple readings A reading is a declared interpretation of the source facts. Examples: ```yaml READINGS: baseline: description: "Raw unweighted result." ekoh_weighted_v1: description: "Weighted reading using EkoH expertise and ethics context." expert_cohort_v1: description: "Filtered reading using only users above an expertise threshold." public_krowd_v1: description: "Public participant reading." elite_council_v1: description: "Elite or expert-council scoped reading." ``` A reading must always answer: ```yaml READING_MUST_ANSWER: - "What inputs were used?" - "What filters were applied?" - "What weights were applied?" - "Which snapshot/config was used?" - "When was it computed?" - "Can it be recomputed?" ``` --- ## 6. Ownership contract ## 6.1 Korum Korum owns deliberation facts. ```yaml KORUM_SOURCE_FACTS: - "EthikosTopic" - "EthikosStance" - "EthikosArgument" - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "ModerationAction" ``` Korum may expose stance distributions and argument statistics, but it does not own Smart Vote readings. Korum must not store `weighted_value` as if it were a canonical stance. --- ## 6.2 Konsultations Konsultations owns consultation and ballot facts. ```yaml KONSULTATIONS_SOURCE_FACTS: - "IntakeSubmission" - "Consultation" - "BallotEvent" - "ConsultationResultSnapshot" - "ImpactTrack" ``` Konsultations may store baseline ballot results. Konsultations must not store an EkoH-weighted outcome as its canonical result unless that value is explicitly marked as a Smart Vote reading. --- ## 6.3 Smart Vote Smart Vote owns computation and publication of readings. ```yaml SMART_VOTE_OWNS: - "LensDeclaration" - "ReadingResult" - "Vote aggregation" - "VoteResult" - "Reading publication" ``` Smart Vote may read Korum and Konsultations facts. Smart Vote must not mutate Korum or Konsultations facts. Smart Vote may write only derived artifacts: ```yaml SMART_VOTE_DERIVED_ARTIFACTS: - "ReadingResult" - "VoteResult" - "AggregationBreakdown" - "ReadingAuditRecord" ``` --- ## 6.4 EkoH EkoH owns expertise and ethics context. ```yaml EKOH_OWNS: - "ExpertiseCategory" - "UserExpertiseScore" - "UserEthicsScore" - "ScoreConfiguration" - "ScoreHistory" - "ConfidentialitySetting" - "ContextAnalysisLog" - "EmergingExpert" ``` EkoH is not the voting engine. EkoH provides context to Smart Vote through snapshots, scores, domain vectors, ethics multipliers, and cohort eligibility. --- ## 7. Vote type separation The Kintsugi upgrade must preserve a strict separation between three vote-like concepts. | Concept | Owner | Level | Range / shape | Meaning | | -------------------- | ---------- | -------------------: | ------------- | ----------------------------------------- | | `EthikosStance` | Korum | topic-level | `-3..+3` | User stance on a topic | | `ArgumentImpactVote` | Korum | argument/claim-level | `0..4` | Impact of a claim on its parent | | `Smart Vote Reading` | Smart Vote | aggregate/derived | lens-specific | Published interpretation of source events | ## 7.1 `EthikosStance` `EthikosStance` is the canonical topic-level stance. ```yaml ETHIKOS_STANCE: MODEL: "EthikosStance" OWNER: "Korum" LEVEL: "topic" RANGE: "-3..+3" MEANING: - "-3 strongly against" - "0 neutral / undecided" - "+3 strongly for" ``` Rules: ```yaml ETHIKOS_STANCE_RULES: - "An EthikosStance is a source fact." - "An EthikosStance may be used as input to a baseline result." - "An EthikosStance may be used as input to a Smart Vote reading." - "An EthikosStance must not store weighted meaning directly." ``` --- ## 7.2 `ArgumentImpactVote` `ArgumentImpactVote` is a Kialo-style claim-level signal. ```yaml ARGUMENT_IMPACT_VOTE: MODEL: "ArgumentImpactVote" OWNER: "Korum" LEVEL: "argument / claim" RANGE: "0..4" MEANING: "Perceived impact, relevance, and/or strength of a claim relative to its parent." ``` Rules: ```yaml ARGUMENT_IMPACT_VOTE_RULES: - "ArgumentImpactVote is not a topic stance." - "ArgumentImpactVote is not a Smart Vote ballot." - "ArgumentImpactVote may affect argument quality analytics." - "ArgumentImpactVote may inform summaries or debate health metrics." - "ArgumentImpactVote must not be mixed into baseline decision results unless a lens explicitly declares it as allowed input." ``` --- ## 7.3 Smart Vote reading A Smart Vote reading is an aggregate output. ```yaml SMART_VOTE_READING: MODEL: "ReadingResult" OWNER: "Smart Vote" LEVEL: "aggregate" RANGE: "depends on reading type" MEANING: "Declared interpretation of source facts." ``` Rules: ```yaml SMART_VOTE_READING_RULES: - "A Smart Vote reading is not a source fact." - "A Smart Vote reading must be reproducible." - "A Smart Vote reading must reference its lens." - "A Smart Vote reading must reference its EkoH snapshot when EkoH context is used." - "A Smart Vote reading must never overwrite baseline results." ``` --- ## 8. Baseline result contract A baseline result is the canonical unweighted aggregation of source events. ```yaml BASELINE_RESULT: reading_key: "baseline" weighting: "none" source_truth: "raw events" snapshot_ref_required: false lens_hash_required: true ``` ## 8.1 Allowed baseline inputs Allowed baseline inputs must be raw, source-owned events. ```yaml BASELINE_ALLOWED_INPUTS: KORUM: - "EthikosStance" KONSULTATIONS: - "BallotEvent" SMART_VOTE: - "Vote.raw_value" ``` ## 8.2 Disallowed baseline inputs ```yaml BASELINE_DISALLOWED_INPUTS: - "Vote.weighted_value" - "VoteResult.sum_weighted_value" - "UserExpertiseScore.weighted_score" - "UserEthicsScore" - "EkoH-derived multiplier" - "ArgumentImpactVote unless explicitly declared in a non-baseline reading" ``` ## 8.3 Baseline display rule Any UI that displays a weighted, filtered, expert-only, cohort-only, or EkoH-adjusted result must also keep the baseline visible or reachable. ```yaml BASELINE_VISIBILITY_RULE: BASELINE_MUST_REMAIN_VISIBLE: true WEIGHTED_READING_MAY_BE_HIGHLIGHTED: true WEIGHTED_READING_MUST_NOT_ERASE_BASELINE: true ``` --- ## 9. Lens declaration contract A `LensDeclaration` is the contract that defines how a reading is computed. Every non-trivial reading must have a lens. ## 9.1 Required fields ```yaml LensDeclaration: reading_key: type: "string" required: true examples: - "baseline" - "ekoh_weighted_v1" - "expert_cohort_v1" - "public_krowd_v1" - "elite_council_v1" label: type: "string" required: true examples: - "Baseline" - "EkoH-weighted" - "Expert cohort" - "Public Krowd" description: type: "text" required: true allowed_inputs: type: "array[string]" required: true examples: - "EthikosStance" - "BallotEvent" - "Vote.raw_value" segmentation_rules: type: "json" required: true nullable: false weighting_rules: type: "json" required: true nullable: false required_snapshot_refs: type: "array[string]" required: true examples: - "ekoh_snapshot_id" - "score_configuration_hash" lens_hash: type: "string" required: true description: "Stable content-addressable hash of the lens declaration." version: type: "string" required: true examples: - "v1" - "v1.1" status: type: "enum" required: true values: - "draft" - "active" - "deprecated" - "archived" created_at: type: "datetime" required: true updated_at: type: "datetime" required: true ``` ## 9.2 Lens hash rule The `lens_hash` must change when any of the following changes: ```yaml LENS_HASH_REQUIRES_CHANGE_WHEN: - "allowed_inputs changes" - "segmentation_rules changes" - "weighting_rules changes" - "required_snapshot_refs changes" - "thresholds change" - "cohort definitions change" - "score configuration reference changes" ``` The `lens_hash` must not change for display-only copy changes unless the change affects interpretation. --- ## 10. Reading result contract A `ReadingResult` is the stored output of a lens applied to source events. ## 10.1 Required fields ```yaml ReadingResult: id: type: "integer or uuid" required: true reading_key: type: "string" required: true examples: - "baseline" - "ekoh_weighted_v1" lens_hash: type: "string" required: true snapshot_ref: type: "string" nullable: true required_if: - "EkoH context is used" - "cohort eligibility is derived from EkoH" - "expertise weighting is used" - "ethics weighting is used" target_type: type: "string" required: true examples: - "ethikos_topic" - "consultation" - "decision_record" - "project" target_id: type: "integer or uuid" required: true computed_at: type: "datetime" required: true source_event_window: type: "object" required: true fields: from: type: "datetime" nullable: true to: type: "datetime" nullable: true source_event_counts: type: "json" required: true results_payload: type: "json" required: true audit_payload: type: "json" required: true status: type: "enum" required: true values: - "pending" - "computed" - "published" - "invalidated" - "archived" ``` ## 10.2 Minimal `results_payload` ```json { "summary": { "support": 0.0, "oppose": 0.0, "neutral": 0.0, "total_participants": 0 }, "distribution": [], "breakdowns": {}, "confidence": { "sample_size": 0, "minimum_threshold_met": false, "notes": [] } } ``` ## 10.3 Minimal `audit_payload` ```json { "lens_hash": "sha256:...", "input_sources": [], "input_event_ids_hash": "sha256:...", "snapshot_ref": null, "score_configuration_hash": null, "computed_by": "smart_vote", "code_version": null, "warnings": [] } ``` --- ## 11. EkoH snapshot contract An EkoH snapshot is a frozen reference to the EkoH context used by a reading. It may include: ```yaml EKOH_SNAPSHOT_MAY_INCLUDE: - "expertise category taxonomy version" - "user expertise scores" - "user ethics scores" - "score configuration" - "cohort eligibility" - "domain relevance vector" - "privacy/confidentiality settings" - "emerging expert markers" ``` ## 11.1 Required when EkoH is used If a reading uses EkoH scores, ethics multipliers, cohort eligibility, expert thresholds, domain relevance, or emerging expert signals, it must include: ```yaml EKOH_REQUIRED_READING_FIELDS: snapshot_ref: "required" lens_hash: "required" score_configuration_hash: "required" computed_at: "required" results_payload: "required" ``` ## 11.2 EkoH must not mutate votes ```yaml EKOH_MUTATION_RULES: EKOH_MUTATES_ETHIKOS_STANCE: false EKOH_MUTATES_BALLOT_EVENT: false EKOH_MUTATES_ARGUMENT_IMPACT_VOTE: false EKOH_MUTATES_SMART_VOTE_RAW_VALUE: false ``` EkoH may change future readings only by changing the snapshot/context used in a new computation. Existing published readings must not silently change when EkoH scores change. --- ## 12. Weighting contract Smart Vote may compute weighted values using EkoH context. The current Smart Vote architecture includes `Vote.raw_value`, `Vote.weighted_value`, `VoteResult.sum_weighted_value`, and vote modality definitions. ## 12.1 Raw value ```yaml RAW_VALUE: source: "user action" examples: - "stance value" - "approval value" - "rating value" - "ranking position" mutable_by_smart_vote: false ``` ## 12.2 Weighted value ```yaml WEIGHTED_VALUE: source: "Smart Vote computation" inputs: - "raw_value" - "LensDeclaration" - "EkoH snapshot if used" mutable_by_smart_vote: true source_fact: false ``` ## 12.3 Weighting function The exact implementation may vary by modality, but every weighted reading must conceptually follow: ```text weighted_value = f(raw_value, lens_declaration, ekoh_snapshot_context?) ``` Where: ```yaml WEIGHTING_INPUTS: raw_value: required: true lens_declaration: required: true ekoh_snapshot_context: required_if: - "expertise weighting" - "ethics weighting" - "cohort filtering" - "expert threshold" ``` ## 12.4 Hard rule `weighted_value` is not the canonical civic fact. It is a derived value. --- ## 13. Current implementation alignment ## 13.1 Current backend concepts The current backend already contains Smart Vote concepts that must be respected: ```yaml CURRENT_SMART_VOTE_MODELS: - "Vote" - "VoteResult" - "VoteModality" - "VoteLedger" ``` Known current model semantics: ```yaml Vote: fields: - "user" - "target_type" - "target_id" - "modality" - "raw_value" - "weighted_value" - "created_at" VoteResult: fields: - "target_type" - "target_id" - "sum_weighted_value" - "vote_count" VoteModality: known_values: - "approval" - "ranking" - "rating" - "preferential" - "budget_split" VoteLedger: role: "append-only hash ledger for vote audit / anchoring" ``` ## 13.2 Current settings The backend settings include EkoH/Smart Vote apps and scheduled tasks: ```yaml CURRENT_EKOH_SMART_VOTE_APPS: - "konnaxion.ekoh" - "konnaxion.smart_vote" CURRENT_PERIODIC_TASKS: - "ekoh-score-recalc" - "ekoh-contextual-analysis" - "smartvote-vote-aggregate" ``` These tasks align with the Kintsugi requirement that EkoH context and Smart Vote aggregation remain separate responsibilities. ## 13.3 Current frontend alignment The existing EkoH route group already exposes Smart Vote surfaces such as voting weight and Konsensus activity. Kintsugi must preserve this separation: ```yaml FRONTEND_ALIGNMENT: EKOH_ROUTES: role: "identity, expertise, ethics, voting weight visibility" ETHIKOS_DECIDE_ROUTES: role: "decision workflows and reading publication" ETHIKOS_INSIGHTS_ROUTE: role: "analytics and reading comparison" KONSENSUS: role: "Smart Vote / collective poll center" ``` --- ## 14. Route display contract ## 14.1 `/ethikos/decide/*` Decision routes may display: ```yaml DECIDE_MAY_DISPLAY: - "BaselineResult" - "ReadingResult" - "DecisionRecord" - "Lens summary" - "EkoH weighted interpretation" - "Public vs expert readings" ``` Decision routes must not hide the baseline. --- ## 14.2 `/ethikos/insights` Insights may display: ```yaml INSIGHTS_MAY_DISPLAY: - "Reading comparison" - "Weighted vs unweighted deltas" - "Score distributions" - "Expertise and ethics breakdowns" - "Consensus evolution" - "Emerging expert signals" ``` Insights should fetch via a service layer that composes Smart Vote / Kollective data with domain APIs, instead of embedding raw multi-endpoint orchestration inside components. --- ## 14.3 `/ethikos/pulse/*` Pulse may display: ```yaml PULSE_MAY_DISPLAY: - "participation health" - "current baseline trend" - "reading divergence" - "expert/public gap" - "minimum threshold warnings" ``` Pulse must not present a weighted result as if it were the only public outcome. --- ## 14.4 `/ethikos/trust/*` Trust routes may display: ```yaml TRUST_MAY_DISPLAY: - "EkoH expertise profile" - "EkoH ethics signals" - "badges" - "credentials" - "voting weight explanation" ``` Trust routes must not expose confidential EkoH data beyond the configured visibility rules. --- ## 15. API and service contract This document does not create final API endpoints by itself. Endpoint definitions belong in `07_API_AND_SERVICE_CONTRACTS.md`. However, the following rules are binding. ## 15.1 Existing endpoints to respect ```yaml EXISTING_RELEVANT_ENDPOINTS: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" KOLLECTIVE_VOTES: "/api/kollective/votes/" SMART_VOTE_API_V1: "/api/v1/smart-vote/" EKOH_API_V1: "/api/v1/ekoh/" ``` The current backend includes `/api/v1/ekoh/` and `/api/v1/smart-vote/` route includes. ## 15.2 Service-layer rule Frontend components must not directly orchestrate readings by fetching multiple low-level endpoints inside page components. ```yaml SERVICE_LAYER_REQUIRED: - "services/ethikos" - "services/decide" - "services/insights" - "services/kollective or smart-vote service wrapper" ``` ## 15.3 Reading API shape A future reading endpoint should expose a shape compatible with: ```json { "target_type": "ethikos_topic", "target_id": 123, "baseline": { "reading_key": "baseline", "lens_hash": "sha256:...", "snapshot_ref": null, "computed_at": "2026-04-25T00:00:00Z", "results_payload": {} }, "readings": [ { "reading_key": "ekoh_weighted_v1", "lens_hash": "sha256:...", "snapshot_ref": "ekoh_snapshot:...", "computed_at": "2026-04-25T00:00:00Z", "results_payload": {} } ] } ``` --- ## 16. Privacy and confidentiality EkoH data may be sensitive. A reading may use EkoH information without exposing individual EkoH scores. ## 16.1 Public output rule Public readings may expose: ```yaml PUBLIC_READING_MAY_EXPOSE: - "aggregate weighted result" - "aggregate expert cohort result" - "number of eligible participants" - "threshold met / not met" - "lens explanation" ``` Public readings must not expose: ```yaml PUBLIC_READING_MUST_NOT_EXPOSE: - "individual private EkoH score" - "individual ethics score" - "private cohort eligibility reason" - "identity behind anonymous or pseudonymous setting" ``` ## 16.2 Admin/audit output rule Admin surfaces may expose more detail only if permissions allow. ```yaml ADMIN_AUDIT_MAY_EXPOSE: - "score configuration hash" - "cohort counts" - "excluded-event counts" - "snapshot reference" - "lens declaration" - "computation warnings" ``` Even admin surfaces should avoid exposing private score details unless there is a defined operational reason. --- ## 17. Thresholds and confidence A reading should not imply legitimacy when the data is insufficient. ## 17.1 Minimum fields Every reading payload should include: ```yaml READING_CONFIDENCE_FIELDS: sample_size: "integer" eligible_population_size: "integer | null" minimum_threshold_met: "boolean" warnings: "array[string]" ``` ## 17.2 Example warnings ```yaml READING_WARNINGS: - "insufficient_sample_size" - "expert_threshold_not_met" - "snapshot_missing" - "lens_deprecated" - "baseline_event_window_too_small" - "cohort_filter_too_narrow" ``` ## 17.3 Expert threshold Existing references define an expert quorum concept for ethiKos results: a minimum expert vote count with EkoH percentile logic. This contract does not hard-code all thresholds, but requires any threshold to be declared in the lens. --- ## 18. Invalidating readings A reading must be invalidated when the inputs or interpretation contract are no longer reliable. ```yaml INVALIDATE_READING_WHEN: - "source events changed after computed_at and reading is not explicitly frozen" - "lens declaration changed" - "lens_hash changed" - "EkoH snapshot was revoked or invalidated" - "score configuration was corrected" - "privacy rule changed" - "bug found in computation" ``` Invalidation must not delete the old reading unless retention policy permits deletion. Preferred behavior: ```yaml READING_INVALIDATION_BEHAVIOR: - "mark status = invalidated" - "store invalidated_at" - "store invalidation_reason" - "recompute as a new ReadingResult" ``` --- ## 19. Publishing rules ## 19.1 Baseline publishing Baseline may be published when: ```yaml BASELINE_PUBLISHING_REQUIREMENTS: - "source event query succeeded" - "source event count is recorded" - "result payload is generated" - "computed_at is recorded" ``` ## 19.2 Weighted reading publishing Weighted readings may be published only when: ```yaml WEIGHTED_READING_PUBLISHING_REQUIREMENTS: - "LensDeclaration is active" - "lens_hash is recorded" - "snapshot_ref is recorded if EkoH is used" - "source_event_counts are recorded" - "audit_payload is recorded" - "minimum threshold status is explicit" - "baseline remains visible" ``` ## 19.3 UI label rule Every non-baseline reading must be labeled. Good labels: ```yaml GOOD_LABELS: - "Baseline" - "EkoH-weighted reading" - "Expert cohort reading" - "Public Krowd reading" - "Elite council reading" ``` Bad labels: ```yaml BAD_LABELS: - "The result" - "True result" - "Corrected vote" - "Real consensus" - "Expert truth" ``` --- ## 20. Audit reproducibility A reading is valid only if it can be recomputed. ## 20.1 Required reproducibility inputs ```yaml REPRODUCIBILITY_INPUTS: - "target_type" - "target_id" - "source event query definition" - "source event window" - "source event ids hash" - "lens declaration" - "lens_hash" - "snapshot_ref if used" - "score configuration hash if used" - "code version if available" - "computed_at" ``` ## 20.2 Required reproducibility statement Every reading documentation or admin detail page should be able to state: ```text This reading was computed from [source events] using [lens] at [computed_at], with [snapshot_ref], producing [results_payload]. ``` --- ## 21. Data model implications The following models are either current, proposed, or required by this contract. ## 21.1 Current or already present concepts ```yaml CURRENT_OR_EXISTING: - "Vote" - "VoteResult" - "VoteModality" - "VoteLedger" - "UserExpertiseScore" - "UserEthicsScore" - "ExpertiseCategory" - "ScoreConfiguration" - "ScoreHistory" - "EthikosStance" ``` ## 21.2 Proposed Kintsugi models ```yaml PROPOSED_FOR_KINTSUGI: - "LensDeclaration" - "ReadingResult" - "ReadingAuditRecord" - "SnapshotRef" ``` ## 21.3 Fields that must not be added to source tables as shortcuts Do not add these as canonical source fields on `EthikosStance`, `EthikosArgument`, or ballot source tables: ```yaml DO_NOT_ADD_AS_SOURCE_TRUTH: - "weighted_result" - "expert_result" - "ekoh_adjusted_value" - "final_truth_value" - "corrected_stance" ``` If needed, such values belong in `ReadingResult` or another derived artifact. --- ## 22. Example lens declarations ## 22.1 Baseline ```yaml reading_key: "baseline" label: "Baseline" description: "Raw unweighted aggregation of source events." allowed_inputs: - "EthikosStance" segmentation_rules: {} weighting_rules: type: "none" required_snapshot_refs: [] lens_hash: "sha256:" version: "v1" status: "active" ``` ## 22.2 EkoH-weighted reading ```yaml reading_key: "ekoh_weighted_v1" label: "EkoH-weighted reading" description: "Weighted reading using EkoH domain expertise and ethics context." allowed_inputs: - "EthikosStance" segmentation_rules: include_users: "all_eligible" weighting_rules: type: "ekoh_domain_expertise_and_ethics" expertise_source: "UserExpertiseScore" ethics_source: "UserEthicsScore" cap_source: "ScoreConfiguration" required_snapshot_refs: - "ekoh_snapshot_id" - "score_configuration_hash" lens_hash: "sha256:" version: "v1" status: "active" ``` ## 22.3 Expert cohort reading ```yaml reading_key: "expert_cohort_v1" label: "Expert cohort reading" description: "Filtered reading using participants above an EkoH expertise threshold in the topic domain." allowed_inputs: - "EthikosStance" segmentation_rules: cohort: "experts" expertise_percentile_min: 75 weighting_rules: type: "none_or_declared" required_snapshot_refs: - "ekoh_snapshot_id" lens_hash: "sha256:" version: "v1" status: "active" ``` --- ## 23. Example reading result ```json { "reading_key": "ekoh_weighted_v1", "lens_hash": "sha256:7b5f...", "snapshot_ref": "ekoh_snapshot:2026-04-25T15:00:00Z", "target_type": "ethikos_topic", "target_id": 42, "computed_at": "2026-04-25T15:30:00Z", "source_event_window": { "from": "2026-04-01T00:00:00Z", "to": "2026-04-25T15:29:59Z" }, "source_event_counts": { "EthikosStance": 184, "excluded": 3 }, "results_payload": { "summary": { "support": 0.68, "oppose": 0.21, "neutral": 0.11, "total_participants": 181 }, "distribution": [ { "bucket": "-3", "weighted_share": 0.05 }, { "bucket": "-2", "weighted_share": 0.07 }, { "bucket": "-1", "weighted_share": 0.09 }, { "bucket": "0", "weighted_share": 0.11 }, { "bucket": "+1", "weighted_share": 0.19 }, { "bucket": "+2", "weighted_share": 0.24 }, { "bucket": "+3", "weighted_share": 0.25 } ], "confidence": { "sample_size": 181, "minimum_threshold_met": true, "notes": [] } }, "audit_payload": { "lens_hash": "sha256:7b5f...", "input_event_ids_hash": "sha256:91ab...", "snapshot_ref": "ekoh_snapshot:2026-04-25T15:00:00Z", "score_configuration_hash": "sha256:f310...", "computed_by": "smart_vote", "warnings": [] }, "status": "published" } ``` --- ## 24. Anti-drift rules ```yaml ANTI_DRIFT_RULES: - "Do not call a weighted reading the baseline." - "Do not hide the baseline when displaying weighted readings." - "Do not let Smart Vote mutate Korum records." - "Do not let Smart Vote mutate Konsultations records." - "Do not let EkoH mutate votes, stances, or ballots." - "Do not treat EkoH as the voting engine." - "Do not treat EthikosStance as a Smart Vote reading." - "Do not treat ArgumentImpactVote as an EthikosStance." - "Do not treat ArgumentImpactVote as a Smart Vote ballot." - "Do not store weighted outcomes as canonical consultation results." - "Do not publish an EkoH-derived reading without snapshot_ref." - "Do not publish a non-baseline reading without lens_hash." - "Do not silently recompute published readings without new computed_at." - "Do not expose individual private EkoH scores in public reading payloads." ``` --- ## 25. Non-goals This document does not: * define all Smart Vote UI screens; * replace the Smart Vote technical specification; * replace the EkoH schema documentation; * define every database migration; * define all endpoints; * define Kialo-style argument impact voting in full; * define implementation tasks; * authorize direct OSS integration; * authorize any full external merge. --- ## 26. Acceptance checklist A Smart Vote/EkoH reading implementation is acceptable only if all of the following are true: ```yaml ACCEPTANCE_CHECKLIST: baseline: - "Baseline result exists or is explicitly unavailable." - "Baseline is raw and unweighted." - "Baseline remains visible when readings are shown." lens: - "Every non-baseline reading has a LensDeclaration." - "Every lens has a stable lens_hash." - "Allowed inputs are explicit." - "Weighting rules are explicit." - "Segmentation rules are explicit." ekoh: - "EkoH-derived readings include snapshot_ref." - "EkoH-derived readings include score/config audit references." - "Private EkoH data is not leaked in public payloads." audit: - "computed_at is stored." - "source_event_counts are stored." - "results_payload is stored." - "audit_payload is stored." - "reading can be recomputed." ownership: - "Smart Vote does not mutate upstream Korum/Konsultations facts." - "EkoH does not act as the voting engine." - "Weighted values are stored as derived artifacts." ``` --- ## 27. Related documents ```yaml RELATED_DOCS: - "00_KINTSUGI_START_HERE.md" - "02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md" - "03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md" - "04_CANONICAL_NAMING_AND_VARIABLES.md" - "06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md" - "07_API_AND_SERVICE_CONTRACTS.md" - "08_DATA_MODEL_AND_MIGRATION_PLAN.md" - "12_CANONICAL_OBJECTS_AND_EVENTS.md" - "13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md" - "14_FRONTEND_ALIGNMENT_CONTRACT.md" - "15_BACKEND_ALIGNMENT_CONTRACT.md" - "20_AI_GENERATION_GUARDRAILS.md" - "21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md" ``` --- ## 28. Final normative summary ```yaml FINAL_CONTRACT: SINGLE_TRUTH: "source events" MULTIPLE_READINGS: "declared Smart Vote outputs" BASELINE: "raw unweighted aggregation" WEIGHTED_RESULT: "derived reading" SMART_VOTE_ROLE: "compute and publish readings" EKOH_ROLE: "provide expertise/ethics context" EKOH_IS_VOTING_ENGINE: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKO_H_SNAPSHOT_REQUIRED_WHEN_USED: true LENS_HASH_REQUIRED_FOR_EVERY_READING: true BASELINE_MUST_REMAIN_VISIBLE: true ``` --- ## V4.1 clarification — rating disclosure is not reading ownership EkoH rating visibility and Smart Vote contextual influence are different contracts. Smart Vote may compute aggregate declared readings from EkoH context while participant-level EkoH-derived detail returned to a caller MUST respect the EkoH disclosure decision. This does not alter the baseline, source stances, or reading formula. See `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/10_FIRST_PASS_INTEGRATION_MATRIX.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 70020466ed2f9d8b1a4c1a675e05c90545ab9593bfe5e40de6cdac1b429d27c3 CONTENT_BYTES: 46751 ================================================================================================ # 10 — First-Pass Integration Matrix **File:** `10_FIRST_PASS_INTEGRATION_MATRIX.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Status:** Canonical first-pass scope matrix **Module:** `ethiKos` **Platform:** `Konnaxion` --- ## 1. Purpose This document defines the **first-pass integration matrix** for the ethiKos Kintsugi Upgrade. Its purpose is to prevent drift when translating external civic-tech inspiration into native ethiKos features. This matrix answers: - which external sources are in scope now; - which sources are explicitly deferred; - which patterns are retained; - which patterns are rejected or postponed; - where each pattern maps into the existing `/ethikos/*` route surface; - which current or proposed ethiKos objects each pattern affects; - whether each pattern should be implemented as native mimic, future annex, or no-go; - what must not be imported, renamed, or merged. This document is not an implementation backlog. It is a scope and alignment contract. --- ## 2. Scope This document covers first-pass Kintsugi inspiration from: ```yaml FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" ```` This document also records the explicitly deferred sources: ```yaml DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ``` --- ## 3. Canonical variables used ```yaml KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_ETHIKOS_FRAME_STABLE: true DOCS_BEFORE_CODE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true ``` ```yaml PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_ROUTE_FAMILIES: DELIBERATE: "/ethikos/deliberate/*" DECIDE: "/ethikos/decide/*" IMPACT: "/ethikos/impact/*" PULSE: "/ethikos/pulse/*" TRUST: "/ethikos/trust/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" ``` ```yaml OWNERSHIP: KORUM_OWNS: - "Topics" - "Arguments" - "Threaded argument graph" - "Topic-level stance events" - "Debate moderation" KONSULTATIONS_OWNS: - "Intake" - "Consultations" - "Citizen suggestions" - "Ballot capture" - "Result snapshots" - "Impact tracking" SMART_VOTE_OWNS: - "Derived readings" - "Lens declarations" - "Aggregations" - "Result publication" EKOH_OWNS: - "Expertise context" - "Ethics context" - "Cohort eligibility" - "Snapshots" ``` ```yaml MIMIC_VS_ANNEX: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" MIMIC_FIRST_PASS: true ANNEX_FIRST_PASS_ALLOWED: false FULL_CODE_IMPORT_DEFAULT: false ``` --- ## 4. Non-goals This document does not: * authorize importing external OSS code; * authorize a full merge of any civic-tech platform; * create a new Kialo app; * create a new Kintsugi frontend app; * replace existing `/ethikos/*` routes; * replace current `EthikosTopic`, `EthikosStance`, `EthikosArgument`, or `EthikosCategory`; * redefine Korum/Konsultations/Smart Vote/EkoH ownership; * generate backend tickets; * generate frontend tickets; * define migrations in final detail; * decide final serializer payloads; * solve the preview drawer bug; * include Polis, LiquidFeedback, All Our Ideas, Your Priorities, or OpenSlides in first pass. --- ## 5. First-pass matrix summary | Source | First-pass status | Strategy | Primary retained pattern | Primary ethiKos route family | Primary owner | First-pass priority | | ---------------------------- | ----------------: | ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------- | ------------------: | | Consider.it | In scope | Native mimic | Reason capture, pro/con deliberation compression | `/ethikos/deliberate/*` | Korum | P2 | | Kialo-style argument mapping | In scope | Native mimic | Structured claim graph, sources, impact voting, permissions | `/ethikos/deliberate/*` | Korum | P0 | | Loomio | In scope | Native mimic | Proposal lifecycle, time-boxed decisions, outcome publishing | `/ethikos/decide/*` | Smart Vote + ethiKos decision layer | P1 | | Citizen OS | In scope | Native mimic | Drafting, versioning, amendments, collaborative text flow | Drafting capability + `/ethikos/decide/*` | ethiKos drafting capability | P1 | | Decidim | In scope | Native mimic | Civic process architecture, phases, accountability, admin governance | `/ethikos/impact/*`, `/ethikos/admin/*`, `/ethikos/pulse/*` | Konsultations + Admin | P1 | | CONSUL Democracy | In scope | Native mimic | Eligibility, thresholds, proposal gating, consultation governance | `/ethikos/decide/*`, `/ethikos/admin/*`, `/ethikos/impact/*` | Konsultations + Smart Vote | P2 | | DemocracyOS | In scope | Native mimic | Proposal-centric policy debate | `/ethikos/decide/*`, `/ethikos/deliberate/*` | Korum + decision layer | P2 | Priority scale: ```yaml P0: "Foundational; must shape first-pass documentation and contracts." P1: "Core Kintsugi extension; likely first implementation wave after contracts." P2: "Important pattern source; useful after P0/P1 contracts are stable." P3: "Deferred or reference-only." ``` --- ## 6. Deferred matrix summary | Source | Status | Reason | Allowed first-pass use | | --------------- | --------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------ | | Polis | Deferred | Consensus clustering is powerful but outside current partial-native first pass | Public credit / future research only | | LiquidFeedback | Deferred | Delegated/liquid democracy would alter decision semantics too early | Public credit / future research only | | All Our Ideas | Deferred | Pairwise idea ranking is not needed for first pass | None beyond future idea note | | Your Priorities | Deferred | Civic ideation workflow overlaps with later Konsultations work | None beyond future idea note | | OpenSlides | Deferred / future annex candidate | Meeting/parliament workflow is too specialized for first pass | Future annex research only | Deferred sources MUST NOT generate first-pass models, routes, migrations, services, or backlog tasks. --- ## 7. Source-by-source integration detail --- # 7.1 Consider.it ## 7.1.1 Status ```yaml SOURCE: "Consider.it" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P2" PRIMARY_ROUTE_SCOPE: "/ethikos/deliberate/*" PRIMARY_OWNER: "Korum" ``` ## 7.1.2 Retained pattern Consider.it is retained as inspiration for: * compact pro/con reasoning; * surfacing reasons rather than chronological noise; * making participant positions more legible; * reason clusters; * structured comparison between support and opposition. ## 7.1.3 ethiKos mapping | Consider.it concept | ethiKos Kintsugi mapping | | | | ------------------- | -------------------------------------------------- | --- | -------- | | Position on issue | `EthikosStance` | | | | Reason for/against | `EthikosArgument` with `side` | | | | Pro/con structure | `EthikosArgument.side = pro | con | neutral` | | Reason grouping | Future `ArgumentGraph` view or derived clustering | | | | Participant opinion | Topic-level stance + argument contribution pattern | | | ## 7.1.4 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/deliberate/[topic]" SECONDARY: - "/ethikos/deliberate/elite" - "/ethikos/pulse/health" - "/ethikos/insights" ``` ## 7.1.5 Model impact Current models sufficient for first expression: ```yaml CURRENT_MODELS_USED: - "EthikosTopic" - "EthikosStance" - "EthikosArgument" ``` Possible future support models: ```yaml POSSIBLE_MODELS: - "ArgumentCluster" - "ArgumentSummary" ``` These possible models are not first-pass mandatory. ## 7.1.6 First-pass allowed work Consider.it MAY inspire: * clearer pro/con presentation; * topic stance summary; * reason cards; * argument-side filtering; * deliberation summary panels. ## 7.1.7 First-pass forbidden work Consider.it MUST NOT cause: * a new `considerit` app; * external code import; * replacement of `EthikosArgument`; * replacement of `/ethikos/deliberate/*`; * direct writes from external tools. ## 7.1.8 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.2 Kialo-style argument mapping ## 7.2.1 Status ```yaml SOURCE: "Kialo-style argument mapping" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P0" PRIMARY_ROUTE_SCOPE: "/ethikos/deliberate/*" PRIMARY_OWNER: "Korum" ``` ## 7.2.2 Retained pattern Kialo-style mapping is the canonical first-pass reference for structured deliberation. It contributes: * thesis-centered discussion; * single-thesis and multi-thesis topology; * claims as atomic argument nodes; * pro/con relation to parent; * argument tree navigation; * minimap concept; * sources attached to claims; * impact voting on claims; * guided voting; * perspectives; * suggested claims; * participant roles; * anonymity mode; * author visibility; * vote visibility; * templates; * small group mode; * discussion export. Only a subset is first pass. ## 7.2.3 Canonical ethiKos mapping ```yaml KIALO_CANONICAL_MAPPING: KIALO_DISCUSSION: "EthikosTopic" KIALO_THESIS: "Topic thesis/prompt field; current fallback is EthikosTopic.title + description" KIALO_CLAIM: "EthikosArgument" KIALO_PRO_CON_EDGE: "EthikosArgument.parent + EthikosArgument.side" KIALO_SOURCE: "ArgumentSource" KIALO_IMPACT_VOTE: "ArgumentImpactVote" KIALO_SUGGESTED_CLAIM: "ArgumentSuggestion" KIALO_PERSPECTIVE: "DiscussionPerspective / Smart Vote lens depending context" KIALO_PARTICIPANT_ROLE: "DiscussionParticipantRole" ``` ## 7.2.4 Critical separation Kialo introduces claim-level impact voting. This must remain separate from ethiKos topic-level stance and Smart Vote readings. ```yaml VOTE_TYPE_SEPARATION: ETHIKOS_STANCE: RANGE: "-3..+3" LEVEL: "topic-level" MODEL: "EthikosStance" KIALO_IMPACT_VOTE: RANGE: "0..4" LEVEL: "claim-level" PROPOSED_MODEL: "ArgumentImpactVote" SMART_VOTE_READING: RANGE: "lens-dependent" LEVEL: "derived aggregation" PROPOSED_MODEL: "ReadingResult" ``` Mandatory rules: ```yaml CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false ``` ## 7.2.5 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/deliberate/[topic]" SECONDARY: - "/ethikos/deliberate/elite" - "/ethikos/deliberate/guidelines" - "/ethikos/admin/moderation" - "/ethikos/admin/roles" - "/ethikos/insights" ``` ## 7.2.6 First-pass feature subset ```yaml KIALO_FIRST_PASS_FEATURES: - "Argument tree using current EthikosArgument parent + side" - "Claim/source links" - "Role-aware suggested claims" - "Impact vote separated from topic stance" - "Author visibility settings" - "Voting visibility settings" - "Basic topic info/background panel" ``` ## 7.2.7 Deferred Kialo features ```yaml KIALO_DEFERRED_FEATURES: - "Small group mode" - "Sunburst minimap" - "Clone-from-template" - "Export discussion" - "Custom perspectives" - "Claim extraction into new discussion" - "Move/link claim across discussions" ``` ## 7.2.8 Model impact Existing models: ```yaml CURRENT_MODELS_USED: - "EthikosTopic" - "EthikosArgument" - "EthikosStance" ``` First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" ``` Later model candidates: ```yaml DEFERRED_MODEL_CANDIDATES: - "ArgumentBookmark" - "ArgumentLink" - "DiscussionPerspective" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionExport" ``` ## 7.2.9 Required enum alignment ```yaml KIALO_VALUES: KIALO_EDGE_SIDE_VALUES: - "pro" - "con" - "neutral" KIALO_IMPACT_VOTE_RANGE: "0..4" KIALO_ROLES: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" KIALO_ANONYMITY_MODES: - "standard" - "anonymous" KIALO_AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" KIALO_VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" KIALO_DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" KIALO_MINIMAP_MODES: - "tree" - "sunburst" ``` ## 7.2.10 First-pass forbidden work Kialo-style mapping MUST NOT cause: * renaming `EthikosArgument` to `Claim`; * creating `konnaxion.kialo`; * creating `/kialo` routes; * importing Kialo code; * treating claim impact votes as topic stances; * treating claim impact votes as Smart Vote ballots; * exposing anonymous identities to non-admin users; * publishing suggested claims without approval when role is `suggester`. ## 7.2.11 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.3 Loomio ## 7.3.1 Status ```yaml SOURCE: "Loomio" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P1" PRIMARY_ROUTE_SCOPE: "/ethikos/decide/*" PRIMARY_OWNER: "Smart Vote + ethiKos decision layer" ``` ## 7.3.2 Retained pattern Loomio is retained as inspiration for: * proposal lifecycle; * time-boxed decisions; * consent/objection/approval flows; * explicit decision closure; * outcome publication; * clear transition from discussion to decision. ## 7.3.3 ethiKos mapping | Loomio concept | ethiKos Kintsugi mapping | | ------------------------------- | -------------------------------------------- | | Discussion thread | `EthikosTopic` + `EthikosArgument` | | Proposal | `DecisionRecord` | | Poll/decision | `DecisionProtocol` + `DecisionRecord` | | Stance/vote in decision context | `BallotEvent` or Smart Vote-compatible event | | Outcome | `DecisionRecord.outcome` + `ReadingResult` | | Closing date | `DecisionRecord.opens_at` / `closes_at` | | Decision method | `DecisionProtocol` | ## 7.3.4 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/decide/public" - "/ethikos/decide/elite" - "/ethikos/decide/results" SECONDARY: - "/ethikos/decide/methodology" - "/ethikos/admin/audit" - "/ethikos/insights" ``` ## 7.3.5 Model impact First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "DecisionProtocol" - "DecisionRecord" - "LensDeclaration" - "ReadingResult" ``` Possible support objects: ```yaml SUPPORT_OBJECTS: - "BallotEvent" - "BaselineResult" ``` ## 7.3.6 First-pass allowed work Loomio MAY inspire: * decision lifecycle states; * decision protocol names; * opening and closing windows; * outcome publishing; * objection/consent logic; * result explanation. ## 7.3.7 First-pass forbidden work Loomio MUST NOT cause: * importing Loomio code; * changing the authentication model; * creating a separate decision app; * replacing Smart Vote; * allowing Smart Vote to mutate source records; * collapsing deliberation and decision into one table. ## 7.3.8 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.4 Citizen OS ## 7.4.1 Status ```yaml SOURCE: "Citizen OS" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P1" PRIMARY_ROUTE_SCOPE: "Drafting capability + /ethikos/decide/*" PRIMARY_OWNER: "ethiKos bounded drafting capability" ``` ## 7.4.2 Retained pattern Citizen OS is retained as inspiration for: * collaborative drafting; * versioned text; * amendments; * decision-ready documents; * structured transition from deliberation to written proposal; * separation between discussion and text editing. ## 7.4.3 Architectural caution Citizen OS architecture may rely on external collaborative editing infrastructure such as Etherpad-like flows. The first pass MUST NOT annex such infrastructure. First pass should mimic the product pattern: * draft; * version; * amendment; * rationale; * decision-ready text. It must not integrate external pad infrastructure. ## 7.4.4 ethiKos mapping | Citizen OS concept | ethiKos Kintsugi mapping | | ---------------------- | -------------------------------------------------------- | | Topic | `EthikosTopic` | | Collaborative document | `Draft` | | Document revision | `DraftVersion` | | Proposed edit | `Amendment` | | Rationale / reasoning | `RationalePacket` | | Final proposal text | `DecisionRecord.subject_ref` or `Draft.accepted_version` | ## 7.4.5 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/decide/public" - "/ethikos/decide/elite" SECONDARY: - "/ethikos/deliberate/[topic]" - "/ethikos/impact/outcomes" - "/ethikos/admin/audit" ``` If a future `/ethikos/draft/*` route is proposed, it must be documented in `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` and approved by ADR before implementation. ## 7.4.6 Model impact First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" ``` ## 7.4.7 First-pass allowed work Citizen OS MAY inspire: * creating a draft from a topic; * creating versions of a draft; * attaching rationale to draft text; * linking amendments to arguments; * promoting a draft into a decision record. ## 7.4.8 First-pass forbidden work Citizen OS MUST NOT cause: * Etherpad annex in first pass; * external collaborative editing service dependency; * creating a separate Citizen OS route family; * importing Citizen OS code; * mixing draft versions directly into `EthikosArgument`; * treating draft text as the same object as the debate topic. ## 7.4.9 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.5 Decidim ## 7.5.1 Status ```yaml SOURCE: "Decidim" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P1" PRIMARY_ROUTE_SCOPE: "/ethikos/impact/* + /ethikos/admin/* + /ethikos/pulse/*" PRIMARY_OWNER: "Konsultations + Admin" ``` ## 7.5.2 Retained pattern Decidim is retained as inspiration for: * civic process architecture; * participatory phases; * proposals; * debates; * meetings as a future reference only; * accountability; * admin governance; * permissions; * taxonomies; * traceability; * public process transparency. ## 7.5.3 ethiKos mapping | Decidim concept | ethiKos Kintsugi mapping | | --------------------- | ------------------------------------------------------------------------------ | | Participatory process | `ProcessPhase` / ethiKos pipeline instance | | Component | Route-family capability under `/ethikos/*` | | Proposal | `DecisionRecord` or `Draft` depending stage | | Debate | `EthikosTopic` + `EthikosArgument` | | Accountability | `ImpactTrack` | | Admin permissions | `/ethikos/admin/roles` + `DiscussionParticipantRole` / future governance rules | | Traceability | `AuditEvent` / `ModerationAction` | | Taxonomy | `TopicTag` / category / policy domain | ## 7.5.4 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/impact/tracker" - "/ethikos/impact/outcomes" - "/ethikos/admin/audit" - "/ethikos/admin/moderation" - "/ethikos/admin/roles" SECONDARY: - "/ethikos/pulse/overview" - "/ethikos/pulse/health" - "/ethikos/learn/guides" ``` ## 7.5.5 Model impact First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "ImpactTrack" - "ImpactUpdate" - "ProcessPhase" - "AuditEvent" - "ModerationAction" ``` Some of these may already exist partially or be represented by current admin/moderation surfaces. The migration plan must verify current code before creating new tables. ## 7.5.6 First-pass allowed work Decidim MAY inspire: * process phases; * impact status tracking; * public accountability snapshots; * audit trails; * moderation transparency; * route-family explanation in Learn; * admin permissions review. ## 7.5.7 First-pass forbidden work Decidim MUST NOT cause: * importing Decidim/Rails code; * replacing the Django backend; * switching to GraphQL for first-pass CRUD; * creating Decidim-style component framework inside ethiKos; * making ethiKos a full civic operating system in first pass. ## 7.5.8 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.6 CONSUL Democracy ## 7.6.1 Status ```yaml SOURCE: "CONSUL Democracy" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P2" PRIMARY_ROUTE_SCOPE: "/ethikos/decide/* + /ethikos/admin/* + /ethikos/impact/*" PRIMARY_OWNER: "Konsultations + Smart Vote" ``` ## 7.6.2 Retained pattern CONSUL Democracy is retained as inspiration for: * consultation governance; * proposal thresholds; * eligibility rules; * census/participation boundaries; * admin-controlled participation settings; * public proposal lifecycle; * open-government accountability patterns. ## 7.6.3 ethiKos mapping | CONSUL concept | ethiKos Kintsugi mapping | | ------------------------------ | -------------------------------------------- | | Proposal | `DecisionRecord` or `Draft` | | Supports / votes | `BallotEvent` + Smart Vote baseline/readings | | Census / eligibility | `EligibilityRule` | | Participatory budget / process | Future consultation process type | | Admin moderation | `/ethikos/admin/moderation` | | Public result | `ReadingResult` + `DecisionRecord` | | Accountability | `ImpactTrack` | ## 7.6.4 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/decide/public" - "/ethikos/decide/results" - "/ethikos/admin/roles" - "/ethikos/impact/tracker" SECONDARY: - "/ethikos/decide/methodology" - "/ethikos/learn/guides" ``` ## 7.6.5 Model impact First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "EligibilityRule" - "DecisionProtocol" - "DecisionRecord" - "ImpactTrack" ``` ## 7.6.6 First-pass allowed work CONSUL MAY inspire: * eligibility rules; * proposal thresholds; * public voting windows; * result eligibility notes; * admin role gating; * impact follow-up. ## 7.6.7 First-pass forbidden work CONSUL MUST NOT cause: * importing CONSUL code; * replacing current authentication; * adding full census infrastructure in first pass; * replacing EkoH cohort context; * bypassing Smart Vote readings; * adding separate CONSUL routes. ## 7.6.8 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- # 7.7 DemocracyOS ## 7.7.1 Status ```yaml SOURCE: "DemocracyOS" FIRST_PASS_STATUS: "in_scope" STRATEGY: "native_mimic" PRIORITY: "P2" PRIMARY_ROUTE_SCOPE: "/ethikos/decide/* + /ethikos/deliberate/*" PRIMARY_OWNER: "Korum + ethiKos decision layer" ``` ## 7.7.2 Retained pattern DemocracyOS is retained as inspiration for: * proposal-centric policy discussion; * structured public debate around proposals; * clear voting/discussion relationship; * public agenda-style issue pages; * admin/staff controls; * visibility and participation rules. ## 7.7.3 ethiKos mapping | DemocracyOS concept | ethiKos Kintsugi mapping | | ---------------------- | -------------------------------------------------- | | Topic / law / proposal | `DecisionRecord` or `EthikosTopic` depending stage | | Discussion | `EthikosArgument` tree | | Vote | `BallotEvent` / Smart Vote-compatible event | | Result | `ReadingResult` | | Admin/staff | `/ethikos/admin/roles` | | Visibility | `DiscussionVisibilitySetting` | ## 7.7.4 Route targets ```yaml ROUTE_TARGETS: PRIMARY: - "/ethikos/decide/public" - "/ethikos/deliberate/[topic]" SECONDARY: - "/ethikos/admin/roles" - "/ethikos/decide/results" - "/ethikos/learn/guides" ``` ## 7.7.5 Model impact First-pass proposed models: ```yaml FIRST_PASS_MODEL_CANDIDATES: - "DecisionRecord" - "DecisionProtocol" - "DiscussionVisibilitySetting" ``` ## 7.7.6 First-pass allowed work DemocracyOS MAY inspire: * proposal pages that combine summary, arguments, and vote state; * clear discussion-to-decision flow; * public visibility states; * proposal status labels. ## 7.7.7 First-pass forbidden work DemocracyOS MUST NOT cause: * importing Node/Mongo architecture; * replacing Django/DRF; * replacing PostgreSQL; * creating a DemocracyOS subapp; * collapsing ethiKos topics and decisions into one ambiguous object; * bypassing Smart Vote readings. ## 7.7.8 Kintsugi classification ```yaml CLASSIFICATION: MIMIC: true ANNEX: false IMPORT_CODE: false CREATE_APP: false ``` --- ## 8. Cross-source synthesis by route family ## 8.1 `/ethikos/deliberate/*` Primary source references: ```yaml DELIBERATE_SOURCES: PRIMARY: - "Kialo-style argument mapping" SECONDARY: - "Consider.it" - "DemocracyOS" ``` Main retained patterns: * argument graph; * claim cards; * pro/con edges; * topic stance; * claim source links; * claim-level impact vote; * role-aware suggestions; * moderation; * author visibility; * vote visibility; * topic background info; * deliberation guidelines. Current core models: ```yaml CURRENT_MODELS: - "EthikosTopic" - "EthikosArgument" - "EthikosStance" - "EthikosCategory" ``` First-pass proposed support models: ```yaml PROPOSED_SUPPORT_MODELS: - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" ``` --- ## 8.2 `/ethikos/decide/*` Primary source references: ```yaml DECIDE_SOURCES: PRIMARY: - "Loomio" SECONDARY: - "CONSUL Democracy" - "DemocracyOS" - "Citizen OS" ``` Main retained patterns: * proposal lifecycle; * decision protocol; * voting window; * eligibility rule; * baseline result; * Smart Vote reading; * outcome publication; * methodology explanation. First-pass proposed support models: ```yaml PROPOSED_SUPPORT_MODELS: - "DecisionProtocol" - "DecisionRecord" - "EligibilityRule" - "LensDeclaration" - "ReadingResult" ``` --- ## 8.3 Drafting capability Primary source references: ```yaml DRAFTING_SOURCES: PRIMARY: - "Citizen OS" SECONDARY: - "Loomio" - "Decidim" ``` Main retained patterns: * draft from topic; * version history; * amendment; * rationale packet; * promotion to decision record; * auditability. First-pass proposed support models: ```yaml PROPOSED_SUPPORT_MODELS: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" ``` Route note: ```yaml ROUTE_NOTE: CURRENT_ROUTE: "No canonical /ethikos/draft/* route is fixed yet." RULE: "Do not invent /ethikos/draft/* implementation without route-plan and ADR alignment." ``` --- ## 8.4 `/ethikos/impact/*` Primary source references: ```yaml IMPACT_SOURCES: PRIMARY: - "Decidim" SECONDARY: - "CONSUL Democracy" ``` Main retained patterns: * outcome follow-up; * implementation tracking; * public accountability; * feedback loop; * status timeline. First-pass proposed support models: ```yaml PROPOSED_SUPPORT_MODELS: - "ImpactTrack" - "ImpactUpdate" ``` Important ownership rule: ```yaml IMPACT_OWNERSHIP_RULE: IMPACT_BELONGS_TO: "Konsultations + accountability handoff" IMPACT_DOES_NOT_BELONG_TO: "KeenKonnect as source of truth" ``` KeenKonnect may receive execution handoff links, but it must not own civic impact truth. --- ## 8.5 `/ethikos/admin/*` Primary source references: ```yaml ADMIN_SOURCES: PRIMARY: - "Decidim" - "CONSUL Democracy" - "Kialo-style argument mapping" ``` Main retained patterns: * audit trail; * moderation queue; * participant roles; * eligibility controls; * visibility settings; * permission-gated operations; * suggested claim review. First-pass proposed support models: ```yaml PROPOSED_SUPPORT_MODELS: - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" - "EligibilityRule" - "ModerationAction" - "AuditEvent" ``` --- ## 8.6 `/ethikos/pulse/*` Primary source references: ```yaml PULSE_SOURCES: PRIMARY: - "Decidim" - "Consider.it" SECONDARY: - "Kialo-style argument mapping" ``` Main retained patterns: * participation health; * deliberation quality; * argument balance; * live participation state; * trend detection; * unresolved conflict signals. First-pass model impact should be minimal. Prefer derived metrics from existing and newly added records. --- ## 8.7 `/ethikos/trust/*` Primary source references: ```yaml TRUST_SOURCES: PRIMARY: - "EkoH internal docs" SECONDARY: - "CONSUL Democracy" - "Decidim" ``` Main retained patterns: * expertise profile; * badges; * credentials; * cohort context; * eligibility explanation; * public/private trust display controls. EkoH remains context. It is not a voting engine. --- ## 8.8 `/ethikos/learn/*` Primary source references: ```yaml LEARN_SOURCES: PRIMARY: - "Internal Kintsugi docs" - "Kialo-style guidance" - "Smart Vote/EkoH methodology" ``` Main retained patterns: * glossary; * methodology; * public explanation; * voting explanation; * roles explanation; * deliberation guidance; * Kintsugi changelog. --- ## 8.9 `/ethikos/insights` Primary source references: ```yaml INSIGHTS_SOURCES: PRIMARY: - "Smart Vote" - "EkoH" - "Decidim accountability patterns" - "Kialo perspectives" ``` Main retained patterns: * baseline vs reading comparison; * cohort views; * argument graph summaries; * impact visibility; * decision result interpretation. --- ## 9. Cross-source synthesis by pipeline stage | Pipeline stage | Owner | Main sources | Main retained patterns | | ---------------------------------- | -------------------------- | ------------------------------------- | ------------------------------------------------------ | | Stage 0 — Intake | Konsultations | Decidim, CONSUL | issue intake, eligibility, categorization | | Stage 1 — Discovery / Consultation | Konsultations | Consider.it, Decidim, CONSUL | options, constraints, participation landscape | | Stage 2 — Deliberation | Korum | Kialo-style, Consider.it, DemocracyOS | argument graph, claims, sources, reason capture | | Stage 3 — Drafting | ethiKos bounded capability | Citizen OS, Loomio | draft, amendment, versioning, rationale | | Stage 4 — Decision | Smart Vote | Loomio, CONSUL, DemocracyOS | protocol, ballots, results, readings | | Stage 5 — Accountability | Konsultations + handoff | Decidim, CONSUL | impact track, outcome follow-up, public accountability | --- ## 10. First-pass model impact matrix | Model / object | Source inspiration | Owner | First-pass status | Notes | | ----------------------------- | ------------------------------- | --------------------- | ----------------- | --------------------------------------------- | | `EthikosTopic` | Kialo, DemocracyOS, Consider.it | Korum | Existing | Preserve | | `EthikosArgument` | Kialo, Consider.it, DemocracyOS | Korum | Existing | Preserve; do not rename to Claim | | `EthikosStance` | Consider.it, internal ethiKos | Korum | Existing | Topic-level `-3..+3` only | | `EthikosCategory` | Internal ethiKos | Korum | Existing | Preserve | | `ArgumentSource` | Kialo | Korum | Candidate | Source/citation attached to argument | | `ArgumentImpactVote` | Kialo | Korum | Candidate | Claim-level impact `0..4` | | `ArgumentSuggestion` | Kialo | Korum/Admin | Candidate | Role-aware suggested claims | | `DiscussionParticipantRole` | Kialo, Decidim | Korum/Admin | Candidate | owner/admin/editor/writer/suggester/viewer | | `DiscussionVisibilitySetting` | Kialo, DemocracyOS | Korum/Admin | Candidate | anonymity, author visibility, vote visibility | | `DecisionProtocol` | Loomio, CONSUL | Smart Vote / ethiKos | Candidate | Decision method and thresholds | | `DecisionRecord` | Loomio, DemocracyOS, CONSUL | Smart Vote / ethiKos | Candidate | Decision lifecycle and outcome | | `EligibilityRule` | CONSUL, Decidim | Konsultations / Admin | Candidate | Participation eligibility | | `LensDeclaration` | Smart Vote / EkoH | Smart Vote | Candidate | Declared reading lens | | `ReadingResult` | Smart Vote / EkoH | Smart Vote | Candidate | Derived result publication | | `Draft` | Citizen OS | ethiKos drafting | Candidate | Decision-ready text | | `DraftVersion` | Citizen OS | ethiKos drafting | Candidate | Version history | | `Amendment` | Citizen OS | ethiKos drafting | Candidate | Proposed text change | | `RationalePacket` | Citizen OS, Kialo | ethiKos drafting | Candidate | Why text says what it says | | `ImpactTrack` | Decidim, CONSUL | Konsultations | Candidate | Accountability tracking | | `ExternalArtifact` | Annex rulebook | Boundary layer | Candidate | Future annex artifact | | `ProjectionMapping` | Annex rulebook | Boundary layer | Candidate | Future projection mapping | --- ## 11. First-pass UI impact matrix | UI surface | Main source | Route | First-pass status | | --------------------------------- | ------------------- | ---------------------------------------------------------- | -------------------------- | | Argument tree | Kialo | `/ethikos/deliberate/[topic]` | In scope | | Argument node card | Kialo, Consider.it | `/ethikos/deliberate/[topic]` | In scope | | Source panel | Kialo | `/ethikos/deliberate/[topic]` | In scope | | Suggested claims panel | Kialo | `/ethikos/deliberate/[topic]`, `/ethikos/admin/moderation` | In scope | | Basic topic info/background panel | Kialo | `/ethikos/deliberate/[topic]` | In scope | | Guided voting drawer | Kialo | `/ethikos/deliberate/[topic]` | Optional first pass | | Minimap tree mode | Kialo | `/ethikos/deliberate/[topic]` | Optional first pass | | Sunburst minimap | Kialo | `/ethikos/deliberate/[topic]` | Deferred | | Proposal lifecycle cards | Loomio, DemocracyOS | `/ethikos/decide/*` | In scope | | Decision result panel | Loomio, Smart Vote | `/ethikos/decide/results` | In scope | | Draft/version panel | Citizen OS | Decide/Drafting surface | In scope if model approved | | Impact timeline | Decidim, CONSUL | `/ethikos/impact/tracker` | In scope | | Admin audit table | Decidim | `/ethikos/admin/audit` | In scope | | Eligibility settings | CONSUL | `/ethikos/admin/roles`, `/ethikos/decide/methodology` | Optional first pass | | Reading comparison dashboard | Smart Vote/EkoH | `/ethikos/insights` | In scope | --- ## 12. Explicit no-go matrix | Source | No-go item | Reason | | -------------- | ------------------------------------- | ------------------------------------------ | | Consider.it | Import codebase | First pass is native mimic only | | Kialo | Create `konnaxion.kialo` | Kialo-style belongs inside Korum | | Kialo | Rename `EthikosArgument` to `Claim` | Existing model must remain stable | | Kialo | Treat claim impact votes as stances | Different semantic level | | Loomio | Replace auth/session model | Out of scope | | Loomio | Replace Smart Vote | Smart Vote owns readings | | Citizen OS | Add Etherpad annex now | Annex not allowed first pass | | Citizen OS | Store draft versions as arguments | Drafting is separate bounded capability | | Decidim | Rebuild Decidim component framework | Too large and incompatible with first pass | | Decidim | Switch backend style to Rails/GraphQL | Current backend is Django/DRF | | CONSUL | Add full census infrastructure now | Too broad for first pass | | CONSUL | Replace EkoH cohort context | EkoH owns cohort/expertise context | | DemocracyOS | Import Node/Mongo architecture | Current stack remains Django/PostgreSQL | | DemocracyOS | Create separate DemocracyOS routes | Native mimic inside `/ethikos/*` | | Polis | Add clustering models now | Deferred | | LiquidFeedback | Add delegation/liquid voting now | Deferred | | OpenSlides | Add meeting/parliament workflow now | Deferred | --- ## 13. Integration readiness scale Use this readiness scale in later docs and backlog planning. ```yaml INTEGRATION_READINESS: R0_REJECTED: meaning: "Not allowed or explicitly out of scope." R1_REFERENCE_ONLY: meaning: "Useful for public credit or future research, but not first pass." R2_CONCEPT_MIMIC: meaning: "Use as product inspiration only." R3_CONTRACT_MIMIC: meaning: "Define objects, payloads, routes, and rules around this pattern." R4_IMPLEMENTATION_CANDIDATE: meaning: "Ready for later backlog after docs and code inspection." R5_ANNEX_CANDIDATE: meaning: "Possible future sidecar, requires isolation, adapter, license clearance, and ADR." ``` First-pass source readiness: | Source | Readiness | | ---------------------------- | ----------------- | | Kialo-style argument mapping | R3 | | Loomio | R3 | | Citizen OS | R3 | | Decidim | R3 | | CONSUL Democracy | R2/R3 | | DemocracyOS | R2/R3 | | Consider.it | R2 | | Polis | R1 | | LiquidFeedback | R1 | | All Our Ideas | R1 | | Your Priorities | R1 | | OpenSlides | R1/R5 future only | --- ## 14. Anti-drift rules The following rules are binding. ```yaml ANTI_DRIFT_RULES: - "First-pass sources are fixed by this document." - "Deferred sources MUST NOT produce first-pass tasks." - "All first-pass source patterns are native mimic only." - "No external source may write directly to Korum or Konsultations core tables." - "No first-pass source may create a new top-level frontend app." - "No first-pass source may create a new backend app unless an ADR explicitly allows it later." - "Kialo-style features extend Korum under /ethikos/deliberate/*." - "Loomio-style features inform /ethikos/decide/*." - "Citizen OS-style features inform bounded drafting capability." - "Decidim-style features inform process, admin, and accountability." - "CONSUL-style features inform eligibility, thresholds, and governance." - "DemocracyOS-style features inform proposal-centric discussion." - "Smart Vote publishes readings only." - "EkoH provides expertise/ethics/cohort context only." - "Impact truth belongs to Konsultations/accountability, not KeenKonnect." - "Do not expand /api/home/*." ``` --- ## 15. Related documents This document should be read with: ```text 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 16. Final binding statement ```yaml FINAL_BINDING_STATEMENT: FIRST_PASS_IS: - "Native mimic of selected civic-tech patterns" - "Route-preserving" - "Ownership-preserving" - "Documentation-first" - "Contract-driven" FIRST_PASS_IS_NOT: - "Full OSS merge" - "Annex integration" - "New Kialo module" - "New Kintsugi app" - "Route rewrite" - "Backend ownership collapse" - "Implementation backlog" MOST_IMPORTANT_SOURCE_PATTERN: DELIBERATION: "Kialo-style argument mapping" DECISION: "Loomio-style proposal lifecycle" DRAFTING: "Citizen OS-style drafting/versioning" ACCOUNTABILITY: "Decidim-style process and accountability" ELIGIBILITY: "CONSUL-style governance" PROPOSAL_DISCUSSION: "DemocracyOS-style proposal-centric debate" REASON_CAPTURE: "Consider.it-style pro/con reason clarity" PRIMARY_DRIFT_CONTROL_RULE: "If an external source pattern conflicts with ethiKos boundaries, mimic the useful idea only and preserve ethiKos ownership, routes, and source-of-truth rules." ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/11_MIMIC_VS_ANNEX_RULEBOOK.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 90d3fe2b3c4d349720e216199bb5369fa941bdfa3750d38e6b9277ff0cf7b1f1 CONTENT_BYTES: 27995 ================================================================================================ # 11 — Mimic vs Annex Rulebook **File:** `11_MIMIC_VS_ANNEX_RULEBOOK.md` **Pack:** `ethiKos Kintsugi Update Documentation Pack` **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Status:** Draft for execution alignment **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Primary module:** `ethiKos` **Update name:** `Kintsugi` --- ## 1. Purpose This document defines the rules for deciding whether an external civic technology pattern should be: 1. **Mimicked** natively inside ethiKos; 2. **Annexed** later as an isolated sidecar or adapter-based integration; 3. **Deferred** entirely; 4. **Rejected** for Kintsugi purposes. The Kintsugi Upgrade uses external civic technology as inspiration, not as a reason to merge foreign architectures into Konnaxion. This rulebook exists to prevent: - full OSS merge drift; - duplicate truth systems; - accidental route-family expansion; - foreign tool capture of Korum or Konsultations tables; - Smart Vote/EkoH boundary confusion; - speculative integration work before documentation contracts are stable. The rule for the first pass is: ```txt Mimic useful patterns natively. Do not annex first. Do not merge external tools. Do not let external tools own ethiKos truth. ```` --- ## 2. Scope This document applies to all external civic technology patterns considered for the ethiKos Kintsugi Upgrade, including but not limited to: * Consider.it; * Kialo-style argument mapping; * Loomio; * Citizen OS; * Decidim; * CONSUL Democracy; * DemocracyOS; * Polis; * LiquidFeedback; * All Our Ideas; * Your Priorities; * OpenSlides. It governs: * first-pass pattern selection; * mimic vs annex classification; * deferred source handling; * adapter boundaries; * route mapping; * data ownership; * audit requirements; * anti-drift rules; * AI generation behavior. It does not define: * exact model fields; * exact serializers; * final UI copy; * implementation tasks; * repository-specific code-reading results; * license conclusions beyond strategic classification. Those details belong in the companion docs listed in Section 21. --- ## 3. Canonical Variables Used ```yaml RULEBOOK: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" FIRST_PASS_STRATEGY: "partial_native_mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false ROUTE_POLICY: PRIMARY_ROUTE_SURFACE: "/ethikos/*" CREATE_NEW_TOP_LEVEL_ROUTE_FAMILY: false CREATE_KIALO_ROUTE_FAMILY: false CREATE_KINTSUGI_APP_ROUTE: false OWNERSHIP: KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument graph" - "debate moderation" KONSULTATIONS_OWNS: - "intake" - "consultations" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false ANNEX_REQUIRES_ADAPTERS: true ANNEX_REQUIRES_NO_DUAL_TRUTH: true ANNEX_BOUNDARY_OBJECTS: - "ExternalArtifact" - "ProjectionMapping" ``` --- ## 4. Core Definitions ## 4.1 Mimic **Mimic** means native reimplementation of a useful product, workflow, or data pattern inside Konnaxion. A mimicked pattern: * is implemented in the existing Konnaxion stack; * uses existing ethiKos route families; * writes canonical records through ethiKos-owned services; * preserves ethiKos data ownership; * avoids importing foreign app architecture; * avoids direct dependency on the source project; * credits the inspiration without becoming a clone. Mimic is the default Kintsugi strategy. ### Example Kialo-style argument mapping is mimicked by extending `/ethikos/deliberate/*` with claim-tree UX, source panels, argument impact votes, and suggested claims. It does not create `/kialo/*`, does not import Kialo code, and does not rename `EthikosArgument` to `Claim`. --- ## 4.2 Annex **Annex** means optional sidecar integration through a controlled adapter boundary. An annexed tool: * remains operationally separate; * is replaceable; * is isolated from core ethiKos tables; * never writes directly to Korum or Konsultations records; * exposes artifacts that ethiKos may ingest, project, or reference; * is connected through `ExternalArtifact` and `ProjectionMapping`; * does not become the canonical source of ethiKos truth. Annex is not allowed in the first Kintsugi pass. Annex may be considered later only after documentation, code reading, licensing review, and ADR approval. --- ## 4.3 Merge **Merge** means importing an external tool’s code, schema, architecture, workflow, or app surface into the Konnaxion core. Merge is forbidden for the Kintsugi first pass. Examples of forbidden merge behavior: ```txt Importing Loomio as the decision engine. Embedding Decidim as the ethiKos process layer. Creating a full Citizen OS stack inside Konnaxion. Replacing EthikosArgument with Kialo Claim models. Letting DemocracyOS own proposal truth. Letting OpenSlides own ethiKos decisions. ``` --- ## 4.4 Deferred **Deferred** means the source is acknowledged but not used for first-pass implementation. Deferred sources may be: * credited publicly; * kept in Kompendio as references; * revisited after the Kintsugi contracts are stable; * reviewed in future code-reading work. Deferred sources MUST NOT create first-pass models, routes, services, migrations, or backlog tasks. --- ## 4.5 Rejected **Rejected** means the source or pattern is not suitable for Kintsugi. Reasons may include: * license conflict; * architecture capture risk; * duplicate truth risk; * security risk; * incompatible governance model; * unnecessary complexity; * route or ownership conflict; * mismatch with ethiKos purpose. Rejected sources should be documented only if they are likely to be proposed again. --- ## 5. First-Pass Classification The first Kintsugi pass is mimic-only. | Source | First-pass status | Rule | | ---------------------------- | ----------------: | ------------------------------------------------------------ | | Consider.it | Mimic | Reason capture and pro/con deliberation compression | | Kialo-style argument mapping | Mimic | Structured argument tree, sources, impact votes, permissions | | Loomio | Mimic | Proposal lifecycle and decision protocol patterns | | Citizen OS | Mimic | Drafting, amendments, versioning, topic phases | | Decidim | Mimic | Process architecture, accountability, admin patterns | | CONSUL Democracy | Mimic | Eligibility, thresholds, public proposal mechanics | | DemocracyOS | Mimic | Proposal-centric policy debate UX | No first-pass source is annexed. No first-pass source is merged. --- ## 6. Deferred Classification The following sources are explicitly not first pass. | Source | Status | Rule | | --------------- | -------------------------------: | ------------------------------------------------ | | Polis | Deferred / public credit only | Do not implement consensus mapping now | | LiquidFeedback | Deferred / public credit only | Do not implement delegation/liquid democracy now | | All Our Ideas | Deferred | Do not implement pairwise ranking now | | Your Priorities | Deferred | Do not implement idea prioritization sidecar now | | OpenSlides | Deferred / possible future annex | Do not implement assembly/parliament mode now | These tools may appear in public credits or long-term architecture notes, but they MUST NOT drive first-pass implementation. --- ## 7. Decision Rule Summary Use this decision tree before adopting any external pattern. ```txt 1. Is the feature needed for the first-pass Kintsugi scope? - No → Defer. - Yes → Continue. 2. Can the pattern be implemented natively inside existing ethiKos routes? - Yes → Mimic. - No → Continue. 3. Is the external tool modular, isolated, replaceable, and license-compatible? - No → Defer or reject. - Yes → Continue. 4. Would annexing it create duplicate truth or direct writes to core ethiKos tables? - Yes → Reject or redesign as mimic. - No → Future annex candidate. 5. Is this first pass? - Yes → Mimic or defer only. - No → Annex may be considered with ADR approval. ``` --- ## 8. Mimic Criteria A source SHOULD be mimicked when one or more of the following are true: * the idea is valuable but the codebase is too large; * the source stack is incompatible with Konnaxion; * the license creates friction or risk; * the tool is effectively a full civic operating system; * the UX pattern is useful but the data model is not; * Konnaxion needs a unified ethiKos experience; * canonical records must remain native ethiKos truth; * the source would otherwise dominate the product; * the pattern is easy to express through current routes and models; * the pattern improves legitimacy without adding infrastructure burden. A mimic implementation MUST: * live under `/ethikos/*`; * use Konnaxion frontend conventions; * use the existing services layer; * use Django/DRF contracts on the backend; * preserve current core models unless a non-breaking extension is documented; * map foreign concepts to canonical objects; * cite the source as inspiration where appropriate; * avoid imported code unless separately approved. --- ## 9. Annex Criteria A source MAY be considered for annex later when all conditions below are true: ```yaml ANNEX_REQUIREMENTS: FEATURE_IS_MODULAR: true FEATURE_IS_OPTIONAL: true FEATURE_IS_REPLACEABLE: true LICENSE_REVIEW_COMPLETE: true SECURITY_REVIEW_COMPLETE: true ADAPTER_BOUNDARY_DEFINED: true NO_CORE_TABLE_WRITES: true NO_DUAL_TRUTH: true NO_ROUTE_FAMILY_CAPTURE: true NO_PRODUCT_DOMINANCE: true ADR_APPROVED: true ``` An annex candidate MUST use: ```txt ExternalArtifact ProjectionMapping Adapter service Explicit provenance Optional projection through ethiKos services ``` An annex candidate MUST NOT: * write directly to Korum tables; * write directly to Konsultations tables; * mutate Smart Vote readings; * mutate EkoH snapshots; * become the baseline result authority; * require ethiKos users to leave the core product flow; * bypass permissions, audit, or identity rules. --- ## 10. Merge Rejection Criteria A proposal MUST be rejected if it requires any of the following: * replacing existing ethiKos route families; * replacing existing Korum or Konsultations ownership; * importing a full external civic application into core; * letting an external tool own baseline facts; * letting an external tool write directly into core tables; * creating a second decision engine; * creating a second shell or navigation system; * duplicating user identity or permission systems; * forcing Konnaxion to adopt the external tool’s stack; * hiding raw baseline results behind a derived interpretation; * making Smart Vote mutate upstream facts; * making EkoH the voting engine. --- ## 11. Pattern Mapping Rules Every external source must be reduced to patterns before implementation. A pattern entry MUST specify: ```yaml PATTERN_ENTRY: SOURCE_NAME: "" SOURCE_STATUS: "mimic | annex_candidate | deferred | rejected" PATTERN_NAME: "" ETHIKOS_ROUTE_TARGET: "" CANONICAL_OBJECT_TARGET: "" OWNER_LAYER: "Korum | Konsultations | Smart Vote | EkoH | Drafting" DATA_IMPACT: "none | new field | new table | adapter artifact" RISK_LEVEL: "low | medium | high" FIRST_PASS_ALLOWED: true_or_false NON_GOALS: - "" ``` A pattern entry MUST NOT say only: ```txt Use Loomio. Use Decidim. Integrate Kialo. Add Polis. ``` It MUST say: ```txt Mimic Loomio-style proposal lifecycle under /ethikos/decide/* using native DecisionRecord objects. ``` --- ## 12. Route Mapping Rules All first-pass patterns MUST map to existing ethiKos route families. | Route family | Allowed pattern types | | ----------------------- | ----------------------------------------------------------------------------- | | `/ethikos/deliberate/*` | argument mapping, pro/con reasoning, sources, suggested claims, moderation | | `/ethikos/decide/*` | proposal lifecycle, decision protocols, ballots, results, Smart Vote readings | | `/ethikos/impact/*` | accountability, outcomes, implementation tracking, feedback | | `/ethikos/pulse/*` | participation health, live signals, trends, process visibility | | `/ethikos/trust/*` | expertise context, credentials, EkoH-facing trust markers | | `/ethikos/admin/*` | roles, audit, moderation, eligibility, visibility controls | | `/ethikos/learn/*` | glossary, guides, methodology, public explanation | | `/ethikos/insights` | analytics, reading comparison, interpretation | Forbidden route drift: ```txt /kialo/* /loomio/* /decidim/* /consul/* /citizen-os/* /democracyos/* /kintsugi-app/* /deliberation/* ``` Conceptual or public documentation pages may refer to Kintsugi, Korum, or Konsultations, but implementation work must respect the actual `/ethikos/*` surface. --- ## 13. Ownership Rules The following ownership rules are binding. ## 13.1 Korum Korum owns: * debate topics; * stance events; * arguments; * argument graph; * claim-like UX; * sources attached to arguments; * argument impact votes; * suggested claims; * debate moderation. Korum MAY mimic: * Kialo-style argument mapping; * Consider.it-style pro/con reason capture; * DemocracyOS-style proposal discussion. Korum MUST NOT: * own Smart Vote readings; * own consultation ballot truth; * embed drafting tables directly into argument tables; * let Kialo become a separate backend app. --- ## 13.2 Konsultations Konsultations owns: * intake; * consultation framing; * ballots; * result snapshots; * citizen suggestions; * impact tracking. Konsultations MAY mimic: * Citizen OS topic phases; * CONSUL proposal mechanics; * Decidim process phases; * DemocracyOS policy proposal framing. Konsultations MUST NOT: * overwrite Korum arguments; * mutate Smart Vote readings; * make KeenKonnect the civic impact source of truth; * use external tools as baseline ballot authority. --- ## 13.3 Smart Vote Smart Vote owns: * baseline and declared result publication; * derived readings; * lens declarations; * aggregations; * result payloads. Smart Vote MAY use EkoH snapshots as context. Smart Vote MUST NOT: * mutate Korum records; * mutate Konsultations records; * replace source events; * hide the baseline reading; * treat Kialo impact votes as ballots. --- ## 13.4 EkoH EkoH owns: * expertise context; * ethics context; * cohort eligibility; * snapshot and audit context. EkoH MAY inform Smart Vote readings. EkoH MUST NOT: * become the voting engine; * mutate votes; * override baseline results; * write directly into Korum or Konsultations truth. --- ## 14. Adapter Boundary Rules Any future annex must use explicit adapter objects. ## 14.1 `ExternalArtifact` `ExternalArtifact` stores append-only imported or linked external payloads. It SHOULD include: ```yaml ExternalArtifact: source_system: string source_version: string external_id: string artifact_type: string raw_payload: json provenance: json captured_at: datetime captured_by: user_or_service checksum: string trust_status: enum ``` It MUST NOT become canonical ethiKos truth by itself. --- ## 14.2 `ProjectionMapping` `ProjectionMapping` maps external IDs to internal canonical IDs. It SHOULD include: ```yaml ProjectionMapping: source_system: string external_id: string internal_object_type: string internal_object_id: string mapping_confidence: enum mapping_status: enum created_at: datetime reviewed_by: user_or_service ``` Projection into canonical objects MUST happen through ethiKos services, not direct database writes. --- ## 15. First-Pass Source Rules ## 15.1 Consider.it Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * reason capture; * pro/con positioning; * deliberation compression; * strength/clarity signals; * comparison of reasons. Target: ```txt /ethikos/deliberate/* Korum EthikosArgument ArgumentSource ArgumentImpactVote ``` Forbidden: * direct code import; * separate Consider.it route; * replacing Korum argument model. --- ## 15.2 Kialo-style Argument Mapping Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * thesis-centered discussion; * claim tree; * pro/con relation; * sources; * impact votes; * suggested claims; * roles and permissions; * anonymity settings; * minimap as future/optional; * perspectives as future/optional. Target: ```txt /ethikos/deliberate/* Korum EthikosTopic EthikosArgument ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` Forbidden: * creating `konnaxion.kialo`; * creating `/kialo/*`; * renaming `EthikosArgument` to `Claim`; * treating impact votes as topic stances; * treating impact votes as Smart Vote ballots. --- ## 15.3 Loomio Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * discussion-to-proposal transition; * sense-check patterns; * proposal lifecycle; * time-boxed decision; * outcome publication; * dissent visibility. Target: ```txt /ethikos/decide/* DecisionProtocol DecisionRecord BaselineResult ReadingResult ``` Forbidden: * direct Loomio import; * separate Loomio auth model; * replacing Smart Vote publication logic; * making Loomio the decision source of truth. --- ## 15.4 Citizen OS Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * topic phases; * collaborative drafting; * amendments; * version history; * structured discussion around text; * action handoff. Target: ```txt ethiKos drafting capability Draft DraftVersion Amendment RationalePacket ``` Forbidden: * embedding Etherpad stack in first pass; * direct Citizen OS deployment; * merging drafting tables into Korum argument tables; * replacing ethiKos routes with Citizen OS flow. --- ## 15.5 Decidim Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * process phases; * accountability; * proposals; * debates; * meetings as conceptual future reference; * admin/process configuration; * participatory component structure. Target: ```txt /ethikos/impact/* /ethikos/admin/* /ethikos/pulse/* ProcessPhase ImpactTrack AuditEvent ModerationAction ``` Forbidden: * direct Decidim import; * adopting Decidim’s full Rails architecture; * making Decidim the process source of truth; * creating a second participatory process platform beside ethiKos. --- ## 15.6 CONSUL Democracy Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * eligibility rules; * thresholds; * proposal gating; * civic administration; * public accountability patterns. Target: ```txt /ethikos/decide/* /ethikos/admin/* /ethikos/impact/* EligibilityRule DecisionProtocol ImpactTrack ``` Forbidden: * direct CONSUL import; * replacing Konnaxion auth/permissions; * making CONSUL census logic canonical without EkoH/Konnaxion alignment. --- ## 15.7 DemocracyOS Status: ```txt first_pass_mimic ``` Allowed pattern extraction: * proposal-centric policy discussion; * clause-level review patterns; * public debate around proposals; * role/visibility ideas where useful. Target: ```txt /ethikos/decide/* /ethikos/deliberate/* DecisionRecord EthikosArgument Draft ``` Forbidden: * direct DemocracyOS import; * adopting its stack; * creating a separate proposal truth system. --- ## 16. Deferred Source Rules ## 16.1 Polis Status: ```txt deferred_public_credit_only ``` Allowed now: * public inspiration credit; * future research note. Forbidden now: * implementing clustering; * implementing bridge statement engine; * implementing agree/disagree/pass at Polis scale; * adding Polis-specific models; * annexing Polis. --- ## 16.2 LiquidFeedback Status: ```txt deferred_public_credit_only ``` Allowed now: * public inspiration credit; * future governance theory reference. Forbidden now: * implementing delegation; * implementing liquid democracy vote flows; * adding delegation tables; * adding delegation UI; * making Smart Vote a delegation engine. --- ## 16.3 All Our Ideas Status: ```txt deferred ``` Forbidden now: * pairwise ranking implementation; * sidecar integration; * ranking-specific models; * first-pass prioritization engine. --- ## 16.4 Your Priorities Status: ```txt deferred ``` Forbidden now: * idea-prioritization sidecar; * standalone idea-intake route; * external prioritization data source; * first-pass annex. --- ## 16.5 OpenSlides Status: ```txt deferred_possible_future_annex ``` Allowed later: * possible assembly/parliament mode analysis. Forbidden now: * assembly mode implementation; * formal meeting governance route; * motions/elections stack; * first-pass annex. --- ## 17. Scoring Rubric Each candidate pattern SHOULD be scored before adoption. | Criterion | Score 0 | Score 1 | Score 2 | | --------------------- | ------------------------ | ------------------- | ------------------------------ | | First-pass relevance | Not relevant | Useful later | Needed now | | Route fit | Needs new route family | Partial fit | Fits existing `/ethikos/*` | | Ownership fit | Conflicts with ownership | Needs clarification | Clean owner | | Data safety | Creates duplicate truth | Needs adapter | Native canonical fit | | Stack fit | Incompatible | Adapter needed | Native implementation easy | | UX coherence | Fragments UX | Needs redesign | Strengthens ethiKos UX | | License risk | High | Unknown | Low or irrelevant due to mimic | | Implementation weight | Heavy | Medium | Light | | Auditability | Weak | Possible | Strong | | Replaceability | Hard | Medium | Easy | Interpretation: ```txt 16–20 = good mimic candidate 10–15 = document carefully; mimic only if strategic 5–9 = defer 0–4 = reject ``` Annex cannot be approved by score alone. Annex requires explicit ADR approval. --- ## 18. Required Decision Record Every future annex or major mimic must produce a short decision record. Template: ```md # Pattern Decision Record ## Source Name: ## Status Mimic / Annex candidate / Deferred / Rejected: ## Pattern retained ## Pattern rejected ## Route target ## Owner layer ## Canonical object target ## Data impact ## Adapter required? ## License concern ## Security concern ## Audit concern ## Decision ## Rationale ## Related docs ``` --- ## 19. Non-Goals This rulebook does not authorize: * implementation of all listed sources; * sidecar integration in first pass; * full code import from any civic tool; * new top-level app routes; * new backend apps for source-specific clones; * implementation of Polis clustering; * implementation of LiquidFeedback delegation; * implementation of OpenSlides parliament mode; * implementation of All Our Ideas pairwise ranking; * implementation of Your Priorities idea intake; * changes to Smart Vote ownership; * changes to EkoH ownership; * replacement of current ethiKos models. --- ## 20. Anti-Drift Rules The following rules are binding. ## 20.1 Default to Mimic If uncertain, choose: ```txt mimic_or_defer ``` Do not choose annex by default. --- ## 20.2 Existing Routes Win If a pattern can fit under `/ethikos/*`, it MUST fit under `/ethikos/*`. Do not create route families named after external tools. --- ## 20.3 Native Truth Wins If an external tool produces data that overlaps with Korum or Konsultations truth, ethiKos canonical records win. External payloads remain artifacts until explicitly projected. --- ## 20.4 Baseline Stays Visible No mimic or annex may hide baseline results behind a weighted or filtered interpretation. Smart Vote readings are additional readings, not replacements. --- ## 20.5 No Tool Capture A foreign civic tool must never become the controlling architecture for ethiKos. The source may inspire: ```txt UX pattern workflow pattern data vocabulary audit idea permission idea ``` It must not control: ```txt routes database ownership identity permissions truth source decision authority ``` --- ## 20.6 No Backlog Leakage This rulebook does not create implementation tasks. Implementation tasks must be produced later through: ```txt 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 21. Related Docs This file should be read with: | File | Relationship | | --------------------------------------------- | --------------------------------------- | | `00_KINTSUGI_START_HERE.md` | Entry point and baseline | | `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` | Strategic execution frame | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Conflict resolution and source priority | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Ownership and write rules | | `04_CANONICAL_NAMING_AND_VARIABLES.md` | Fixed names and constants | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route target mapping | | `08_DATA_MODEL_AND_MIGRATION_PLAN.md` | Non-destructive model additions | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Baseline/readings/snapshot rules | | `10_FIRST_PASS_INTEGRATION_MATRIX.md` | Source-to-pattern matrix | | `18_ADR_REGISTER.md` | Architecture decisions | | `19_OSS_CODE_READING_PLAN.md` | How to inspect source repos | | `20_AI_GENERATION_GUARDRAILS.md` | AI drift prevention | | `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` | Kialo-specific mimic contract | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Future task-generation format | --- ## 22. Final Rule The Kintsugi integration posture is: ```txt Learn from external civic tools. Credit them clearly. Mimic useful patterns natively. Protect ethiKos truth. Keep routes stable. Keep ownership explicit. Defer annexes. Never merge blindly. ``` For first-pass Kintsugi work, the only valid actions are: ```txt Mimic Defer Reject Document future annex candidate ``` The invalid action is: ```txt Merge ``` ``` Source basis: Kintsugi clean-slate scope, the existing Kintsugi master draft, the boundaries document’s Annex/Mimic and ownership rules, and the code/documentation snapshot showing the need to preserve existing ethiKos surfaces and contracts. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2} :contentReference[oaicite:3]{index=3} ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/12_CANONICAL_OBJECTS_AND_EVENTS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b11753cb48def4c1fe0dd5f02e31fbdd71918e25c9309f7fe1fcd23268e29a93 CONTENT_BYTES: 53037 ================================================================================================ # 12 — Canonical Objects and Events **Project:** Konnaxion **Module:** ethiKos **Upgrade:** Kintsugi **Document ID:** `12_CANONICAL_OBJECTS_AND_EVENTS.md` **Status:** Canonical architecture contract **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Audience:** Human maintainers, AI assistants, backend implementers, frontend implementers, documentation generators **Purpose:** Define the canonical business objects and lifecycle events used by the ethiKos Kintsugi upgrade. --- ## 1. Purpose This document defines the canonical **objects** and **events** for the ethiKos Kintsugi upgrade. It exists to prevent future drift where AI assistants, developers, or parallel documentation passes invent incompatible names, duplicate models, incorrect ownership, or conflicting event semantics. The core rule is: ```txt Objects describe civic state. Events describe civic change. Readings describe derived interpretation. ```` This document is not a database migration file and is not an implementation backlog. It is the object/event vocabulary that future data models, serializers, frontend payloads, audit logs, and product flows must respect. --- ## 2. Scope This document covers: * current canonical Ethikos objects; * proposed Kintsugi objects; * Korum deliberation objects; * Kialo-style structured argument objects; * Konsultations consultation objects; * Smart Vote reading objects; * EkoH context objects; * drafting/versioning objects; * impact/accountability objects; * external integration boundary objects; * moderation and audit objects; * canonical events emitted or recorded by those objects; * object ownership; * event ownership; * anti-drift rules. This document does **not** define: * database fields in final migration detail; * serializer JSON schemas in final detail; * frontend component structure; * implementation task sequencing; * UI copy; * full OSS integration; * annex/sidecar architecture. Those are handled by related documents. --- ## 3. Canonical Variables Used ```yaml PROJECT: PLATFORM_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" IMPLEMENTATION: STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_CORE_MODELS_STABLE: true CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" PRIMARY_ROUTE_SURFACE: ETHIKOS: "/ethikos/*" DELIBERATE: "/ethikos/deliberate/*" DECIDE: "/ethikos/decide/*" IMPACT: "/ethikos/impact/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" OWNERSHIP: KORUM: "topics, arguments, argument graph, topic-level stances, debate moderation" KONSULTATIONS: "intake, consultations, ballots, result snapshots, impact tracking" SMART_VOTE: "readings, lens declarations, derived aggregations, result publication" EKOH: "expertise context, ethics context, cohort eligibility, snapshot context" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false READINGS_ARE_DERIVED: true KIALO: STRATEGY: "native mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CLAIM_MAPPING: "Claim -> EthikosArgument" DISCUSSION_MAPPING: "Discussion -> EthikosTopic" IMPACT_VOTE_IS_TOPIC_STANCE: false ``` --- ## 4. Object Classification Objects in this document are classified into four implementation states. | State | Meaning | | --------------------- | -------------------------------------------------------------------------------------------------------------- | | `existing_core` | Already exists in the current Ethikos backend and must not be renamed or broken. | | `first_pass_addition` | Proposed for the Kintsugi first-pass native mimic upgrade. | | `contract_only` | Canonical concept that may be represented through existing models or derived payloads before becoming a table. | | `deferred` | Valid future object, but not required for the first-pass upgrade. | --- ## 5. Ownership Model Every canonical object must have exactly one primary owner. | Owner | Owns | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `Korum` | Structured debates, topics as deliberation containers, arguments, argument graph, topic stances, moderation on debate artifacts. | | `Konsultations` | Intake, consultations, citizen suggestions, ballots, result snapshots, impact tracking. | | `Smart Vote` | Derived readings, declared lenses, result interpretation, publication of computed views. | | `EkoH` | Expertise context, ethics context, eligibility context, cohort/snapshot metadata. | | `Drafting` | Drafts, draft versions, amendments, rationale packets. | | `Admin/Audit` | Moderation actions, audit events, role changes, governance traceability. | | `External Boundary` | Imported/annexed artifacts, projection mappings, provenance records. | Ownership defines write authority. It does not prevent other modules from reading or displaying the object. --- ## 6. Current Core Objects The following objects already exist and are canonical. ### 6.1 `EthikosCategory` ```yaml OBJECT: "EthikosCategory" STATUS: "existing_core" OWNER: "Korum" CURRENT_MODEL: "EthikosCategory" ROUTE_SCOPE: - "/ethikos/deliberate/*" - "/ethikos/decide/*" API_SCOPE: - "/api/ethikos/categories/" MEANING: "Topic grouping used to organize Ethikos topics." MUST_NOT: - "rename to CategoryGroup" - "replace with external taxonomy in first pass" ``` ### 6.2 `EthikosTopic` ```yaml OBJECT: "EthikosTopic" STATUS: "existing_core" OWNER: "Korum" CURRENT_MODEL: "EthikosTopic" ROUTE_SCOPE: - "/ethikos/deliberate/*" - "/ethikos/decide/*" API_SCOPE: - "/api/ethikos/topics/" MEANING: "Main debate, deliberation, or consultation prompt container." KIALO_MAPPING: - "Kialo Discussion -> EthikosTopic" - "Kialo Thesis -> EthikosTopic title/description or future thesis field" MUST_NOT: - "rename to KialoDiscussion" - "replace with imported discussion model" - "move source ownership to Smart Vote" ``` ### 6.3 `EthikosStance` ```yaml OBJECT: "EthikosStance" STATUS: "existing_core" OWNER: "Korum" CURRENT_MODEL: "EthikosStance" ROUTE_SCOPE: - "/ethikos/deliberate/*" - "/ethikos/decide/*" API_SCOPE: - "/api/ethikos/stances/" MEANING: "Per-user topic-level stance." VALUE_RANGE: "-3..+3" LEVEL: "topic" MUST_NOT: - "treat as Kialo impact vote" - "treat as Smart Vote reading" - "replace with external ballot model" ``` ### 6.4 `EthikosArgument` ```yaml OBJECT: "EthikosArgument" STATUS: "existing_core" OWNER: "Korum" CURRENT_MODEL: "EthikosArgument" ROUTE_SCOPE: - "/ethikos/deliberate/*" API_SCOPE: - "/api/ethikos/arguments/" MEANING: "Threaded argument or reply attached to an Ethikos topic." KIALO_MAPPING: - "Kialo Claim -> EthikosArgument" - "Kialo Pro/Con edge -> EthikosArgument.parent + EthikosArgument.side" MUST_NOT: - "rename to Claim" - "replace with DebatePost" - "create separate Kialo claim table in first pass unless explicitly approved later" ``` --- ## 7. Canonical Object Registry This registry defines the complete canonical vocabulary for the Kintsugi upgrade. | Canonical Object | Owner | Status | Current / Proposed Representation | Primary Route Scope | | ----------------------------- | -------------------------- | --------------------: | -------------------------------------------- | ---------------------------------------------- | | `EthikosCategory` | Korum | `existing_core` | `EthikosCategory` | `/ethikos/deliberate/*`, `/ethikos/decide/*` | | `EthikosTopic` | Korum | `existing_core` | `EthikosTopic` | `/ethikos/deliberate/*`, `/ethikos/decide/*` | | `EthikosStance` | Korum | `existing_core` | `EthikosStance` | `/ethikos/deliberate/*` | | `EthikosArgument` | Korum | `existing_core` | `EthikosArgument` | `/ethikos/deliberate/*` | | `ProblemStatement` | Konsultations | `contract_only` | field/payload around topic intake | `/ethikos/decide/*` | | `IntakeSubmission` | Konsultations | `first_pass_addition` | proposed model | `/ethikos/decide/*` | | `IntakeQueue` | Konsultations | `contract_only` | queryset/status view | `/ethikos/admin/*` | | `TopicTag` | Korum | `contract_only` | may reuse category first | `/ethikos/deliberate/*` | | `Option` | Konsultations | `first_pass_addition` | proposed model or JSON payload | `/ethikos/decide/*` | | `OptionSet` | Konsultations | `contract_only` | grouped options | `/ethikos/decide/*` | | `Constraint` | Konsultations | `first_pass_addition` | proposed model or JSON payload | `/ethikos/decide/*` | | `ConstraintSet` | Konsultations | `contract_only` | grouped constraints | `/ethikos/decide/*` | | `ArgumentGraph` | Korum | `contract_only` | derived from `EthikosArgument.parent + side` | `/ethikos/deliberate/[topic]` | | `ArgumentEdge` | Korum | `contract_only` | parent/child relation + side | `/ethikos/deliberate/[topic]` | | `ArgumentSource` | Korum | `first_pass_addition` | proposed model | `/ethikos/deliberate/[topic]` | | `ArgumentImpactVote` | Korum | `first_pass_addition` | proposed model | `/ethikos/deliberate/[topic]` | | `ArgumentSuggestion` | Korum | `first_pass_addition` | proposed model | `/ethikos/deliberate/[topic]` | | `ArgumentBookmark` | Korum | `deferred` | proposed model | `/ethikos/deliberate/[topic]` | | `ArgumentLink` | Korum | `deferred` | proposed model | `/ethikos/deliberate/[topic]` | | `BallotEvent` | Konsultations | `first_pass_addition` | proposed model or event table | `/ethikos/decide/*` | | `DecisionProtocol` | Konsultations / Smart Vote | `first_pass_addition` | proposed model | `/ethikos/decide/*` | | `DecisionRecord` | Konsultations / Smart Vote | `first_pass_addition` | proposed model | `/ethikos/decide/results` | | `Draft` | Drafting | `first_pass_addition` | proposed model | `/ethikos/decide/*` | | `DraftVersion` | Drafting | `first_pass_addition` | proposed model | `/ethikos/decide/*` | | `Amendment` | Drafting | `first_pass_addition` | proposed model | `/ethikos/decide/*` | | `RationalePacket` | Drafting | `first_pass_addition` | proposed model or JSON artifact | `/ethikos/decide/*` | | `BaselineResult` | Smart Vote | `contract_only` | derived from source events | `/ethikos/decide/results` | | `LensDeclaration` | Smart Vote | `first_pass_addition` | proposed model | `/ethikos/decide/results`, `/ethikos/insights` | | `ReadingResult` | Smart Vote | `first_pass_addition` | proposed model | `/ethikos/decide/results`, `/ethikos/insights` | | `SnapshotRef` | EkoH | `contract_only` | reference to EkoH snapshot/context | `/ethikos/trust/*`, `/ethikos/insights` | | `EligibilityRule` | EkoH / Konsultations | `first_pass_addition` | proposed model | `/ethikos/admin/roles` | | `CohortContext` | EkoH | `contract_only` | snapshot/ref payload | `/ethikos/trust/*` | | `ImpactTrack` | Konsultations | `first_pass_addition` | proposed model | `/ethikos/impact/tracker` | | `ImpactUpdate` | Konsultations | `first_pass_addition` | proposed model | `/ethikos/impact/*` | | `ExternalArtifact` | External Boundary | `first_pass_addition` | proposed append-only model | admin/backoffice | | `ProjectionMapping` | External Boundary | `first_pass_addition` | proposed mapping model | admin/backoffice | | `ModerationAction` | Admin/Audit | `first_pass_addition` | proposed model or log entry | `/ethikos/admin/moderation` | | `AuditEvent` | Admin/Audit | `first_pass_addition` | proposed model or log entry | `/ethikos/admin/audit` | | `DiscussionParticipantRole` | Korum/Admin | `first_pass_addition` | proposed model | `/ethikos/admin/roles` | | `DiscussionVisibilitySetting` | Korum/Admin | `first_pass_addition` | proposed model or topic settings | `/ethikos/deliberate/*` | | `DiscussionPerspective` | Korum / Smart Vote | `deferred` | proposed model | `/ethikos/insights` | | `DiscussionTemplate` | Korum | `deferred` | proposed model | `/ethikos/deliberate/*` | | `DiscussionGroup` | Korum | `deferred` | proposed model | `/ethikos/deliberate/*` | | `DiscussionExport` | Korum | `deferred` | export artifact | `/ethikos/deliberate/*` | --- ## 8. Object Families ### 8.1 Korum Objects Korum objects describe structured deliberation. ```yaml KORUM_OBJECTS: existing_core: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" first_pass_addition: - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" - "ModerationAction" contract_only: - "ArgumentGraph" - "ArgumentEdge" deferred: - "ArgumentBookmark" - "ArgumentLink" - "DiscussionPerspective" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionExport" ``` Korum owns topic-level deliberation facts. Korum does not own Smart Vote readings, formal consultation ballots, or EkoH expertise snapshots. --- ### 8.2 Kialo-Style Structured Argument Objects Kialo-style concepts are mapped into Korum. They do not create a new Kialo module. | Kialo Concept | Canonical Kintsugi Object | Current / Proposed Representation | | ---------------- | ---------------------------------- | -------------------------------------------- | | Discussion | `EthikosTopic` | existing model | | Thesis | topic prompt / title / description | existing fields first; optional future field | | Claim | `EthikosArgument` | existing model | | Pro/Con relation | `ArgumentEdge` | parent + side | | Claim source | `ArgumentSource` | first-pass addition | | Impact vote | `ArgumentImpactVote` | first-pass addition | | Suggested claim | `ArgumentSuggestion` | first-pass addition | | Role | `DiscussionParticipantRole` | first-pass addition | | Visibility | `DiscussionVisibilitySetting` | first-pass addition | | Perspective | `DiscussionPerspective` | deferred or Smart Vote lens-adjacent | | Template | `DiscussionTemplate` | deferred | | Export | `DiscussionExport` | deferred | Critical distinction: ```txt Kialo Claim = UX/conceptual term. EthikosArgument = backend model name. Do not rename EthikosArgument to Claim. ``` --- ### 8.3 Konsultations Objects Konsultations objects describe intake, consultation, formal decision input, and public accountability. ```yaml KONSULTATIONS_OBJECTS: first_pass_addition: - "IntakeSubmission" - "Option" - "Constraint" - "BallotEvent" - "DecisionProtocol" - "DecisionRecord" - "ImpactTrack" - "ImpactUpdate" contract_only: - "ProblemStatement" - "IntakeQueue" - "OptionSet" - "ConstraintSet" ``` Konsultations owns formal consultation state and result snapshots. Konsultations does not own Smart Vote’s derived readings. --- ### 8.4 Smart Vote Objects Smart Vote objects describe derived interpretation of baseline events. ```yaml SMART_VOTE_OBJECTS: first_pass_addition: - "LensDeclaration" - "ReadingResult" contract_only: - "BaselineResult" ``` Smart Vote may compute: * baseline readings; * cohort-filtered readings; * expertise-weighted readings; * ethics-contextualized readings; * comparative readings. Smart Vote must not mutate: * `EthikosStance`; * `BallotEvent`; * `EthikosArgument`; * `EthikosTopic`. --- ### 8.5 EkoH Objects EkoH objects provide expertise, ethics, eligibility, and context. ```yaml EKOH_OBJECTS: first_pass_addition: - "EligibilityRule" contract_only: - "SnapshotRef" - "CohortContext" - "ExpertiseContext" - "EthicsContext" ``` EkoH is not a voting engine. EkoH context may be referenced by Smart Vote readings through `snapshot_ref`. --- ### 8.6 Drafting Objects Drafting objects support the civic transition from deliberation to decision-ready text. ```yaml DRAFTING_OBJECTS: first_pass_addition: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" ``` Drafting is a bounded capability under ethiKos. It must not overwrite Korum arguments or Konsultations ballots. --- ### 8.7 External Boundary Objects External boundary objects support future Annex/sidecar integrations without allowing foreign tools to write into core tables. ```yaml EXTERNAL_BOUNDARY_OBJECTS: first_pass_addition: - "ExternalArtifact" - "ProjectionMapping" ``` `ExternalArtifact` is append-only provenance. `ProjectionMapping` maps external identifiers to internal canonical identifiers. No external tool may directly mutate core Korum or Konsultations tables. --- ### 8.8 Admin and Audit Objects Admin and audit objects record governance actions. ```yaml ADMIN_AUDIT_OBJECTS: first_pass_addition: - "ModerationAction" - "AuditEvent" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" ``` Audit objects must be designed for traceability and reproducibility, not only UI display. --- ## 9. Event Classification Events are named in past tense. Event names must use the following pattern: ```txt ``` Examples: ```txt TopicCreated ArgumentSourceAttached ReadingComputed ImpactUpdated ``` Events are classified as: | Event Type | Meaning | | ---------------- | ----------------------------------------------------------- | | `source_event` | A user or system action that changes canonical civic state. | | `derived_event` | A computed event derived from source events. | | `audit_event` | A governance, moderation, or system trace event. | | `external_event` | A received or mapped event from an external artifact. | --- ## 10. Canonical Event Envelope Every canonical event SHOULD be representable using this envelope, even if implemented later as model rows, audit logs, or serialized payloads. ```yaml CanonicalEventEnvelope: event_id: "string or integer" event_type: "string" event_family: "source_event | derived_event | audit_event | external_event" owner: "Korum | Konsultations | Smart Vote | EkoH | Drafting | Admin/Audit | External Boundary" actor_id: "nullable user id" actor_display: "nullable display string" subject_type: "canonical object name" subject_id: "object id or stable ref" parent_subject_type: "nullable canonical object name" parent_subject_id: "nullable object id or stable ref" occurred_at: "ISO_8601 datetime" payload: "JSON object" source_ref: "nullable source/provenance ref" snapshot_ref: "nullable EkoH/context snapshot ref" trace_id: "nullable request/process id" ``` Minimum event fields: ```yaml MINIMUM_EVENT_FIELDS: - "event_type" - "event_family" - "owner" - "subject_type" - "subject_id" - "occurred_at" ``` --- ## 11. Korum Event Registry Korum events describe deliberation state changes. | Event | Family | Subject | Trigger | Notes | | ----------------------------- | -------------- | ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------ | | `TopicCreated` | `source_event` | `EthikosTopic` | topic created | Existing topic creation. | | `TopicUpdated` | `source_event` | `EthikosTopic` | topic edited | Must preserve auditability. | | `TopicClosed` | `source_event` | `EthikosTopic` | topic status changed to closed | May affect Decide/results views. | | `TopicArchived` | `source_event` | `EthikosTopic` | topic archived | Must not delete source facts. | | `CategoryCreated` | `source_event` | `EthikosCategory` | category created | Admin or seed action. | | `CategoryUpdated` | `source_event` | `EthikosCategory` | category edited | Maintains grouping. | | `StanceRecorded` | `source_event` | `EthikosStance` | user records stance | Topic-level `-3..+3`. | | `StanceUpdated` | `source_event` | `EthikosStance` | user updates stance | Must preserve current source state; historical audit optional but recommended. | | `ArgumentCreated` | `source_event` | `EthikosArgument` | argument posted | Existing core behavior. | | `ArgumentUpdated` | `source_event` | `EthikosArgument` | argument edited | Must preserve moderation trace. | | `ArgumentHidden` | `audit_event` | `EthikosArgument` | moderation hides argument | Does not delete argument. | | `ArgumentRestored` | `audit_event` | `EthikosArgument` | moderation restores argument | Reverses hidden state. | | `ArgumentParentAssigned` | `source_event` | `EthikosArgument` | parent relation set | Builds argument graph. | | `ArgumentSideAssigned` | `source_event` | `EthikosArgument` | side set to pro/con/neutral | Builds Kialo-style edge meaning. | | `ArgumentSourceAttached` | `source_event` | `ArgumentSource` | source added to argument | Kialo-style source transparency. | | `ArgumentSourceUpdated` | `source_event` | `ArgumentSource` | source edited | Must preserve provenance if possible. | | `ArgumentSourceRemoved` | `audit_event` | `ArgumentSource` | source removed or hidden | Prefer soft removal. | | `ArgumentImpactVoteRecorded` | `source_event` | `ArgumentImpactVote` | user votes on claim impact | Claim-level `0..4`; not a stance. | | `ArgumentImpactVoteUpdated` | `source_event` | `ArgumentImpactVote` | user updates impact vote | Claim-level only. | | `ArgumentSuggestionSubmitted` | `source_event` | `ArgumentSuggestion` | suggester submits claim | Not published until accepted. | | `ArgumentSuggestionAccepted` | `audit_event` | `ArgumentSuggestion` | editor/admin accepts suggestion | May create `EthikosArgument`. | | `ArgumentSuggestionRejected` | `audit_event` | `ArgumentSuggestion` | editor/admin rejects suggestion | Must keep moderation trace. | | `DiscussionRoleAssigned` | `audit_event` | `DiscussionParticipantRole` | role assigned | Used for Kialo-style permissions. | | `DiscussionVisibilityChanged` | `audit_event` | `DiscussionVisibilitySetting` | visibility changed | Includes anonymity/author/vote visibility. | --- ## 12. Konsultations Event Registry Konsultations events describe intake, consultation, decision input, and accountability state. | Event | Family | Subject | Trigger | Notes | | -------------------------- | -------------- | ------------------ | --------------------------------- | --------------------------------------- | | `IntakeSubmissionCreated` | `source_event` | `IntakeSubmission` | citizen/admin submits intake | May lead to topic or consultation. | | `IntakeSubmissionTriaged` | `audit_event` | `IntakeSubmission` | admin classifies intake | Links to pipeline Stage 0. | | `ProblemStatementDefined` | `source_event` | `ProblemStatement` | problem statement accepted | May be stored as field/payload. | | `OptionCreated` | `source_event` | `Option` | option added | Consultation/decision option. | | `OptionUpdated` | `source_event` | `Option` | option edited | Must preserve audit trace. | | `OptionRemoved` | `audit_event` | `Option` | option removed/hidden | Prefer soft removal. | | `ConstraintCreated` | `source_event` | `Constraint` | constraint added | Defines feasibility/context. | | `ConstraintUpdated` | `source_event` | `Constraint` | constraint edited | Must preserve trace. | | `ConsultationOpened` | `source_event` | `DecisionRecord` | consultation/decision opens | Protocol governs inputs. | | `ConsultationClosed` | `source_event` | `DecisionRecord` | consultation/decision closes | Locks or snapshots input. | | `BallotRecorded` | `source_event` | `BallotEvent` | formal ballot submitted | Not same as `EthikosStance`. | | `BallotUpdated` | `source_event` | `BallotEvent` | ballot changed if protocol allows | Must follow protocol. | | `DecisionProtocolAssigned` | `audit_event` | `DecisionProtocol` | protocol selected | Defines rules. | | `DecisionRecordCreated` | `source_event` | `DecisionRecord` | decision record created | Links source inputs and readings. | | `DecisionRecordPublished` | `source_event` | `DecisionRecord` | result published | Should include baseline + reading refs. | --- ## 13. Drafting Event Registry Drafting events describe collaborative civic text formation. | Event | Family | Subject | Trigger | Notes | | ------------------------ | -------------- | ----------------- | ------------------------------------ | ---------------------------------------------- | | `DraftCreated` | `source_event` | `Draft` | draft initialized | May originate from topic, intake, or decision. | | `DraftVersionCreated` | `source_event` | `DraftVersion` | new version saved | Version history must remain stable. | | `DraftVersionPublished` | `source_event` | `DraftVersion` | version published for review | Public or internal depending status. | | `AmendmentSubmitted` | `source_event` | `Amendment` | amendment proposed | Must link to draft/version. | | `AmendmentAccepted` | `audit_event` | `Amendment` | amendment accepted | May create new draft version. | | `AmendmentRejected` | `audit_event` | `Amendment` | amendment rejected | Must preserve rationale. | | `RationalePacketCreated` | `source_event` | `RationalePacket` | rationale attached to draft/decision | Links reasons, constraints, readings. | | `RationalePacketUpdated` | `source_event` | `RationalePacket` | rationale updated | Must preserve traceability. | --- ## 14. Smart Vote Event Registry Smart Vote events are derived or publication events. They do not mutate source facts. | Event | Family | Subject | Trigger | Notes | | ------------------------- | --------------- | ----------------- | ---------------------------------- | ----------------------------------------------------------------------- | | `LensDeclarationCreated` | `source_event` | `LensDeclaration` | lens declared | Defines computation rules. | | `LensDeclarationUpdated` | `audit_event` | `LensDeclaration` | lens updated | Should invalidate dependent readings if needed. | | `BaselineResultComputed` | `derived_event` | `BaselineResult` | raw aggregation computed | Uses source events. | | `ReadingComputed` | `derived_event` | `ReadingResult` | lens-based reading computed | Must include `reading_key`, `lens_hash`, `snapshot_ref`, `computed_at`. | | `ReadingPublished` | `derived_event` | `ReadingResult` | reading made visible | Does not replace baseline. | | `ReadingInvalidated` | `audit_event` | `ReadingResult` | source/lens/snapshot changed | Requires recomputation or warning. | | `ResultSnapshotPublished` | `derived_event` | `DecisionRecord` | decision/result snapshot published | Includes baseline and readings. | Smart Vote event invariant: ```txt Smart Vote reads source facts. Smart Vote writes derived artifacts. Smart Vote does not mutate source facts. ``` --- ## 15. EkoH Event Registry EkoH events describe expertise, ethics, cohort, and snapshot context. | Event | Family | Subject | Trigger | Notes | | -------------------------- | -------------- | ------------------ | -------------------------------------------- | -------------------------------------- | | `SnapshotReferenced` | `audit_event` | `SnapshotRef` | reading or decision references EkoH snapshot | Context only. | | `EligibilityRuleCreated` | `source_event` | `EligibilityRule` | rule created | May affect consultation participation. | | `EligibilityRuleUpdated` | `audit_event` | `EligibilityRule` | rule changed | Must be audited. | | `CohortContextAttached` | `audit_event` | `CohortContext` | cohort context linked to lens/decision | Does not cast votes. | | `ExpertiseContextAttached` | `audit_event` | `ExpertiseContext` | expertise context linked | Does not mutate ballots. | | `EthicsContextAttached` | `audit_event` | `EthicsContext` | ethics context linked | Does not mutate ballots. | EkoH event invariant: ```txt EkoH provides context. EkoH does not vote. EkoH does not own source ballot events. ``` --- ## 16. Impact Event Registry Impact events describe the public accountability loop. | Event | Family | Subject | Trigger | Notes | | ------------------------- | -------------- | ---------------------------------- | ------------------------- | ----------------------------------- | | `ImpactTrackCreated` | `source_event` | `ImpactTrack` | tracking object created | Links decision to outcome. | | `ImpactTrackUpdated` | `source_event` | `ImpactTrack` | tracker state changed | Supports `/ethikos/impact/tracker`. | | `ImpactUpdatePublished` | `source_event` | `ImpactUpdate` | public update posted | Accountability artifact. | | `ImpactFeedbackReceived` | `source_event` | `ImpactUpdate` or feedback payload | feedback submitted | Supports feedback loop. | | `OutcomeMarkedPlanned` | `source_event` | `ImpactTrack` | status set to planned | Status transition. | | `OutcomeMarkedInProgress` | `source_event` | `ImpactTrack` | status set to in progress | Status transition. | | `OutcomeMarkedBlocked` | `source_event` | `ImpactTrack` | status set to blocked | Requires reason. | | `OutcomeMarkedCompleted` | `source_event` | `ImpactTrack` | status set to completed | Requires evidence/ref. | | `OutcomeMarkedCancelled` | `source_event` | `ImpactTrack` | status set to cancelled | Requires reason. | Impact invariant: ```txt Impact belongs to Ethikos/Konsultations accountability truth. KeenKonnect may receive handoff references, but it does not own Ethikos impact truth. ``` --- ## 17. External Boundary Event Registry External boundary events support future Annex/sidecar integration while preventing direct writes into core tables. | Event | Family | Subject | Trigger | Notes | | --------------------------- | ---------------- | ------------------- | -------------------------------------- | -------------------------------------------- | | `ExternalArtifactReceived` | `external_event` | `ExternalArtifact` | external payload received | Append-only provenance. | | `ExternalArtifactValidated` | `audit_event` | `ExternalArtifact` | payload checked | Does not mutate core tables directly. | | `ExternalArtifactRejected` | `audit_event` | `ExternalArtifact` | payload rejected | Preserve reason. | | `ProjectionMappingCreated` | `audit_event` | `ProjectionMapping` | external ID mapped to internal ID | Adapter boundary. | | `ProjectionMappingUpdated` | `audit_event` | `ProjectionMapping` | mapping changed | Must be audited. | | `ProjectionApplied` | `audit_event` | `ProjectionMapping` | projection created via Ethikos service | Must use service layer, not direct DB write. | External boundary invariant: ```txt Annex tools write ExternalArtifact and ProjectionMapping only. Canonical projection must go through Ethikos services. Foreign tools do not write core Korum/Konsultations tables directly. ``` --- ## 18. Admin and Audit Event Registry Admin and audit events provide traceability. | Event | Family | Subject | Trigger | Notes | | -------------------------- | ------------- | ----------------------------- | -------------------------------------------- | -------------------------------------------------------- | | `ModerationActionRecorded` | `audit_event` | `ModerationAction` | moderation action taken | Required for admin traceability. | | `AuditEventRecorded` | `audit_event` | `AuditEvent` | system/admin event logged | Generic audit record. | | `RoleAssigned` | `audit_event` | `DiscussionParticipantRole` | user receives role | Role scope must be explicit. | | `RoleRevoked` | `audit_event` | `DiscussionParticipantRole` | role removed | Must be audited. | | `VisibilitySettingChanged` | `audit_event` | `DiscussionVisibilitySetting` | author/vote/participation visibility changed | Important for anonymity. | | `AnonymousModeEnabled` | `audit_event` | `DiscussionVisibilitySetting` | anonymous mode enabled | Must protect normal participants from identity exposure. | | `AnonymousModeDisabled` | `audit_event` | `DiscussionVisibilitySetting` | anonymous mode disabled | Must be explicit and audited. | --- ## 19. Vote and Reading Separation The following object distinctions are mandatory. | Object | Owner | Level | Range / Form | Source or Derived? | | -------------------- | ------------- | ---------------------- | ----------------- | ------------------ | | `EthikosStance` | Korum | Topic | `-3..+3` | Source | | `ArgumentImpactVote` | Korum | Argument/claim | `0..4` | Source | | `BallotEvent` | Konsultations | Decision/consultation | Protocol-specific | Source | | `BaselineResult` | Smart Vote | Aggregation | Computed | Derived | | `ReadingResult` | Smart Vote | Lens-based aggregation | Computed | Derived | | `SnapshotRef` | EkoH | Context | Reference | Context | Forbidden equivalences: ```txt ArgumentImpactVote = EthikosStance ArgumentImpactVote = BallotEvent EthikosStance = ReadingResult BallotEvent = ReadingResult SnapshotRef = vote EkoH context = vote Smart Vote reading = source fact ``` --- ## 20. Object Lifecycle by Pipeline Stage | Stage | Name | Primary Owner | Input Objects | Output Objects | | ----: | ------------------------ | -------------------------- | -------------------------------------------------- | ------------------------------------------------------- | | 0 | Intake | Konsultations | `IntakeSubmission` | `ProblemStatement`, `IntakeQueue` | | 1 | Discovery / Consultation | Konsultations | `ProblemStatement`, `Option`, `Constraint` | `OptionSet`, `ConstraintSet` | | 2 | Deliberation | Korum | `EthikosTopic`, `EthikosArgument`, `EthikosStance` | `ArgumentGraph`, `StanceEvent`, `ModerationAction` | | 3 | Drafting | Drafting | `ArgumentGraph`, `OptionSet`, `ConstraintSet` | `Draft`, `DraftVersion`, `Amendment`, `RationalePacket` | | 4 | Decision | Konsultations / Smart Vote | `BallotEvent`, `EthikosStance`, `LensDeclaration` | `BaselineResult`, `ReadingResult`, `DecisionRecord` | | 5 | Accountability | Konsultations | `DecisionRecord`, `ImpactTrack` | `ImpactUpdate`, public accountability snapshot | --- ## 21. Object Naming Rules Canonical object names must follow these rules: 1. Use singular nouns. 2. Use PascalCase. 3. Do not encode implementation framework names. 4. Do not encode OSS source names unless the object is explicitly external-boundary/provenance. 5. Prefer domain meaning over UI label. 6. Preserve existing model names exactly. Valid: ```txt ArgumentSource ReadingResult LensDeclaration ImpactTrack ExternalArtifact ProjectionMapping ``` Invalid: ```txt KialoClaim DecidimProposal LoomioPoll ConsulVote WeightedTopicThing DebatePost Opinion ``` Exception: * OSS names may appear in documentation as pattern references, not canonical object names. --- ## 22. Event Naming Rules Canonical events must follow these rules: 1. Use PascalCase. 2. Use past tense. 3. Start with the object or domain subject. 4. Do not use UI verbs such as “clicked” unless the UI action is the actual audited event. 5. Do not name derived readings as if they are source facts. Valid: ```txt TopicCreated ArgumentSourceAttached ArgumentImpactVoteRecorded ReadingComputed ImpactUpdatePublished ProjectionMappingCreated ``` Invalid: ```txt UserClickedVote KialoClaimMade SmartVoteChangedStance EkoHVoted ResultTruthOverwritten ``` --- ## 23. Required Object Invariants ### 23.1 Existing Core Must Remain Stable ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` These names must not be replaced or renamed by Kintsugi. ### 23.2 Source Facts Must Remain Source Facts Source facts include: ```txt EthikosTopic EthikosStance EthikosArgument ArgumentImpactVote BallotEvent DraftVersion Amendment ImpactUpdate ``` Source facts must not be overwritten by derived readings. ### 23.3 Readings Must Be Reproducible Every `ReadingResult` must be reproducible from: ```txt BaselineEvents + LensDeclaration + SnapshotContext? ``` Required reading fields: ```txt reading_key lens_hash snapshot_ref computed_at topic_id or consultation_id results_payload ``` ### 23.4 External Artifacts Must Be Boundary Objects External artifacts are not canonical civic truth until projected through approved services. ### 23.5 Anonymity Must Be Protected If `DiscussionVisibilitySetting` enables anonymous participation, ordinary participants must not see hidden author identities. --- ## 24. First-Pass Additions The following objects are recommended for first-pass consideration. ```yaml FIRST_PASS_OBJECTS: KORUM: - "ArgumentSource" - "ArgumentImpactVote" - "ArgumentSuggestion" - "DiscussionParticipantRole" - "DiscussionVisibilitySetting" KONSULTATIONS: - "IntakeSubmission" - "Option" - "Constraint" - "BallotEvent" - "DecisionProtocol" - "DecisionRecord" SMART_VOTE: - "LensDeclaration" - "ReadingResult" DRAFTING: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" IMPACT: - "ImpactTrack" - "ImpactUpdate" EXTERNAL_BOUNDARY: - "ExternalArtifact" - "ProjectionMapping" ADMIN_AUDIT: - "ModerationAction" - "AuditEvent" ``` These are not automatically implementation tasks. They are canonical object candidates to be considered by: ```txt 08_DATA_MODEL_AND_MIGRATION_PLAN.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 25. Deferred Objects The following objects are valid but deferred unless explicitly approved later. ```yaml DEFERRED_OBJECTS: KIALO_STYLE: - "ArgumentBookmark" - "ArgumentLink" - "DiscussionPerspective" - "DiscussionTemplate" - "DiscussionGroup" - "DiscussionExport" ADVANCED_CONSENSUS: - "PolisCluster" - "LiquidDelegation" - "PairwisePreference" MEETING_FORMALITY: - "AgendaItem" - "Motion" - "RollCall" ``` Deferred means: * may be mentioned as future work; * must not drive first-pass migrations; * must not create first-pass endpoints; * must not create first-pass route families. --- ## 26. Anti-Drift Rules The following rules are binding. ### 26.1 Do Not Rename Existing Core ```txt Do not rename EthikosTopic. Do not rename EthikosStance. Do not rename EthikosArgument. Do not rename EthikosCategory. ``` ### 26.2 Do Not Create Duplicate Concept Models Forbidden duplicates: ```txt Claim as replacement for EthikosArgument Opinion as replacement for EthikosStance KialoDiscussion as replacement for EthikosTopic WeightedVote as replacement for ReadingResult ``` ### 26.3 Do Not Merge Vote Types ```txt EthikosStance is topic-level. ArgumentImpactVote is argument-level. BallotEvent is consultation/decision-level. ReadingResult is derived. ``` ### 26.4 Do Not Move Ownership ```txt Korum owns deliberation source facts. Konsultations owns formal consultation inputs and accountability. Smart Vote owns derived readings. EkoH owns context only. ``` ### 26.5 Do Not Create a Kialo Module ```txt Do not create /kialo routes. Do not create konnaxion.kialo. Do not import Kialo code. Use Kialo as native mimic inside /ethikos/deliberate/*. ``` ### 26.6 Do Not Let Annexes Write Core Tables ```txt External tools write ExternalArtifact and ProjectionMapping. They do not write EthikosTopic, EthikosStance, EthikosArgument, BallotEvent, or ReadingResult directly. ``` ### 26.7 Do Not Produce Backlog Here This file defines vocabulary. It does not assign tasks. --- ## 27. Invalid Object/Event Patterns The following are invalid and must be rejected. ```txt Object: KialoClaim Reason: duplicates EthikosArgument and creates OSS naming drift. Object: SmartVoteStance Reason: merges source stance with derived reading. Object: EkoHVote Reason: EkoH is not a voting engine. Object: DecidimProcess Reason: imports OSS product architecture as canonical object. Object: PolisCluster Reason: deferred source, not first-pass. Event: SmartVoteChangedStance Reason: Smart Vote must not mutate source facts. Event: EkoHVoted Reason: EkoH does not vote. Event: ArgumentImpactVoteBecameBallot Reason: argument impact votes and ballots are separate object families. ``` --- ## 28. Valid Object/Event Patterns The following are valid. ```txt Object: ArgumentSource Reason: supports Kialo-style evidence transparency. Object: ArgumentImpactVote Reason: supports Kialo-style claim-level impact voting while preserving EthikosStance. Object: ReadingResult Reason: captures Smart Vote derived readings. Object: LensDeclaration Reason: makes Smart Vote readings declared and reproducible. Object: ExternalArtifact Reason: supports future annex boundaries without direct core writes. Event: ArgumentSourceAttached Reason: records evidence added to a claim/argument. Event: ReadingComputed Reason: records derived Smart Vote computation. Event: ProjectionMappingCreated Reason: records controlled mapping from external artifact to canonical object. ``` --- ## 29. Related Docs This document depends on: ```txt 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md ``` This document is referenced by: ```txt 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 18_ADR_REGISTER.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 30. Final Binding Rule All future Kintsugi docs, code proposals, schema designs, serializer contracts, frontend payloads, and backlog tasks must use this object/event vocabulary unless a later human-approved ADR explicitly supersedes it. ```yaml FINAL_RULE: IF_A_NEW_OBJECT_DUPLICATES_EXISTING_CORE: RESULT: "invalid" IF_A_NEW_EVENT_MUTATES_THE_WRONG_OWNER: RESULT: "invalid" IF_A_READING_IS_TREATED_AS_SOURCE_FACT: RESULT: "invalid" IF_KIALO_TERMS_REPLACE_ETHIKOS_MODEL_NAMES: RESULT: "invalid" IF_EXTERNAL_TOOLS_WRITE_CORE_TABLES: RESULT: "invalid" IF_THE_OBJECT_OR_EVENT_IS_NOT_LISTED_HERE: ACTION: "add it to this document through explicit review before implementation" ``` This document is the canonical object and event registry for the ethiKos Kintsugi upgrade. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 143346d2169401863b9f611aac2e11f9871edb2c0ba48e4b4207381730d0ad0a CONTENT_BYTES: 41408 ================================================================================================ # 13 — Payload Shapes and Serializer Contracts **Document ID:** `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical / Technical Contract **Last aligned:** 2026-04-25 **Primary purpose:** Fix request/response payload shapes, serializer responsibilities, naming conventions, enum values, and frontend/backend normalization rules for the ethiKos Kintsugi upgrade. --- ## 1. Purpose This document defines the canonical JSON payload shapes and serializer contracts for the ethiKos Kintsugi upgrade. It prevents drift between: * frontend TypeScript interfaces; * Django REST Framework serializers; * backend viewsets; * service-layer adapters; * future Kintsugi models; * Smart Vote readings; * EkoH snapshot references; * Kialo-style argument mapping; * Konsultations-style suggestions, ballots, and impact tracking. The current ethiKos backend core is centered on `EthikosTopic`, `EthikosStance`, `EthikosArgument`, and `EthikosCategory`, exposed under `/api/ethikos/topics/`, `/api/ethikos/stances/`, `/api/ethikos/arguments/`, and `/api/ethikos/categories/` when registered. Compatibility aliases also exist under `/api/deliberate/...` and `/api/deliberate/elite/...`. --- ## 2. Scope This document covers: * current ethiKos payloads; * current serializer behavior that must remain stable; * frontend normalization rules; * Kintsugi first-pass additive payloads; * Smart Vote / EkoH reading payloads; * Kialo-style deliberation payloads; * drafting payloads; * impact/accountability payloads; * error response shapes; * pagination shape expectations; * enum and value constraints. This document does not authorize implementation by itself. New models, migrations, endpoints, and serializers must still be governed by: * `07_API_AND_SERVICE_CONTRACTS.md` * `08_DATA_MODEL_AND_MIGRATION_PLAN.md` * `09_SMART_VOTE_EKOH_READING_CONTRACT.md` * `14_FRONTEND_ALIGNMENT_CONTRACT.md` * `15_BACKEND_ALIGNMENT_CONTRACT.md` * `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` --- ## 3. Canonical Variables Used ```yaml DOCUMENT_NAME: "13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md" DOCUMENT_ROLE: "Payload and serializer contract" API_STYLE: "Django REST Framework ViewSet + Serializer + Router" TRANSPORT: "REST over HTTP" GRAPHQL_FOR_CRUD_ALLOWED: false WEBSOCKET_FOR_CRUD_ALLOWED: false BACKEND_JSON_FIELD_STYLE: "snake_case" FRONTEND_INTERNAL_FIELD_STYLE: "camelCase allowed after normalization" DATE_FORMAT: "ISO_8601" CURRENT_ID_TYPE: "integer" PAGINATION_STYLE: "DRF-compatible" PRIMARY_API_PREFIX: "/api/ethikos/" CURRENT_ETHIKOS_ENDPOINTS: TOPICS: "/api/ethikos/topics/" STANCES: "/api/ethikos/stances/" ARGUMENTS: "/api/ethikos/arguments/" CATEGORIES: "/api/ethikos/categories/" COMPATIBILITY_ENDPOINTS: DELIBERATE: "/api/deliberate/..." DELIBERATE_ELITE: "/api/deliberate/elite/..." LEGACY_ENDPOINTS: API_HOME: "/api/home/*" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" STANCE_VALUE_RANGE: "-3..+3" ARGUMENT_SIDE_VALUES: - "pro" - "con" - "neutral" - null KIALO_IMPACT_VOTE_RANGE: "0..4" KIALO_IMPACT_VOTE_IS_TOPIC_STANCE: false SMART_VOTE_READING_IS_SOURCE_FACT: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false ``` --- ## 4. Source-of-Truth Rules ## 4.1 Backend Payload Truth The backend API payload truth is DRF JSON using `snake_case`. Backend serializers must expose field names that are stable, documented, and compatible with existing frontend service adapters. ## 4.2 Frontend Payload Truth Frontend components may use normalized TypeScript shapes in `camelCase`, but raw API types must remain documented. Frontend code must not invent backend field names. Frontend service modules may normalize: ```txt created_at -> createdAt updated_at -> updatedAt parent_id -> parentId target_type -> targetType target_id -> targetId ``` Normalization belongs in services/hooks/adapters, not scattered across page components. The project guidance explicitly requires frontend API calls to use the services layer, respect existing `/api/...` path prefixes, avoid invented paths, and avoid renaming `/api/ethikos/...` to alternatives such as `/api/deliberation/...`. --- ## 5. Serializer Design Principles ## 5.1 Stable Read / Flexible Write Serializers SHOULD expose rich read fields but accept compact write fields. Example: * read may include `category_detail`; * write may accept `category` or `category_id`; * read may include `created_by`; * write should inject `created_by` from the request user. The current `TopicViewSet` injects `created_by` and resolves category from either `category` or `category_id`, while categories are exposed through a read-only viewset by default. ## 5.2 Explicit Ownership Serializer names must match the owning domain. Examples: ```txt EthikosTopicSerializer EthikosStanceSerializer EthikosArgumentSerializer EthikosCategorySerializer ReadingResultSerializer LensDeclarationSerializer ArgumentImpactVoteSerializer ArgumentSourceSerializer ``` Do not create ambiguous names such as: ```txt VoteSerializer PostSerializer OpinionSerializer ClaimSerializer GenericResultSerializer ``` unless the relevant ownership contract explicitly approves them. ## 5.3 No Silent Semantic Collapse Serializers must not collapse distinct concepts: | Concept | Must remain distinct from | | -------------------- | --------------------------------------------- | | `EthikosStance` | `ArgumentImpactVote`, `ReadingResult`, ballot | | `ArgumentImpactVote` | topic stance, Smart Vote ballot | | `ReadingResult` | raw stance, raw ballot, source fact | | `EkoHSnapshot` | vote, reading, ballot | | `DraftVersion` | decision outcome | | `ImpactTrack` | KeenKonnect project | --- ## 6. API Envelope and Pagination ## 6.1 List Response Compatibility The current frontend must tolerate both DRF paginated and bare-list responses where legacy code already does so. Allowed list shapes: ```json [ { "id": 1 } ] ``` ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 1 } ] } ``` New endpoints SHOULD use standard DRF pagination where appropriate. Frontend adapters SHOULD normalize both forms into arrays. The current frontend Smart Vote polling code already handles both a bare list and a paginated `{ "results": [...] }` shape when reading `/api/kollective/votes/`. ## 6.2 Detail Response Shape Detail endpoints SHOULD return a single JSON object. ```json { "id": 1, "created_at": "2026-04-25T15:28:01Z", "updated_at": "2026-04-25T15:28:01Z" } ``` ## 6.3 Error Response Shape Use DRF-compatible error responses. Field-level error: ```json { "value": ["Ensure this value is greater than or equal to -3."] } ``` Non-field error: ```json { "non_field_errors": ["Invalid payload."] } ``` Detail error: ```json { "detail": "Not found." } ``` Kintsugi-specific serializers MAY add stable error codes later, but they must remain compatible with DRF clients. --- ## 7. Current Canonical ethiKos Payloads ## 7.1 `EthikosCategoryPayload` ### Owner ```yaml OWNER: "ethiKos" MODEL: "EthikosCategory" ENDPOINT: "/api/ethikos/categories/" CURRENT_STATUS: "current canonical model; endpoint only if registered" ``` ### Read Shape ```json { "id": 1, "name": "Climate", "description": "Topics related to climate policy." } ``` ### Write Shape Categories are read-only by default unless an admin endpoint explicitly permits writes. ```json { "name": "Climate", "description": "Topics related to climate policy." } ``` ### Serializer Rules * `id` is read-only. * `name` is required. * `description` may be blank. * Public category listing may allow `AllowAny`. The current contracts describe `EthikosCategory` as a topic grouping with `name` and `description`. --- ## 7.2 `EthikosTopicPayload` ### Owner ```yaml OWNER: "Korum / ethiKos" MODEL: "EthikosTopic" ENDPOINT: "/api/ethikos/topics/" ``` ### Read Shape ```json { "id": 42, "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "status": "open", "category": 3, "category_detail": { "id": 3, "name": "Mobility", "description": "Transport and public space." }, "created_by": 7, "created_by_display": "alice", "expertise_category": 12, "total_votes": 18, "last_activity": "2026-04-25T15:00:00Z", "created_at": "2026-04-25T14:00:00Z", "updated_at": "2026-04-25T15:00:00Z" } ``` ### Minimum Read Shape Serializers may omit nested display fields, but must preserve the core shape: ```json { "id": 42, "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "status": "open", "category": 3, "created_by": 7, "total_votes": 18, "last_activity": "2026-04-25T15:00:00Z", "created_at": "2026-04-25T14:00:00Z", "updated_at": "2026-04-25T15:00:00Z" } ``` ### Create Shape ```json { "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "category": 3 } ``` Also accepted for compatibility: ```json { "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "category_id": 3 } ``` ### Update Shape ```json { "title": "Updated title", "description": "Updated description", "status": "closed", "category": 4 } ``` ### Allowed `status` ```yaml TOPIC_STATUS: - "open" - "closed" - "archived" ``` ### Serializer Rules * `id` is read-only. * `created_by` is read-only and injected from request user. * `created_by_display` is read-only if present. * `total_votes` is read-only unless explicitly managed by backend logic. * `last_activity` is read-only unless explicitly managed by backend logic. * `category` is required on create. * `category` is optional on update. * `status` must be one of `open`, `closed`, `archived`. `EthikosTopic` is documented as the debate/consultation prompt with `status`, category, creator, vote totals, and activity timestamps. --- ## 7.3 `EthikosTopicPreviewPayload` ### Owner ```yaml OWNER: "Korum / ethiKos" MODEL: "EthikosTopic" LIKELY_ACTION: "TopicViewSet.preview" ENDPOINT_PATTERN: "/api/ethikos/topics/{id}/preview/" CURRENT_BUG_CONTEXT: "Deliberate preview drawer shows 'Preview / No data'" ``` ### Read Shape ```json { "id": 42, "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "status": "open", "category": { "id": 3, "name": "Mobility" }, "stats": { "stance_count": 18, "argument_count": 9, "pro_count": 4, "con_count": 3, "neutral_count": 2 }, "last_activity": "2026-04-25T15:00:00Z" } ``` ### Serializer Rules * This payload is a read-only preview projection. * It must not replace `EthikosTopicPayload`. * The preview drawer must accept this shape explicitly. * If the backend returns only the minimal topic shape, the frontend adapter must normalize it into this preview shape. The backend code contains a `preview` action intended to return a minimal topic preview compatible with frontend usage like `topics/{id}/preview`. --- ## 7.4 `EthikosStancePayload` ### Owner ```yaml OWNER: "Korum" MODEL: "EthikosStance" ENDPOINT: "/api/ethikos/stances/" LEVEL: "topic-level" RANGE: "-3..+3" ``` ### Read Shape ```json { "id": 1001, "topic": 42, "user": 7, "user_display": "alice", "value": 2, "timestamp": "2026-04-25T15:10:00Z" } ``` ### Create / Update Shape ```json { "topic": 42, "value": 2 } ``` ### Allowed `value` ```yaml STANCE_VALUE_RANGE: MIN: -3 MAX: 3 INTEGER_ONLY: true ``` Semantic labels: ```yaml -3: "Strongly against" -2: "Moderately against" -1: "Somewhat against" 0: "Neutral / undecided" 1: "Somewhat for" 2: "Moderately for" 3: "Strongly for" ``` ### Serializer Rules * `id` is read-only. * `user` is read-only and injected from request user. * `timestamp` is read-only. * `topic` is required. * `value` is required. * `value` must be an integer between `-3` and `3`. * A user should have one stance per topic. * Updating a stance should upsert or replace the user’s previous stance, depending on backend implementation. The current docs and frontend logic use `EthikosStance` as one user’s numeric topic-level position, constrained to `-3 … +3`; consultation-result hooks aggregate stance rows returned from `/api/ethikos/stances/?topic=`. --- ## 7.5 `EthikosArgumentPayload` ### Owner ```yaml OWNER: "Korum" MODEL: "EthikosArgument" ENDPOINT: "/api/ethikos/arguments/" LEVEL: "argument/thread-entry" ``` ### Read Shape ```json { "id": 501, "topic": 42, "user": 7, "user_display": "alice", "content": "Protected bike lanes reduce severe injuries and improve access.", "side": "pro", "parent": null, "parent_id": null, "is_hidden": false, "created_at": "2026-04-25T15:12:00Z", "updated_at": "2026-04-25T15:12:00Z" } ``` ### Create Shape ```json { "topic": 42, "content": "Protected bike lanes reduce severe injuries and improve access.", "side": "pro", "parent": null } ``` ### Reply Create Shape ```json { "topic": 42, "content": "This depends on street design and winter maintenance.", "side": "con", "parent": 501 } ``` ### Allowed `side` ```yaml ARGUMENT_SIDE: - "pro" - "con" - "neutral" - null ``` ### Serializer Rules * `id` is read-only. * `user` is read-only and injected from request user. * `topic` is required. * `content` is required. * `side` is optional. * `parent` is optional. * `parent_id` may be exposed for frontend compatibility. * `is_hidden` is read-only for normal users and writable only through moderation/admin flows. * `created_at` and `updated_at` are read-only. The current frontend documents a raw argument shape returned from `/api/ethikos/arguments/`, including optional `parent` and `parent_id` fields depending on serializer configuration; Konsultations suggestions currently normalize Ethikos arguments into suggestion objects. --- ## 8. Kialo-Style Deliberation Payloads ## 8.1 `ArgumentTreePayload` ### Owner ```yaml OWNER: "Korum" ROUTE_SCOPE: "/ethikos/deliberate/*" SOURCE_PATTERN: "Kialo-style structured argument mapping" ``` ### Read Shape ```json { "topic": { "id": 42, "title": "Should the city prioritize protected bike lanes?", "description": "A structured public deliberation about mobility priorities.", "status": "open" }, "root_nodes": [ { "id": 501, "topic": 42, "content": "Protected bike lanes reduce severe injuries and improve access.", "side": "pro", "parent": null, "children": [], "source_count": 2, "impact_summary": { "average": 3.5, "count": 12 } } ], "settings": { "topology": "single_thesis", "author_visibility": "all", "vote_visibility": "all", "participation_type": "standard" } } ``` ### Serializer Rules * This is a projection over `EthikosTopic` and `EthikosArgument`. * It must not replace the canonical `EthikosArgumentPayload`. * It may be assembled in a service layer instead of a database model. * Children must preserve stable IDs. * The tree must distinguish `side` from stance. --- ## 8.2 `ArgumentNodePayload` ### Read Shape ```json { "id": 501, "topic": 42, "user": 7, "user_display": "alice", "content": "Protected bike lanes reduce severe injuries and improve access.", "side": "pro", "parent": null, "depth": 0, "path": [501], "is_hidden": false, "source_count": 2, "impact_summary": { "average": 3.5, "count": 12, "my_vote": 4 }, "created_at": "2026-04-25T15:12:00Z", "updated_at": "2026-04-25T15:12:00Z" } ``` ### Serializer Rules * `depth` and `path` are computed projection fields. * `impact_summary` is computed from `ArgumentImpactVote`. * `my_vote` is included only for authenticated users. * Hidden arguments should not expose content to unauthorized users. --- ## 8.3 `ArgumentSourcePayload` ### Owner ```yaml OWNER: "Korum" PROPOSED_MODEL: "ArgumentSource" ATTACHES_TO: "EthikosArgument" ``` ### Read Shape ```json { "id": 9001, "argument": 501, "url": "https://example.org/safety-study", "title": "Road Safety Study", "publisher": "Example Institute", "published_at": "2025-11-01", "excerpt": "Short excerpt or summary.", "added_by": 7, "created_at": "2026-04-25T15:20:00Z", "updated_at": "2026-04-25T15:20:00Z" } ``` ### Create Shape ```json { "argument": 501, "url": "https://example.org/safety-study", "title": "Road Safety Study", "publisher": "Example Institute", "published_at": "2025-11-01", "excerpt": "Short excerpt or summary." } ``` ### Serializer Rules * `argument` is required. * `url` is required unless a future non-URL source type is defined. * `title` is recommended. * `added_by` is injected from request user. * Sources must not be used as hidden weights. * Sources must remain attached to arguments, not to Smart Vote readings. --- ## 8.4 `ArgumentImpactVotePayload` ### Owner ```yaml OWNER: "Korum" PROPOSED_MODEL: "ArgumentImpactVote" LEVEL: "argument/claim-level" RANGE: "0..4" NOT_A_TOPIC_STANCE: true NOT_A_SMART_VOTE_BALLOT: true ``` ### Read Shape ```json { "id": 3001, "argument": 501, "user": 7, "value": 4, "created_at": "2026-04-25T15:30:00Z", "updated_at": "2026-04-25T15:30:00Z" } ``` ### Create / Update Shape ```json { "argument": 501, "value": 4 } ``` ### Allowed `value` ```yaml ARGUMENT_IMPACT_VALUE: MIN: 0 MAX: 4 INTEGER_ONLY: true ``` ### Serializer Rules * `argument` is required. * `value` is required. * `value` must be integer `0..4`. * `user` is injected from request user. * One user should have one impact vote per argument. * This payload must never be merged with `EthikosStancePayload`. --- ## 8.5 `ArgumentSuggestionPayload` ### Owner ```yaml OWNER: "Korum" PROPOSED_MODEL: "ArgumentSuggestion" ROLES_RELATED: - "suggester" - "editor" - "admin" - "owner" ``` ### Read Shape ```json { "id": 7101, "topic": 42, "parent": 501, "suggested_side": "pro", "content": "A possible supporting claim.", "status": "pending", "suggested_by": 9, "reviewed_by": null, "accepted_argument": null, "created_at": "2026-04-25T15:40:00Z", "updated_at": "2026-04-25T15:40:00Z" } ``` ### Create Shape ```json { "topic": 42, "parent": 501, "suggested_side": "pro", "content": "A possible supporting claim." } ``` ### Allowed `status` ```yaml ARGUMENT_SUGGESTION_STATUS: - "pending" - "accepted" - "rejected" ``` ### Serializer Rules * Suggestions must not publish directly as arguments unless accepted by an authorized role. * `accepted_argument` links to the created `EthikosArgument` after approval. * Suggested content must preserve author/audit metadata. --- ## 8.6 `DiscussionSettingsPayload` ### Owner ```yaml OWNER: "Korum" PROPOSED_MODEL: "DiscussionVisibilitySetting" ATTACHES_TO: "EthikosTopic" ``` ### Read / Write Shape ```json { "topic": 42, "topology": "single_thesis", "participation_type": "standard", "author_visibility": "all", "vote_visibility": "all", "suggestions_enabled": true, "sources_required": false, "created_at": "2026-04-25T15:00:00Z", "updated_at": "2026-04-25T15:00:00Z" } ``` ### Enums ```yaml DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" PARTICIPATION_TYPE: - "standard" - "anonymous" AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" ``` ### Serializer Rules * Anonymous mode must not remove admin auditability. * Author visibility must not expose anonymous identities to normal participants. * Vote visibility controls claim-level impact votes, not topic-level stance visibility unless explicitly documented. --- ## 8.7 `ParticipantRolePayload` ### Owner ```yaml OWNER: "Korum" PROPOSED_MODEL: "DiscussionParticipantRole" ATTACHES_TO: "EthikosTopic" ``` ### Read Shape ```json { "id": 8101, "topic": 42, "user": 7, "role": "editor", "assigned_by": 1, "created_at": "2026-04-25T15:00:00Z", "updated_at": "2026-04-25T15:00:00Z" } ``` ### Create / Update Shape ```json { "topic": 42, "user": 7, "role": "editor" } ``` ### Allowed `role` ```yaml DISCUSSION_ROLE: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" ``` ### Serializer Rules * `owner` should be unique or controlled per topic. * Role assignment requires admin/owner-level permission. * Role changes must be auditable. --- ## 9. Konsultations Payloads ## 9.1 `ConsultationSuggestionPayload` ### Owner ```yaml OWNER: "Konsultations" CURRENT_BACKING_SOURCE: "EthikosArgument when mapped to topic suggestions" CURRENT_FRONTEND_NORMALIZATION: "Suggestion" ``` ### Normalized Frontend Shape ```json { "id": "501", "consultationId": "42", "author": "alice", "body": "Protected bike lanes should be prioritized.", "createdAt": "2026-04-25T15:12:00Z", "parentId": null } ``` ### Create Shape ```json { "body": "Protected bike lanes should be prioritized.", "parentId": null } ``` ### Backend Write Projection When backed by `EthikosArgument`, the service adapter posts: ```json { "topic": 42, "content": "Protected bike lanes should be prioritized.", "parent": null } ``` ### Serializer Rules * This is a projection, not a new canonical backend truth unless future Konsultations models are added. * `consultationId` maps to `EthikosTopic.id` in the current implementation. * `body` maps to `EthikosArgument.content`. * `parentId` maps to `EthikosArgument.parent`. The current frontend hook reads consultation suggestions from `ethikos/arguments/`, maps `EthikosArgumentApi` into a normalized `Suggestion`, and posts suggestions back to `ethikos/arguments/`. --- ## 9.2 `ConsultationResultsPayload` ### Owner ```yaml OWNER: "Konsultations" CURRENT_BACKING_SOURCE: "EthikosStance rows aggregated by topic" ``` ### Read Shape ```json { "consultation_id": 42, "stats": { "total": 18, "average": 1.2, "counts": { "-3": 1, "-2": 1, "-1": 2, "0": 3, "1": 4, "2": 5, "3": 2 } }, "buckets": [ { "value": -3, "label": "Strongly against", "count": 1, "share": 0.0556 }, { "value": 3, "label": "Strongly for", "count": 2, "share": 0.1111 } ] } ``` ### Serializer Rules * This can be a frontend-computed aggregate or backend projection. * It must preserve raw stance counts. * It must not be confused with `ReadingResultPayload`. * If weighted readings are included, they must be nested under a separate `readings` key. --- ## 10. Smart Vote / EkoH Payloads ## 10.1 `LensDeclarationPayload` ### Owner ```yaml OWNER: "Smart Vote" PURPOSE: "Declare how a derived reading is computed" ``` ### Read Shape ```json { "id": 1201, "reading_key": "expertise_weighted_mobility", "label": "Expertise-weighted mobility reading", "description": "Weights baseline stance events using declared mobility expertise context.", "target_type": "ethikos_topic", "target_id": 42, "method": "weighted_average", "parameters": { "weight_source": "ekoh_snapshot", "domain": "mobility", "min_confidence": 0.6 }, "lens_hash": "sha256:abc123", "created_by": 1, "created_at": "2026-04-25T16:00:00Z", "updated_at": "2026-04-25T16:00:00Z" } ``` ### Create Shape ```json { "reading_key": "expertise_weighted_mobility", "label": "Expertise-weighted mobility reading", "description": "Weights baseline stance events using declared mobility expertise context.", "target_type": "ethikos_topic", "target_id": 42, "method": "weighted_average", "parameters": { "weight_source": "ekoh_snapshot", "domain": "mobility", "min_confidence": 0.6 } } ``` ### Serializer Rules * `reading_key` is required and stable. * `lens_hash` is computed from method and parameters. * `parameters` must be JSON-serializable. * A lens must not mutate source events. --- ## 10.2 `ReadingResultPayload` ### Owner ```yaml OWNER: "Smart Vote" PURPOSE: "Published derived result" NOT_SOURCE_FACT: true ``` ### Read Shape ```json { "id": 1301, "reading_key": "expertise_weighted_mobility", "lens_hash": "sha256:abc123", "snapshot_ref": "ekoh-snapshot-2026-04-25T16:00:00Z", "target_type": "ethikos_topic", "target_id": 42, "baseline_ref": { "source": "ethikos_stances", "topic": 42, "event_count": 18 }, "results_payload": { "score": 0.68, "distribution": { "-3": 0.03, "-2": 0.04, "-1": 0.08, "0": 0.12, "1": 0.21, "2": 0.34, "3": 0.18 }, "summary": "Weighted support is moderately positive." }, "status": "published", "computed_at": "2026-04-25T16:05:00Z", "published_at": "2026-04-25T16:06:00Z" } ``` ### Serializer Rules * `reading_key` is required. * `lens_hash` is required. * `snapshot_ref` is required when EkoH context is used. * `results_payload` is required. * `computed_at` is required. * `target_type` and `target_id` are required. * `ReadingResult` must not overwrite baseline. * `ReadingResult` must not be treated as raw vote/stance truth. The boundaries plan requires Smart Vote readings to remain additive, explicitly declared, and auditable with fields such as `reading_key`, `lens_hash`, `snapshot_ref` or `ekoh_snapshot_id`, and non-breaking additions only. --- ## 10.3 `KollectiveVotePayload` ### Owner ```yaml OWNER: "Kollective Intelligence / Smart Vote" CURRENT_ENDPOINT: "/api/kollective/votes/" ``` ### Read Shape ```json { "id": 2001, "target_type": "ethikos_topic", "target_id": 42, "user": 7, "value": 1, "created_at": "2026-04-25T16:15:00Z", "updated_at": "2026-04-25T16:15:00Z" } ``` ### Create Shape ```json { "target_type": "ethikos_topic", "target_id": 42, "value": 1 } ``` ### Serializer Rules * This is a Smart Vote / Kollective Intelligence vote primitive. * It is not the same as `EthikosStance`. * It is not the same as `ArgumentImpactVote`. * `target_type` and `target_id` must remain explicit. * Aggregation into readings belongs in Smart Vote logic. The current code reads and posts Smart Vote poll data through `/api/kollective/votes/`, using `target_type` and `target_id` filters to aggregate poll results. --- ## 11. Drafting Payloads ## 11.1 `DraftPayload` ### Owner ```yaml OWNER: "ethiKos bounded drafting capability" PROPOSED_MODEL: "Draft" ``` ### Read Shape ```json { "id": 4001, "topic": 42, "title": "Mobility Policy Draft", "status": "draft", "current_version": 3, "created_by": 7, "created_at": "2026-04-25T17:00:00Z", "updated_at": "2026-04-25T17:30:00Z" } ``` ### Create Shape ```json { "topic": 42, "title": "Mobility Policy Draft" } ``` ### Allowed `status` ```yaml DRAFT_STATUS: - "draft" - "review" - "accepted" - "superseded" - "archived" ``` ### Serializer Rules * A draft links to a topic or consultation source. * A draft must not overwrite arguments or ballots. * `current_version` is computed. --- ## 11.2 `DraftVersionPayload` ### Read Shape ```json { "id": 4101, "draft": 4001, "version_number": 3, "body": "The city should prioritize protected bike lanes...", "summary": "Adds winter maintenance clause.", "created_by": 7, "created_at": "2026-04-25T17:30:00Z" } ``` ### Create Shape ```json { "draft": 4001, "body": "The city should prioritize protected bike lanes...", "summary": "Adds winter maintenance clause." } ``` ### Serializer Rules * `version_number` is server-assigned. * Versions are append-only. * Editing a draft creates a new version; it does not mutate historical versions. --- ## 11.3 `AmendmentPayload` ### Read Shape ```json { "id": 4201, "draft": 4001, "draft_version": 4101, "target_text": "protected bike lanes", "proposed_text": "protected bike lanes and pedestrian safety improvements", "rationale": "Broadens the policy scope.", "status": "submitted", "submitted_by": 8, "reviewed_by": null, "created_at": "2026-04-25T17:35:00Z", "updated_at": "2026-04-25T17:35:00Z" } ``` ### Allowed `status` ```yaml AMENDMENT_STATUS: - "submitted" - "accepted" - "rejected" - "withdrawn" ``` --- ## 11.4 `RationalePacketPayload` ### Read Shape ```json { "id": 4301, "draft": 4001, "source_arguments": [501, 502, 503], "source_stances_summary": { "total": 18, "average": 1.2 }, "source_readings": [1301], "summary": "The draft reflects strong safety arguments and moderate positive stance distribution.", "created_at": "2026-04-25T17:40:00Z" } ``` ### Serializer Rules * Rationale packets link drafting output back to deliberation/consultation evidence. * They must not become independent source truth. --- ## 12. Decision Payloads ## 12.1 `DecisionProtocolPayload` ### Owner ```yaml OWNER: "Smart Vote + ethiKos decision protocol" PROPOSED_MODEL: "DecisionProtocol" ``` ### Read Shape ```json { "id": 5101, "key": "simple_majority", "label": "Simple majority", "description": "Decision closes when a simple majority threshold is reached.", "parameters_schema": { "threshold": "number", "minimum_participants": "integer" }, "created_at": "2026-04-25T18:00:00Z", "updated_at": "2026-04-25T18:00:00Z" } ``` --- ## 12.2 `DecisionRecordPayload` ### Read Shape ```json { "id": 5201, "topic": 42, "protocol": 5101, "status": "published", "baseline_result": { "total": 18, "average": 1.2, "distribution": { "-3": 1, "-2": 1, "-1": 2, "0": 3, "1": 4, "2": 5, "3": 2 } }, "reading_results": [1301], "opened_at": "2026-04-25T18:00:00Z", "closed_at": "2026-04-26T18:00:00Z", "published_at": "2026-04-26T18:30:00Z", "created_at": "2026-04-25T18:00:00Z", "updated_at": "2026-04-26T18:30:00Z" } ``` ### Allowed `status` ```yaml DECISION_STATUS: - "draft" - "open" - "closed" - "published" - "archived" ``` ### Serializer Rules * `baseline_result` must remain visible when readings exist. * `reading_results` links to Smart Vote outputs. * A decision record must not mutate stances, ballots, or arguments. --- ## 13. Impact / Accountability Payloads ## 13.1 `ImpactTrackPayload` ### Owner ```yaml OWNER: "Konsultations / ethiKos Impact" PROPOSED_MODEL: "ImpactTrack" ``` ### Read Shape ```json { "id": 6101, "decision_record": 5201, "title": "Protected bike lane implementation", "status": "in_progress", "summary": "Planning and procurement are underway.", "owner_label": "City mobility department", "handoff_ref": { "module": "keenkonnect", "object_type": "project", "object_id": 9001 }, "created_at": "2026-04-26T19:00:00Z", "updated_at": "2026-04-27T10:00:00Z" } ``` ### Allowed `status` ```yaml IMPACT_STATUS: - "planned" - "in_progress" - "blocked" - "completed" - "cancelled" ``` ### Serializer Rules * `handoff_ref` is optional. * `handoff_ref` does not transfer civic truth ownership to KeenKonnect. * Impact records must remain linked to a decision or consultation result. --- ## 13.2 `ImpactUpdatePayload` ### Read Shape ```json { "id": 6201, "impact_track": 6101, "status": "in_progress", "body": "Procurement process opened.", "evidence_url": "https://example.org/procurement", "created_by": 7, "created_at": "2026-04-27T10:00:00Z" } ``` ### Create Shape ```json { "impact_track": 6101, "status": "in_progress", "body": "Procurement process opened.", "evidence_url": "https://example.org/procurement" } ``` --- ## 14. External Tool Boundary Payloads ## 14.1 `ExternalArtifactPayload` ### Owner ```yaml OWNER: "Integration boundary" PURPOSE: "Append-only external raw artifact" ``` ### Read Shape ```json { "id": 7001, "source_name": "decidim", "source_object_type": "proposal", "source_object_id": "abc-123", "payload": { "title": "External proposal title", "body": "External proposal body" }, "ingested_at": "2026-04-25T19:00:00Z", "created_at": "2026-04-25T19:00:00Z" } ``` ### Serializer Rules * External artifacts are append-only. * They do not become Korum/Konsultations source truth. * They require a projection mapping before being displayed as internal civic objects. --- ## 14.2 `ProjectionMappingPayload` ### Read Shape ```json { "id": 7101, "external_artifact": 7001, "internal_object_type": "EthikosTopic", "internal_object_id": 42, "mapping_type": "reference", "created_by": 1, "created_at": "2026-04-25T19:10:00Z" } ``` ### Allowed `mapping_type` ```yaml PROJECTION_MAPPING_TYPE: - "reference" - "imported_copy" - "derived_summary" ``` ### Serializer Rules * Projection mappings must not silently write to core tables. * If an imported copy is created, provenance must remain visible. --- ## 15. Audit Payloads ## 15.1 `AuditEventPayload` ### Owner ```yaml OWNER: "ethiKos governance/admin" ROUTE_SCOPE: "/ethikos/admin/audit" ``` ### Read Shape ```json { "id": 9001, "actor": 7, "action": "argument_hidden", "object_type": "EthikosArgument", "object_id": 501, "before": { "is_hidden": false }, "after": { "is_hidden": true }, "reason": "Violation of deliberation guidelines.", "source_ref": null, "snapshot_ref": null, "created_at": "2026-04-25T20:00:00Z" } ``` ### Serializer Rules * Audit events should be append-only. * `before` and `after` are optional JSON. * `reason` should be required for moderation actions. * Audit events must not expose sensitive anonymous-user mappings to unauthorized roles. --- ## 16. Frontend TypeScript Alignment Frontend service modules SHOULD define two layers of types: 1. raw API type; 2. normalized UI type. Example: ```ts export interface EthikosArgumentApi { id: number; topic: number; user: number | string; user_display?: string; content: string; side?: 'pro' | 'con' | 'neutral' | null; parent?: number | null; parent_id?: number | null; is_hidden?: boolean; created_at: string; updated_at?: string; } export interface ArgumentNode { id: string; topicId: string; author: string; content: string; side: 'pro' | 'con' | 'neutral' | null; parentId: string | null; isHidden: boolean; createdAt: string; updatedAt?: string; } ``` Rules: * API types mirror backend JSON. * UI types may normalize naming and IDs. * Normalization belongs in service/hook adapters. * Components should not infer backend shape repeatedly. --- ## 17. Serializer Naming Contract ## 17.1 Current Serializers ```txt EthikosCategorySerializer EthikosTopicSerializer EthikosStanceSerializer EthikosArgumentSerializer ``` ## 17.2 Proposed Kintsugi Serializers ```txt ArgumentTreeSerializer ArgumentNodeSerializer ArgumentSourceSerializer ArgumentImpactVoteSerializer ArgumentSuggestionSerializer DiscussionSettingsSerializer DiscussionParticipantRoleSerializer DecisionProtocolSerializer DecisionRecordSerializer LensDeclarationSerializer ReadingResultSerializer DraftSerializer DraftVersionSerializer AmendmentSerializer RationalePacketSerializer ImpactTrackSerializer ImpactUpdateSerializer ExternalArtifactSerializer ProjectionMappingSerializer AuditEventSerializer ``` ## 17.3 Forbidden Serializer Names Do not create ambiguous names: ```txt VoteSerializer ResultSerializer OpinionSerializer PostSerializer ClaimSerializer WeightedVoteSerializer GenericPayloadSerializer KialoSerializer ``` If such a name is unavoidable, the owning document must explicitly justify it. --- ## 18. Required Validation Rules ## 18.1 Topic Validation ```yaml title: required: true blank_allowed: false description: required: true blank_allowed: false status: allowed: - "open" - "closed" - "archived" category: required_on_create: true required_on_update: false ``` ## 18.2 Stance Validation ```yaml topic: required: true value: required: true type: integer min: -3 max: 3 unique: - "user + topic" ``` ## 18.3 Argument Validation ```yaml topic: required: true content: required: true blank_allowed: false side: allowed: - "pro" - "con" - "neutral" - null parent: required: false must_belong_to_same_topic: true ``` ## 18.4 Argument Impact Vote Validation ```yaml argument: required: true value: required: true type: integer min: 0 max: 4 unique: - "user + argument" ``` ## 18.5 Reading Result Validation ```yaml reading_key: required: true lens_hash: required: true target_type: required: true target_id: required: true results_payload: required: true type: object computed_at: required: true snapshot_ref: required_when: "EkoH context is used" ``` --- ## 19. Permission-Related Serializer Rules ## 19.1 Normal User Normal authenticated users may generally create: * their own stances; * their own arguments; * their own argument impact votes; * their own suggestions where suggestions are enabled. They may not: * set `user`; * set `created_by`; * set moderation fields; * publish readings; * assign participant roles; * reveal anonymous identities. ## 19.2 Admin / Moderator Admins and moderators may: * hide/unhide arguments; * accept/reject suggestions; * update discussion settings; * assign roles; * review audit records; * publish or invalidate readings if authorized. ## 19.3 System / Compute Actor System actors may: * compute `ReadingResult`; * assign `lens_hash`; * attach `snapshot_ref`; * create audit events for computations. System actors may not silently mutate source facts. --- ## 20. Anti-Drift Rules ```yaml FORBIDDEN: - "Do not rename EthikosArgument to Claim." - "Do not rename EthikosStance to Vote." - "Do not treat ArgumentImpactVote as EthikosStance." - "Do not treat Smart Vote ReadingResult as a source fact." - "Do not expose EkoH snapshot fields as hidden vote mutations." - "Do not create generic VotePayload for all vote-like behavior." - "Do not replace /api/ethikos/... with /api/deliberation/..." - "Do not expand /api/home/*." - "Do not create raw fetch calls in page components for new Kintsugi work." - "Do not use GraphQL or WebSockets for CRUD unless a later contract explicitly authorizes it." ``` --- ## 21. Related Documents ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 22. Acceptance Criteria This document is accepted when future frontend/backend work can answer the following without inventing new conventions: * What is the raw backend JSON shape? * What is the normalized frontend shape? * Which serializer owns this payload? * Which model backs the payload? * Which fields are read-only? * Which fields are injected from request context? * Which fields are computed? * Which values are valid enum values? * Is this a source fact or derived projection? * Is this topic-level, argument-level, decision-level, or reading-level? * Does this payload preserve the separation between Korum, Konsultations, Smart Vote, EkoH, and Kialo-style deliberation? If any payload cannot answer those questions, it is not ready for implementation. --- ## 23. Final Contract Statement Payloads are not neutral. They encode ownership. For Kintsugi, every payload must preserve the central architecture: * `EthikosTopic` remains the topic/debate/consultation container. * `EthikosStance` remains the topic-level stance. * `EthikosArgument` remains the argument/thread/claim-equivalent object. * `ArgumentImpactVote` remains claim-level only. * `ReadingResult` remains derived Smart Vote output only. * `EkoH` remains context, not voting. * Kialo-style deliberation remains a native Korum pattern, not a separate module. * External OSS patterns remain mimic-first and adapter-only later. The backend speaks stable DRF JSON. The frontend normalizes through services. The baseline remains visible. The derived readings remain declared. The serializers preserve the architecture. --- ## V4.1 EkoH profile payload extension Canonical fields added to the EkoH profile projection: `rating_visibility`, `rating_publication_basis`, `rating_access`, and `score_history`. `rating_access` contains `allowed`, `level`, `reason`, and optional `scope`. Denied callers receive null rating fields rather than client-side hidden values. See `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 6d5b2e5f0266b6c9598a01a109a30206a438dd236438cfd1bf09e477cd6938ca CONTENT_BYTES: 33303 ================================================================================================ # 14 — Frontend Alignment Contract **Document ID:** `14_FRONTEND_ALIGNMENT_CONTRACT.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Frontend contract **Last aligned:** 2026-04-25 **Primary purpose:** prevent frontend drift during the ethiKos Kintsugi upgrade. --- ## 1. Purpose This document defines the frontend alignment rules for the ethiKos Kintsugi upgrade. It fixes how Kintsugi work must fit into the existing Konnaxion frontend architecture: - the existing `/ethikos/*` route family remains canonical; - the existing global layout remains canonical; - the existing `EthikosPageShell` remains the module page wrapper; - the existing service layer remains the API access boundary; - external civic-tech patterns are mimicked inside ethiKos, not imported as separate frontend apps; - Smart Vote, EkoH, Kialo-style argument mapping, and other Kintsugi patterns must appear through existing route families unless a later ADR approves a new surface. This document is binding for all frontend implementation planning and AI-generated frontend documentation. --- ## 2. Scope This contract governs: - ethiKos frontend routes; - ethiKos page layout rules; - module shell usage; - page shell usage; - service-layer API access; - frontend component naming; - route-family responsibilities; - Kialo-style frontend surfaces; - Smart Vote/EkoH frontend boundaries; - frontend handling of known legacy/loose mappings; - frontend anti-drift rules. This contract does **not** define backend models, serializers, migrations, Smart Vote formulas, EkoH scoring logic, or detailed implementation tasks. Those belong to: - `08_DATA_MODEL_AND_MIGRATION_PLAN.md` - `09_SMART_VOTE_EKOH_READING_CONTRACT.md` - `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` - `15_BACKEND_ALIGNMENT_CONTRACT.md` - `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` --- ## 3. Canonical Variables Used This document depends on the following canonical variables from `04_CANONICAL_NAMING_AND_VARIABLES.md`. ```yaml FRONTEND: FRAMEWORK: "Next.js App Router" PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_LAYOUT_RULE: "All ethiKos pages remain inside the existing Ethikos/global shell." DO_NOT_CREATE_SECOND_SHELL: true DO_NOT_CREATE_KIALO_ROUTE_FAMILY: true DO_NOT_CREATE_KINTSUGI_TOP_LEVEL_APP: true USE_SERVICES_LAYER: true PRIMARY_DELIBERATION_ROUTE: "/ethikos/deliberate/*" PRIMARY_DECISION_ROUTE: "/ethikos/decide/*" PRIMARY_IMPACT_ROUTE: "/ethikos/impact/*" PRIMARY_ADMIN_ROUTE: "/ethikos/admin/*" PRIMARY_TRUST_ROUTE: "/ethikos/trust/*" PRIMARY_PULSE_ROUTE: "/ethikos/pulse/*" PRIMARY_LEARN_ROUTE: "/ethikos/learn/*" PRIMARY_INSIGHTS_ROUTE: "/ethikos/insights" CURRENT_ENDPOINTS_CANONICAL: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" LEGACY_OR_PROBLEMATIC_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ```` --- ## 4. Current Frontend Reality The ethiKos frontend already has a real route surface. The Kintsugi upgrade MUST target the existing route families: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` The Kintsugi upgrade MUST NOT replace this surface with older conceptual routes such as: ```txt /debate /consult /reputation /platforms/konnaxion/ethikos/korum /platforms/konnaxion/ethikos/konsultations /platforms/konnaxion/ethikos/kintsugi ``` Those may appear in strategic or public documentation only if clearly marked as conceptual or future-facing. --- ## 5. Frontend Architecture Principles ### 5.1 Preserve the existing shell All ethiKos pages MUST remain inside the existing Konnaxion global layout and ethiKos module shell. The implementation contract is: ```txt App Router route -> /ethikos segment layout -> MainLayout -> ethiKos watermark/context -> Ant Design App provider -> EthikosPageShell -> Page content ``` Do not create: ```txt KintsugiShell KialoShell KorumShell KonsultationsShell SmartVoteShell ``` unless a future ADR explicitly approves it. ### 5.2 Preserve the module page wrapper All ethiKos pages SHOULD use: ```tsx import EthikosPageShell from '@/app/ethikos/EthikosPageShell'; ``` The page shell owns: * page title; * subtitle/helper text; * optional meta title; * optional section label; * primary action; * secondary actions; * central content width; * consistent spacing. Individual pages MUST NOT define their own large competing header outside the shell. ### 5.3 Preserve the service layer Frontend API access MUST go through service modules. Allowed pattern: ```txt page/component -> hook/service -> request helper -> /api/... ``` Forbidden pattern: ```txt page/component -> raw fetch('/api/...') ``` Raw fetches inside page components are allowed only for explicitly documented legacy exceptions. ### 5.4 Preserve one coherent UX External civic-tech inspirations MUST be translated into native ethiKos components. For example: | Source pattern | Frontend expression | | --------------------------- | ----------------------------------------------------------------------- | | Kialo argument map | `ArgumentTreeView` under `/ethikos/deliberate/*` | | Consider.it pro/con reasons | structured reason capture inside Deliberate | | Loomio proposals | decision protocol UI inside Decide | | Citizen OS drafting | draft/versioning UI inside Decide or a bounded ethiKos drafting surface | | Decidim accountability | tracker/outcomes UI inside Impact | | CONSUL thresholds | eligibility/threshold UI inside Decide/Admin | | DemocracyOS proposal debate | proposal-centric discussion inside Decide/Deliberate | Do not create separate frontend apps for these sources. --- ## 6. Route-Family Contract ## 6.1 Decide ### Canonical route family ```txt /ethikos/decide/* ``` ### Current routes ```txt /ethikos/decide/elite /ethikos/decide/public /ethikos/decide/results /ethikos/decide/methodology ``` ### Kintsugi role Decide owns the frontend surfaces for: * decision protocols; * public ballots; * elite/expert decision views; * methodology explanations; * Smart Vote reading display; * result publication; * comparison of baseline vs declared readings. ### Allowed patterns Decide MAY mimic: * Loomio proposal lifecycle; * CONSUL proposal thresholds; * DemocracyOS proposal-centered debate; * Smart Vote result publication; * EkoH-informed reading explanations. ### Required frontend posture Decide pages MUST distinguish: ```txt raw stance/ballot baseline result Smart Vote reading EkoH context ``` Decide pages MUST NOT imply that EkoH directly votes. ### Preferred component names ```txt DecisionProtocolPanel DecisionRecordCard PublicBallotPanel EliteDecisionPanel ReadingComparisonTable BaselineResultCard SmartVoteReadingCard MethodologyExplainer EligibilityNotice ``` --- ## 6.2 Deliberate ### Canonical route family ```txt /ethikos/deliberate/* ``` ### Current routes ```txt /ethikos/deliberate/elite /ethikos/deliberate/[topic] /ethikos/deliberate/guidelines ``` ### Kintsugi role Deliberate owns Korum’s frontend surfaces: * topic-level deliberation; * structured arguments; * pro/con mapping; * Kialo-style claim graph; * Consider.it-style reason capture; * argument sources; * claim impact voting; * suggested claims; * role-aware discussion controls; * moderation visibility. ### Kialo-style scope Kialo-style features MUST live inside `/ethikos/deliberate/*`. They MUST NOT create: ```txt /kialo /ethikos/kialo /api/kialo konnaxion.kialo ``` ### Required conceptual mapping ```txt Kialo Discussion -> EthikosTopic Kialo Claim -> EthikosArgument Kialo Pro/Con edge -> EthikosArgument.parent + EthikosArgument.side Kialo Source -> ArgumentSource Kialo Impact Vote -> ArgumentImpactVote Kialo Suggested Claim -> ArgumentSuggestion ``` ### Required vote separation Deliberate pages MUST distinguish: | Concept | Range | Meaning | | -------------------- | -------: | ----------------------------------------- | | `EthikosStance` | `-3..+3` | user stance on topic | | `ArgumentImpactVote` | `0..4` | impact of an argument/claim on its parent | | `ReadingResult` | variable | Smart Vote derived reading | ### Preferred component names ```txt ArgumentTreeView ArgumentNodeCard ArgumentMinimap ArgumentSourcesPanel ArgumentImpactVoteControl GuidedVotingDrawer SuggestedClaimsPanel DiscussionSettingsPanel ParticipantRoleSettings AnonymousModeBanner DeliberationGuidelinesPanel TopicPreviewDrawer ``` ### Known issue The current visible bug: ```txt BUG_001 = Deliberate preview drawer shows "Preview / No data" ``` This is a targeted bugfix item. It MUST NOT be used as justification for a route redesign or new data model unless a later investigation proves that a model addition is required. --- ## 6.3 Trust ### Canonical route family ```txt /ethikos/trust/* ``` ### Current routes ```txt /ethikos/trust/profile /ethikos/trust/badges /ethikos/trust/credentials ``` ### Kintsugi role Trust owns frontend visibility for: * EkoH-informed profile signals; * expertise credentials; * ethics/trust markers; * participation credibility indicators; * badge or credential display. ### Required boundaries Trust MAY display EkoH-derived context. Trust MUST NOT: * display EkoH as a voting engine; * imply that expertise automatically overrides baseline votes; * expose sensitive EkoH details beyond visibility permissions; * mix private scoring internals into public decision screens without a declared lens or visibility rule. ### Preferred component names ```txt TrustProfileCard ExpertiseCredentialList EthicsContextPanel BadgeGrid CohortEligibilityBadge SnapshotContextNotice ``` --- ## 6.4 Pulse ### Canonical route family ```txt /ethikos/pulse/* ``` ### Current routes ```txt /ethikos/pulse/overview /ethikos/pulse/live /ethikos/pulse/health /ethikos/pulse/trends ``` ### Kintsugi role Pulse owns civic health and live participation signals: * participation volume; * topic activity; * deliberation health; * argument balance; * stance distribution; * trend lines; * live decision/process state. ### Required boundaries Pulse MAY aggregate signals from ethiKos, Smart Vote readings, and EkoH context. Pulse MUST NOT become the source of truth for decisions. Pulse dashboards are interpretive views, not canonical records. ### Preferred component names ```txt PulseOverviewDashboard LiveParticipationPanel DeliberationHealthCard TrendLineChart ArgumentBalanceMeter StanceDistributionChart CivicSignalFeed ``` --- ## 6.5 Impact ### Canonical route family ```txt /ethikos/impact/* ``` ### Current routes ```txt /ethikos/impact/feedback /ethikos/impact/outcomes /ethikos/impact/tracker ``` ### Kintsugi role Impact owns accountability surfaces: * implementation tracking; * outcome reporting; * feedback loops; * public accountability snapshots; * follow-through state after decisions. ### Required boundary correction Impact may currently have loose frontend mappings to KeenKonnect project data. Kintsugi must treat this as a temporary or legacy adapter pattern. Canonical Kintsugi ownership is: ```txt Impact truth -> ethiKos / Konsultations Project execution handoff -> KeenKonnect ``` Impact MUST NOT be documented as owned by KeenKonnect. ### Preferred component names ```txt ImpactTrackerTable OutcomeCard FeedbackPanel AccountabilityTimeline ImplementationStatusBadge PublicReceiptPanel HandoffLinkCard ``` --- ## 6.6 Learn ### Canonical route family ```txt /ethikos/learn/* ``` ### Current routes ```txt /ethikos/learn/changelog /ethikos/learn/glossary /ethikos/learn/guides ``` ### Kintsugi role Learn owns public explanation: * Kintsugi methodology; * glossary; * user guides; * change log; * meaning of readings/lenses; * difference between stance, ballot, impact vote, and reading; * public explanation of Smart Vote and EkoH boundaries. ### Required boundaries Learn pages may explain external inspirations, but must not imply direct dependency or merged external code. ### Preferred component names ```txt GlossaryList GuideSection MethodologyGuide KintsugiExplainer ReadingLensExplainer ChangeLogTimeline ``` --- ## 6.7 Insights ### Canonical route ```txt /ethikos/insights ``` ### Kintsugi role Insights owns analytical interpretation: * reading comparison; * cross-module civic analytics; * topic-level signal interpretation; * cohort views; * Smart Vote result comparison; * EkoH-contextualized analytics where declared. ### Required boundaries Insights MAY compose data from: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/kollective/votes/ ``` Insights MUST use service wrappers. Insights MUST NOT embed raw aggregation fetches directly inside page components. ### Preferred component names ```txt ReadingComparisonDashboard CohortSignalChart TopicInsightCard SmartVoteLensTable BaselineVsWeightedPanel ExpertiseContextChart ``` --- ## 6.8 Admin ### Canonical route family ```txt /ethikos/admin/* ``` ### Current routes ```txt /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles ``` ### Kintsugi role Admin owns governance controls: * audit views; * moderation views; * participant roles; * permission management; * visibility controls; * Kialo-style role settings; * anonymous participation controls; * suggested-claim approval queues. ### Required boundaries Admin MAY expose privileged views that normal participants cannot see. Admin MUST NOT leak anonymous identities to non-admin users. ### Preferred component names ```txt AuditLogTable ModerationQueue RoleMatrix VisibilitySettingsPanel SuggestedClaimApprovalQueue AnonymousParticipationControls AdminOnlyIdentityPanel ``` --- ## 7. Shell and Layout Contract ## 7.1 Segment layout The `/ethikos/*` segment layout is responsible for: * wrapping ethiKos content in `MainLayout`; * preserving the global app navigation; * defaulting sidebar context to ethiKos when absent; * providing Ant Design `App` context; * applying the ethiKos watermark; * providing a Suspense fallback. Pages MUST NOT duplicate this behavior. ## 7.2 Page shell `EthikosPageShell` is responsible for: * visible page title; * subtitle; * meta title; * optional inferred section label; * primary action; * secondary actions; * content max width. Pages SHOULD NOT render a competing top-level `h1` outside `EthikosPageShell`. ## 7.3 Page container `PageContainer`, `ProCard`, tables, lists, cards, forms, and charts may be used inside `EthikosPageShell`. Recommended nesting: ```tsx {/* page content */} ``` If a page already uses a safe existing layout pattern, preserve it unless there is a specific alignment task. --- ## 8. Service-Layer Contract All new frontend data access MUST go through service wrappers. ### 8.1 Canonical services ```txt services/ethikos services/deliberate services/decide services/impact services/learn services/admin services/pulse ``` Existing service names MAY be preserved even if their internal endpoint mapping needs cleanup. ### 8.2 Service function naming Use descriptive verbs: ```txt fetchTopic fetchTopics fetchTopicDetail fetchTopicPreview createTopic submitStance submitArgument submitArgumentImpactVote fetchArgumentTree submitSuggestedClaim fetchDecisionRecords submitPublicVote fetchReadingResults fetchImpactTracker patchImpactStatus fetchAuditLog fetchModerationQueue ``` Avoid names that import external product names into canonical service APIs: ```txt fetchKialoTree submitKialoVote fetchLoomioProposal fetchDecidimProcess submitConsulThreshold ``` ### 8.3 Request helper Services SHOULD use the existing request helper pattern. Preferred structure: ```txt frontend/services/.ts -> import { get, post, patch, put, del } from './_request' -> call canonical API path without duplicating global base logic ``` ### 8.4 API path policy Services SHOULD call canonical backend endpoints: ```txt ethikos/topics/ ethikos/stances/ ethikos/arguments/ ethikos/categories/ kollective/votes/ ``` Services MUST NOT expand use of: ```txt home/* api/home/* ``` If a legacy path exists, it must be: * documented; * isolated; * scheduled for replacement; * not reused in new Kintsugi components. --- ## 9. API Alignment Contract Frontend code MUST preserve these canonical API meanings: | Frontend concept | Canonical backend route | | ------------------------ | --------------------------------------------------- | | Topic list/detail | `/api/ethikos/topics/` | | Topic stance | `/api/ethikos/stances/` | | Topic argument | `/api/ethikos/arguments/` | | Category/glossary source | `/api/ethikos/categories/` | | Kollective vote | `/api/kollective/votes/` | | Smart Vote reading | future `ReadingResult` endpoint, defined later | | Kialo-style impact vote | future `ArgumentImpactVote` endpoint, defined later | | Suggested claim | future `ArgumentSuggestion` endpoint, defined later | Do not generate frontend code against undefined endpoints unless the endpoint is marked as proposed and assigned to the relevant backend contract. --- ## 10. State Management and Fetching Existing pages may use the currently established project patterns, including: * React local state; * `useMemo`; * `useState`; * `useEffect`; * React Query where already used; * `ahooks/useRequest` where already used; * service wrappers. ### Rules * Data loading must have explicit loading state. * Empty collections must render explicit empty states. * Failed service calls must surface recoverable UI when possible. * Mutation success should invalidate or refresh related queries. * Mutation failure should not silently fail. * Page components should not perform cross-domain aggregation directly; aggregation belongs in services or backend endpoints. --- ## 11. Ant Design and Notification Contract The ethiKos layout provides Ant Design `App` context. Pages MAY use: ```tsx const { message, modal, notification } = App.useApp(); ``` Pages MUST NOT mount their own duplicate `App` provider. Pages SHOULD avoid the deprecated static message pattern where the contextual `App.useApp()` pattern is available. --- ## 12. Styling and Design-System Contract Frontend Kintsugi work MUST use the current Konnaxion UI stack. Allowed: * Ant Design; * Ant Design Pro Components; * existing shared layout components; * existing shared chart/card/table components; * module page shells; * current theme context. Forbidden unless explicitly approved: * new global CSS framework; * Tailwind introduction; * duplicate theme provider; * duplicate sidebar/navigation system; * isolated micro-frontend styling; * raw unscoped CSS that overrides global Konnaxion behavior. --- ## 13. Kialo-Style Frontend Contract Kialo-style frontend work belongs under `/ethikos/deliberate/*`. ### 13.1 Required native-mimic posture ```yaml KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_FRONTEND_ROUTE: false CREATE_KIALO_BACKEND_APP: false IMPORT_KIALO_CODE: false ``` ### 13.2 First-pass surfaces First-pass Kialo-style components MAY include: ```txt ArgumentTreeView ArgumentNodeCard ArgumentSourcesPanel ArgumentImpactVoteControl SuggestedClaimsPanel ParticipantRoleSettings DiscussionSettingsPanel AnonymousModeBanner TopicBackgroundPanel ``` ### 13.3 Deferred surfaces The following are deferred unless explicitly moved into first-pass scope: ```txt ArgumentMinimapSunburst DiscussionTemplateClonePanel DiscussionExportPanel SmallGroupModePanel CrossDiscussionClaimLinker ClaimExtractionPanel CustomPerspectiveBuilder ``` ### 13.4 Kialo-style anti-drift Do not: * rename `EthikosArgument` to `Claim`; * create `/kialo` routes; * create `KialoPageShell`; * create `services/kialo`; * treat argument impact votes as topic stances; * treat argument impact votes as Smart Vote ballots; * expose anonymous identities to non-admins; * publish suggester-submitted claims without approval. --- ## 14. Smart Vote / EkoH Frontend Contract Smart Vote and EkoH must be represented carefully in the frontend. ### 14.1 Smart Vote frontend role Smart Vote UI displays: * baseline results; * declared readings; * lens explanations; * result comparisons; * publication state; * reproducibility/audit context. Smart Vote UI MUST NOT imply that Smart Vote mutates raw facts. ### 14.2 EkoH frontend role EkoH UI displays: * expertise context; * ethics context; * cohort eligibility; * snapshot context; * trust/credential signals. EkoH UI MUST NOT imply that EkoH directly casts votes. ### 14.3 Required frontend distinctions Any page showing decision outputs SHOULD distinguish: ```txt Baseline result Declared Smart Vote reading EkoH context/snapshot Raw user stance or ballot ``` Preferred labels: ```txt Baseline Reading Lens Snapshot Expertise context Ethics context ``` Avoid ambiguous labels: ```txt weighted truth EkoH vote expert vote final authority ``` --- ## 15. Drafting Frontend Contract Drafting is a bounded Kintsugi capability. Potential frontend surfaces: ```txt DraftWorkspace DraftVersionTimeline AmendmentPanel RationalePacketViewer DraftComparisonView ``` Drafting MAY appear under Decide or a future bounded ethiKos route if approved. Until an ADR approves a route, do not invent: ```txt /ethikos/draft /ethikos/drafting /ethikos/citizenos ``` Docs may describe drafting conceptually, but implementation routes must be confirmed before frontend generation. --- ## 16. Legacy and Loose Mapping Contract The current graph contains loose mappings and legacy endpoints. ### 16.1 `/api/home/*` Kintsugi frontend work MUST NOT expand `/api/home/*`. Any remaining `/api/home/*` call should be classified as: ```txt legacy needs isolation candidate for replacement not canonical ``` ### 16.2 Deliberate preview `fetchTopicPreview` may currently map loosely onto topic data. The frontend contract is: ```txt TopicPreviewDrawer expects a stable TopicPreviewPayload. The service layer owns any transformation from current backend topic data to the preview payload. The page should not hard-code fallback transformations if the service can own them. ``` ### 16.3 Impact / KeenKonnect loose mapping If Impact currently maps to KeenKonnect project data, classify it as a temporary adapter. Kintsugi frontend documentation must present Impact as ethiKos/Konsultations accountability. KeenKonnect may be shown as an execution handoff target, not the canonical Impact owner. --- ## 17. Accessibility and Responsiveness All new ethiKos frontend work SHOULD: * preserve keyboard navigation; * use semantic headings inside shell structure; * ensure tables have row keys and accessible labels; * ensure charts have readable labels or summaries; * avoid color-only status communication; * preserve mobile/responsive behavior; * avoid layout overflow in tree/graph views; * provide fallback empty states for missing data. Argument maps and tree views SHOULD include non-visual navigation alternatives such as list view, outline view, or searchable claim list. --- ## 18. Loading, Empty, and Error States Each Kintsugi frontend surface MUST define: ```txt loading state empty state error state success state when applicable permission denied state when applicable ``` Recommended copy pattern: | State | Requirement | | ----------------- | ------------------------------------------------------------------- | | Loading | Show section-specific loading message | | Empty | Explain what is missing and how to create it | | Error | Provide retry or fallback when possible | | Permission denied | Explain that the user lacks access, without leaking restricted data | | Partial data | Mark incomplete panels explicitly | The preview drawer bug demonstrates why silent or generic “No data” states are insufficient for Kintsugi UX. --- ## 19. Permission and Visibility Contract Frontend visibility must respect role and anonymity rules. ### Required Kialo-style visibility variables ```yaml KIALO_ROLES: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" KIALO_ANONYMITY_MODES: - "standard" - "anonymous" KIALO_AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" KIALO_VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" ``` ### Frontend rules * Admin-only identity fields must not render for normal participants. * Anonymous participation must be visibly marked without revealing identity. * Suggested claims must show approval state. * Role-limited actions must be disabled or hidden consistently. * Permission-denied responses must not leak restricted metadata. --- ## 20. Frontend Testing Contract Frontend changes for Kintsugi SHOULD include or preserve tests for: * route rendering; * shell wrapping; * service call paths; * empty states; * error states; * topic detail loading; * argument submission; * stance submission; * decision result rendering; * preview drawer payload handling; * admin/moderation visibility; * no accidental `/api/home/*` expansion. Minimum smoke coverage SHOULD verify that the main ethiKos surfaces render without crashing: ```txt /ethikos/decide/public /ethikos/decide/results /ethikos/deliberate/[topic] /ethikos/impact/tracker /ethikos/insights /ethikos/admin/moderation ``` --- ## 21. File Placement Rules ### Existing page routes Existing App Router pages remain under: ```txt frontend/app/ethikos/ ``` ### Shared ethiKos components New reusable ethiKos components SHOULD live in one of the established frontend locations depending on current repo convention. Acceptable locations include: ```txt frontend/app/ethikos/ frontend/modules/ethikos/ frontend/components/ ``` The chosen location must avoid duplication and should follow the nearest existing pattern. ### Service wrappers New service logic SHOULD live under: ```txt frontend/services/ ``` Preferred files: ```txt frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/learn.ts frontend/services/admin.ts ``` Do not create external-source service files such as: ```txt frontend/services/kialo.ts frontend/services/loomio.ts frontend/services/decidim.ts ``` unless a future annex ADR explicitly approves it. --- ## 22. Frontend Review Checklist Before accepting any frontend Kintsugi change, verify: ```txt [ ] The route remains under /ethikos/*. [ ] The page uses the existing ethiKos/global shell. [ ] The page does not define a duplicate large header outside EthikosPageShell. [ ] The page does not create a new shell, theme, or navigation system. [ ] API calls go through services/*. [ ] New API calls use canonical /api/ethikos/* or approved endpoints. [ ] No new /api/home/* usage was added. [ ] Kialo-style features remain under /ethikos/deliberate/*. [ ] Smart Vote is shown as readings, not source mutation. [ ] EkoH is shown as context, not voting. [ ] Stance, impact vote, ballot, and reading are distinct in UI copy. [ ] Empty/error/loading states are explicit. [ ] Permission and anonymity rules are respected. [ ] New component names use canonical naming. [ ] The change does not introduce deferred OSS features as first-pass scope. ``` --- ## 23. Non-Goals This frontend contract does not authorize: * a new `/kialo` frontend app; * a new `/kintsugi` frontend app; * a new global layout; * a second theme system; * importing external OSS frontend code; * implementing Polis/LiquidFeedback/OpenSlides first-pass UI; * replacing REST with GraphQL/WebSockets; * creating backend models from frontend assumptions; * changing current route families; * treating the preview drawer bug as architecture justification. --- ## 24. Anti-Drift Rules ```yaml FRONTEND_ANTI_DRIFT_RULES: - "Do not create a second shell." - "Do not create KintsugiShell." - "Do not create KialoShell." - "Do not create /kialo routes." - "Do not create /ethikos/kialo routes." - "Do not replace /ethikos/* with conceptual public-doc routes." - "Do not bypass the services layer." - "Do not add raw fetches inside page components unless explicitly documented." - "Do not expand /api/home/*." - "Do not rename /api/ethikos/* to /api/deliberation/*." - "Do not treat Kialo impact votes as stances." - "Do not treat Smart Vote readings as source facts." - "Do not present EkoH as a voting engine." - "Do not use external OSS names as canonical internal component prefixes." - "Do not generate implementation backlog inside this contract." ``` --- ## 25. Related Documents | File | Relationship | | ----------------------------------------------- | ---------------------------------------------- | | `00_KINTSUGI_START_HERE.md` | Entry point and reading order | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Source priority and drift resolution | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Korum/Konsultations/Smart Vote/EkoH boundaries | | `04_CANONICAL_NAMING_AND_VARIABLES.md` | Naming constants used by this file | | `05_CURRENT_STATE_BASELINE.md` | Current frontend/backend reality | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route-specific upgrade plan | | `07_API_AND_SERVICE_CONTRACTS.md` | API/service call details | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Smart Vote/EkoH frontend interpretation | | `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` | Payload shapes expected by frontend services | | `15_BACKEND_ALIGNMENT_CONTRACT.md` | Backend-side counterpart | | `16_TEST_AND_SMOKE_CONTRACT.md` | Test expectations | | `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` | Known bugs and exclusions | | `20_AI_GENERATION_GUARDRAILS.md` | AI-specific guardrails | | `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` | Kialo-style Deliberate contract | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Future task format | --- ## 26. Final Canonical Assertion The frontend Kintsugi upgrade strengthens the existing ethiKos surface. The canonical frontend surface remains: ```txt /ethikos/* ``` The canonical shell remains: ```txt MainLayout -> ethiKos segment layout -> Ant Design App context -> EthikosPageShell ``` The canonical API access pattern remains: ```txt page/component -> service wrapper -> /api/... ``` Kialo-style patterns belong under: ```txt /ethikos/deliberate/* ``` Smart Vote readings belong primarily under: ```txt /ethikos/decide/* /ethikos/insights ``` EkoH context belongs primarily under: ```txt /ethikos/trust/* /ethikos/insights ``` Impact/accountability belongs under: ```txt /ethikos/impact/* ``` The Kintsugi frontend update is not a new app, not a new shell, and not a direct OSS frontend merge. It is a native alignment and strengthening of the existing ethiKos frontend. ``` Sources used for alignment: current ethiKos layout and shell implementation, route inventory, service/API conventions, shell-nesting rules, endpoint graph, and Kintsugi boundary rules. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2} :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4} ``` --- ## V4.1 reusable EkoH frontend Canonical EkoH data access moves to `frontend/services/ekoh.ts`. Reusable display belongs under `frontend/modules/ekoh/components/`. Ethikos may wrap these components with question-specific Smart Vote context, but generic EkoH components MUST NOT import Smart Vote. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 0d8cb40757b0a194f95e3d93852291a1b15b34c91a3b98e30c2e7c8a0db682f6 CONTENT_BYTES: 43515 ================================================================================================ # 15 — Backend Alignment Contract **File:** `15_BACKEND_ALIGNMENT_CONTRACT.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Normative backend contract for Kintsugi implementation planning **Last aligned:** 2026-04-25 **Purpose:** Prevent backend drift while extending ethiKos for the Kintsugi upgrade. --- ## 1. Purpose This document defines the backend alignment contract for the ethiKos Kintsugi upgrade. It fixes how backend work must be designed, named, routed, migrated, tested, and integrated so that future implementation does not drift into: * invented Django apps; * invented API prefixes; * renamed canonical models; * accidental Smart Vote mutation of upstream facts; * EkoH becoming a voting engine; * Kialo-style features becoming a separate backend module; * direct foreign-tool writes into ethiKos core tables; * backend changes that conflict with the current Konnaxion codebase. This file is a **backend guardrail**, not an implementation backlog. --- ## 2. Scope This contract covers: * Django app ownership; * REST API routing; * ViewSet / Serializer / Router conventions; * model naming and migration rules; * permission and authentication rules; * service-layer expectations; * Smart Vote / EkoH boundaries; * Kialo-style backend extension rules; * testing and smoke expectations; * anti-drift rules for future AI/code generation. This contract does **not** define: * full model field specifications; * final serializer payload shapes; * frontend implementation; * exact migration files; * Smart Vote formulas; * EkoH scoring formulas; * Kialo UI behavior; * OSS code-reading conclusions. Those belong in related documents listed at the end. --- ## 3. Source Basis The current backend snapshot identifies the backend as a Django / DRF codebase with a central API router and a `konnaxion.ethikos` app. The backend volume includes `backend/config/api_router.py`, Django settings files, and local apps including `konnaxion.ethikos`, `konnaxion.ekoh`, and `konnaxion.smart_vote`. The existing contracts file states that Ethikos uses the `konnaxion.ethikos` backend app exposed under `/api/ethikos/...`, with core endpoints for topics, stances, arguments, and optional categories. The Kintsugi boundaries document fixes the ownership model: Korum owns debate topics, arguments, stance scale and moderation; Konsultations owns consultations, intake, ballots, result snapshots and impact tracking; Smart Vote owns readings and must be read-only on upstream facts; EkoH owns expertise/ethics context and is not the voting engine. --- ## 4. Canonical Variables Used ```yaml id="m2voyl" DOCUMENT_ID: "15_BACKEND_ALIGNMENT_CONTRACT" DOCUMENT_ROLE: "Backend implementation alignment contract" PROJECT_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" BACKEND_FRAMEWORK: "Django + Django REST Framework" DEFAULT_API_STYLE: "DRF ViewSet + Serializer + Router" PRIMARY_BACKEND_APP: "konnaxion.ethikos" PRIMARY_API_PREFIX: "/api/ethikos/" ROOT_URLCONF: "config.urls" API_ROUTER_FILE: "backend/config/api_router.py" AUTH_USER_MODEL: "users.User" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_ETHIKOS_VIEWSETS: - "CategoryViewSet" - "TopicViewSet" - "StanceViewSet" - "ArgumentViewSet" CURRENT_CANONICAL_ENDPOINTS: - "/api/ethikos/topics/" - "/api/ethikos/stances/" - "/api/ethikos/arguments/" - "/api/ethikos/categories/" COMPATIBILITY_ENDPOINT_PREFIXES: - "/api/deliberate/..." - "/api/deliberate/elite/..." KINTSUGI_BACKEND_POLICY: BREAK_EXISTING_MODELS: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_FIELDS: false ADD_NON_BREAKING_TABLES_ALLOWED: true ADD_NON_BREAKING_FIELDS_ALLOWED: true FULL_OSS_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false SMART_VOTE_POLICY: MUTATES_KORUM_RECORDS: false MUTATES_KONSULTATIONS_RECORDS: false WRITES_ONLY_DERIVED_ARTIFACTS: true EKOH_POLICY: IS_VOTING_ENGINE: false PROVIDES_CONTEXT_ONLY: true KIALO_POLICY: CREATE_BACKEND_APP: false IMPORT_CODE: false EXTEND_ETHIKOS_APP: true ``` --- ## 5. Backend Platform Baseline The backend stack is: ```txt id="xelgqr" Django Django REST Framework PostgreSQL Celery Redis Cookiecutter-Django-style layout ``` The repository includes: ```txt id="o2fy7a" backend/config/settings/base.py backend/config/settings/local.py backend/config/settings/production.py backend/config/settings/test.py backend/config/api_router.py backend/config/urls.py backend/konnaxion/ethikos/ backend/konnaxion/ekoh/ backend/konnaxion/smart_vote/ ``` The Kintsugi backend must extend this stack. It must not introduce a parallel API framework or a second backend architecture. --- ## 6. Canonical Django App Ownership ### 6.1 Current canonical backend app ```txt id="chx1vm" konnaxion.ethikos ``` This app owns the current Ethikos core: ```txt id="jbnmga" EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` ### 6.2 Target ownership boundaries | Capability | Backend ownership | | ---------------------------------- | ---------------------------------------------------------------------------- | | Debate topics | `konnaxion.ethikos` | | Topic-level stances | `konnaxion.ethikos` | | Arguments / threaded reasons | `konnaxion.ethikos` | | Argument moderation | `konnaxion.ethikos` | | Kialo-style claim graph extensions | `konnaxion.ethikos` | | Consultation intake | `konnaxion.ethikos`, future Konsultations namespace inside Ethikos if needed | | Ballot capture | `konnaxion.ethikos`, target Konsultations capability | | Decision records | `konnaxion.ethikos` unless later split is explicitly approved | | Smart Vote readings | `konnaxion.smart_vote` or existing Kollective Intelligence Smart Vote app | | EkoH expertise/ethics context | `konnaxion.ekoh` | | KeenKonnect execution handoff | `konnaxion.keenkonnect` | | External OSS artifacts | adapter tables only, not core table writes | ### 6.3 Forbidden backend apps in first pass ```txt id="k0ts4l" konnaxion.kialo konnaxion.kintsugi konnaxion.considerit konnaxion.loomio konnaxion.decidim konnaxion.consul konnaxion.democracyos ``` External tools may inform models, serializers, and service design, but the first-pass implementation is **native mimic**, not a backend app import. --- ## 7. Current Ethikos Backend Core The current Ethikos backend core must be treated as stable. ### 7.1 Current models | Model | Current meaning | Kintsugi mapping | | ----------------- | ----------------------------- | -------------------------------------------------------------- | | `EthikosCategory` | Topic grouping | Category / taxonomy seed | | `EthikosTopic` | Debate or consultation prompt | Korum discussion container; possible Konsultations topic proxy | | `EthikosStance` | User topic-level stance | Raw stance event, `-3..+3` | | `EthikosArgument` | Threaded discussion entry | Kialo-style claim node | The contracts file defines `EthikosTopic`, `EthikosStance`, `EthikosArgument`, and `EthikosCategory` as the current visualized Ethikos entities, including topic status, stance range, argument side/parent threading, and category fields. ### 7.2 Current route registration The current `backend/konnaxion/ethikos/urls.py` registers: ```python id="8xf0i8" router.register(r"topics", TopicViewSet, basename="ethikos-topic") router.register(r"stances", StanceViewSet, basename="ethikos-stance") router.register(r"arguments", ArgumentViewSet, basename="ethikos-argument") ``` It conditionally registers: ```python id="g97fpr" router.register(r"categories", CategoryViewSet, basename="ethikos-category") ``` The backend snapshot confirms this router structure. ### 7.3 Current ViewSet style The current ViewSet style is DRF-native: ```txt id="0fli2k" TopicViewSet = ModelViewSet StanceViewSet = GenericViewSet + Create/Update/Retrieve/List mixins ArgumentViewSet = ModelViewSet CategoryViewSet = optional / read-only where implemented ``` The backend snapshot shows `TopicViewSet`, `StanceViewSet`, and `ArgumentViewSet` using DRF permissions and `perform_create` ownership assignment. --- ## 8. API Prefix Contract ### 8.1 Canonical API prefix All current Ethikos core CRUD must remain under: ```txt id="ha59kv" /api/ethikos/ ``` Canonical endpoints: ```txt id="lrl0gu" /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` ### 8.2 Compatibility aliases The following are compatibility aliases, not separate source-of-truth APIs: ```txt id="h3oydu" /api/deliberate/... /api/deliberate/elite/... ``` ### 8.3 Forbidden first-pass API prefixes The Kintsugi first pass must not introduce: ```txt id="ymluyi" /api/kintsugi/ /api/kialo/ /api/korum/ /api/consultations/ /api/konsultations/ /api/deliberation/ ``` unless a later migration plan explicitly defines the prefix, ownership, routing, tests, and backwards compatibility. ### 8.4 Legacy endpoint rule ```txt id="hiydwy" /api/home/* ``` must not be expanded. If existing frontend code still touches `/api/home/*`, the backend plan must treat it as legacy and route cleanup work, not a Kintsugi foundation. --- ## 9. Router Alignment Contract All new Kintsugi backend endpoints must use the existing router pattern. ### Required pattern ```python id="oa7hfg" from rest_framework.routers import DefaultRouter router = DefaultRouter() router.register(r"", , basename="") urlpatterns = router.urls ``` ### Central registration rule If a new endpoint is intended to be public under `/api/...`, it must be registered through the existing project API routing structure, not via an ad-hoc URL file bypass. ### Basename rules Basenames must be: * stable; * lowercase; * hyphenated; * app-scoped where useful; * not tied to OSS source names. Good: ```txt id="r87zjl" ethikos-decision-record ethikos-reading-result ethikos-draft ethikos-argument-source ethikos-argument-impact-vote ``` Bad: ```txt id="r4n7xw" kialo-claim loomio-proposal decidim-process consul-vote kintsugi-object ``` --- ## 10. Model Alignment Contract ### 10.1 Current models must not be renamed The following are frozen names: ```txt id="xt9rrj" EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` ### 10.2 Conceptual mappings are allowed Future docs may describe these mappings: ```txt id="igc27v" EthikosTopic = Discussion / thesis container EthikosArgument = Claim EthikosStance = Topic-level stance event EthikosCategory = Category / taxonomy seed ``` But code generation must not rename the current models. ### 10.3 Non-breaking additions are allowed Kintsugi may add new tables if they are non-breaking and owned correctly. Candidate target models include: ```txt id="f6hjfe" DecisionProtocol DecisionRecord LensDeclaration ReadingResult Draft DraftVersion Amendment RationalePacket ImpactTrack ImpactUpdate ExternalArtifact ProjectionMapping ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` ### 10.4 Model names must describe Ethikos concepts, not copied OSS concepts Use: ```txt id="nao95s" ArgumentSource ArgumentImpactVote ArgumentSuggestion DecisionRecord ImpactTrack ``` Avoid: ```txt id="ydksyk" KialoClaim LoomioPoll DecidimProposal ConsulDebate DemocracyOSForum ``` OSS names may appear in documentation as source patterns, not model names. --- ## 11. Serializer Alignment Contract Every new writable model must have an explicit serializer. ### Serializer requirements A serializer must define: * model; * fields; * read-only fields; * write-only fields where needed; * validation rules; * ownership/user assignment behavior if applicable; * cross-object consistency checks. ### Existing pattern to preserve The current `EthikosArgumentSerializer` exposes `parent` as read-only and accepts `parent_id` as write-only, then validates that a parent argument belongs to the same topic. This pattern is important for Kialo-style argument graph extensions. ### Required future validation patterns | Serializer | Required validation | | ------------------------------ | ------------------------------------------------------------------------------------------- | | `ArgumentSourceSerializer` | Source must belong to an argument in the same topic context | | `ArgumentImpactVoteSerializer` | Vote must target an existing argument; value must be in allowed range | | `ArgumentSuggestionSerializer` | Suggested claim must be tied to a topic and reviewed before publication if role requires it | | `DecisionRecordSerializer` | Decision must reference a valid topic/consultation and protocol | | `ReadingResultSerializer` | Reading must reference lens, snapshot, input scope, and computed timestamp | | `DraftVersionSerializer` | Draft version must belong to its draft and preserve immutable version history | | `ImpactTrackSerializer` | Impact item must reference decision or consultation source | ### Serializer anti-drift rules ```txt id="71b0ac" Do not serialize Smart Vote readings as if they were EthikosStance rows. Do not serialize Kialo-style impact votes as EthikosStance rows. Do not expose anonymous author identity fields to non-admin serializers. Do not accept foreign-tool payloads that write directly into core Korum/Konsultations tables. ``` --- ## 12. ViewSet Alignment Contract ### 12.1 Default ViewSet style Use DRF ViewSets. Default: ```python id="swe1jx" class ResourceViewSet(viewsets.ModelViewSet): queryset = Resource.objects.all() serializer_class = ResourceSerializer permission_classes = [...] ``` Read-only resources may use: ```python id="ttzmvg" class ResourceViewSet(viewsets.ReadOnlyModelViewSet): ... ``` Limited writable resources may use: ```python id="m3dloe" class ResourceViewSet( mixins.CreateModelMixin, mixins.ListModelMixin, mixins.RetrieveModelMixin, viewsets.GenericViewSet, ): ... ``` ### 12.2 Ownership assignment For user-owned objects, ownership must be assigned in `perform_create`, not trusted from client payload. Good: ```python id="jyl5us" def perform_create(self, serializer): serializer.save(user=self.request.user) ``` or: ```python id="8apex0" def perform_create(self, serializer): serializer.save(created_by=self.request.user) ``` The existing Ethikos ViewSets already follow this pattern for topics, stances, and arguments. ### 12.3 Queryset filtering ViewSets should implement explicit filtering for scoped resources. Examples: ```txt id="cj42tk" topic user status category decision draft reading_key snapshot_ref ``` Filtering must not leak private, anonymous, or admin-only data. --- ## 13. Permissions Contract ### 13.1 Default permission baseline Current Ethikos ViewSets use: ```txt id="udkv63" IsAuthenticatedOrReadOnly IsAuthenticated ``` The backend snapshot shows topic and argument ViewSets using authenticated-or-read-only permissions, while stances require authentication. ### 13.2 Required permission categories Future Kintsugi backend work must distinguish: | Permission class | Use | | ------------------- | ---------------------------------------------------------- | | Public read | Published topics, public results, public readings | | Authenticated write | stance, argument, suggestion, ballot | | Owner edit | own arguments, own drafts, own suggestions where allowed | | Moderator edit | hide arguments, accept/reject suggestions | | Admin edit | roles, visibility, audit controls | | System write | computed readings, scheduled aggregation, snapshot refresh | ### 13.3 Anonymous participation rule Anonymous participation may hide identity from normal participants. It must not erase auditability. Backend must preserve: ```txt id="x8fxf4" real_user_id or audit principal public_author_label visibility mode admin-only identity access ``` ### 13.4 Forbidden permission behavior ```txt id="kzru2d" Do not trust client-submitted user IDs. Do not expose anonymous identities to normal participants. Do not allow Smart Vote to mutate source Ethikos records. Do not allow foreign-tool adapters to write core table facts directly. Do not publish suggested claims without review when role requires approval. ``` --- ## 14. Authentication Contract Backend code must use: ```txt id="c0yvrc" settings.AUTH_USER_MODEL get_user_model() request.user ``` It must not import or depend on: ```txt id="yicbvl" django.contrib.auth.models.User ``` unless only used in a migration-safe, explicitly justified legacy context. The broader technical instructions identify the custom user model as `users.User`, so new backend work must remain compatible with that user model. --- ## 15. Migration Contract ### 15.1 General migration policy Kintsugi backend changes must be additive by default. Allowed: ```txt id="70e2mm" Add new tables. Add nullable fields. Add fields with safe defaults. Add indexes. Add constraints after data migration if needed. Add read-only projections. ``` Forbidden unless explicitly approved: ```txt id="15m4ba" Rename current Ethikos models. Rename current fields used by frontend/services. Drop existing columns. Change endpoint semantics without compatibility. Change stance range. Change argument side semantics. Convert existing IDs to UUIDs in-place. ``` ### 15.2 Existing EkoH migration note The current stable baseline includes the EkoH migration `0002...` as created and applied. Future docs must not re-open that migration as an unresolved baseline issue. ### 15.3 Migration file requirements Every migration plan must specify: ```txt id="i1mlkr" Django app model/table added or changed nullable/default behavior index impact data migration need rollback risk test command affected serializers affected ViewSets affected frontend service ``` ### 15.4 Makemigrations drift prevention Before generating migrations, implementation work must verify: ```txt id="o0oyhl" python manage.py makemigrations --check python manage.py migrate --plan python manage.py test ``` or the equivalent project command. --- ## 16. Korum Backend Contract Korum is not a separate Django app in the first pass. It is the Kintsugi name for the structured debate capabilities inside ethiKos. ### Owned facts ```txt id="mzr6xn" EthikosTopic EthikosStance EthikosArgument ArgumentSource ArgumentImpactVote ArgumentSuggestion ModerationAction ``` ### Korum rules ```txt id="id9pcq" Korum facts are source facts. Korum arguments and stances may feed Smart Vote readings. Korum facts must not be overwritten by Smart Vote. Korum arguments may be extended with Kialo-style claim graph support. Korum moderation must be auditable. ``` ### Kialo-style backend mapping | Kialo-style concept | Backend mapping | | ------------------- | -------------------------------------------------------------- | | Discussion | `EthikosTopic` | | Thesis | existing topic title/description, future optional thesis field | | Claim | `EthikosArgument` | | Pro/con relation | `EthikosArgument.parent` + `EthikosArgument.side` | | Source | `ArgumentSource` | | Impact vote | `ArgumentImpactVote` | | Suggested claim | `ArgumentSuggestion` | | Participant role | `DiscussionParticipantRole` | | Visibility setting | `DiscussionVisibilitySetting` | ### Kialo backend forbidden outputs ```txt id="ckff5j" Do not create konnaxion.kialo. Do not import Kialo code. Do not rename EthikosArgument to Claim. Do not use Kialo impact votes as EthikosStance. Do not use Kialo impact votes as Smart Vote ballots. ``` --- ## 17. Konsultations Backend Contract Konsultations is a submodule/capability under ethiKos. It is not currently confirmed as a fully independent backend app. ### Target owned facts ```txt id="asfxcw" IntakeSubmission IntakeQueue ProblemStatement BallotEvent ResultSnapshot ImpactTrack ImpactUpdate ``` ### Current baseline rule If current code represents a consultation through `EthikosTopic` and `EthikosStance`, documentation must say so explicitly. ### Future implementation rule If a distinct Konsultations model set is introduced, it must: * live inside `konnaxion.ethikos` unless a later ADR says otherwise; * preserve compatibility with existing topic/stance behavior; * separate ballot capture from Smart Vote readings; * provide audit records for result snapshots and impact tracking. --- ## 18. Smart Vote Backend Contract Smart Vote belongs to Kollective Intelligence, not to Korum. The backend snapshot includes Smart Vote service code and EkoH/Smart Vote integration settings. The settings add `konnaxion.ekoh` and `konnaxion.smart_vote`, and include periodic Celery schedules for EkoH recalculation, contextual analysis, and Smart Vote aggregation. ### Smart Vote may write ```txt id="mo67kw" LensDeclaration ReadingResult VoteResult Breakdown artifacts Aggregation audit rows ``` ### Smart Vote must not write ```txt id="gxur77" EthikosTopic EthikosStance EthikosArgument Konsultations source ballots Korum moderation facts ``` ### Reading formula Any weighted or filtered reading must be reproducible: ```txt id="iam0pn" Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?) ``` This formula is fixed by the boundaries document. ### Required Smart Vote fields Future Smart Vote reading models must include or map to: ```txt id="v2r7mr" reading_key lens_hash lens_declaration snapshot_ref computed_at results_payload input_scope algorithm_version ``` --- ## 19. EkoH Backend Contract EkoH owns expertise and ethics context. It is not the voting engine. ### EkoH may provide ```txt id="23rkrh" expertise domain vectors ethics multipliers cohort eligibility snapshot references audit context profile/context serializers periodic score recalculation ``` ### EkoH must not provide ```txt id="5b1fvg" source ballots topic stance mutation argument mutation decision publication authority baseline result ownership ``` ### EkoH integration rule When EkoH affects a result, it must do so through a declared Smart Vote lens or reading, not by changing baseline Korum/Konsultations facts. --- ## 20. Drafting Backend Contract Drafting is a bounded ethiKos capability. It must not be embedded directly into Korum argument rows. ### Target models ```txt id="kviyla" Draft DraftVersion Amendment RationalePacket ``` ### Drafting rules ```txt id="gxd5v6" Drafts may reference topics, consultations, or decision records. Draft versions are append-only. Amendments must be structured. Rationale packets must preserve why text changed. Drafting must not overwrite original arguments or stances. ``` ### Suggested route ownership Until a later API contract defines otherwise, Drafting backend endpoints should remain under: ```txt id="mlh7mw" /api/ethikos/ ``` Possible future resource names: ```txt id="o1aqpt" /api/ethikos/drafts/ /api/ethikos/draft-versions/ /api/ethikos/amendments/ ``` These are target-state candidates, not current baseline endpoints. --- ## 21. Impact Backend Contract Impact is a Konsultations/accountability capability. Current endpoint graph analysis identified loose mappings from Impact frontend services into KeenKonnect project APIs. Kintsugi target state must clarify that KeenKonnect may receive execution handoffs, but civic accountability truth belongs to ethiKos/Konsultations. ### Target owned facts ```txt id="qyhtdm" ImpactTrack ImpactUpdate ExecutionHandoff PublicAccountabilitySnapshot ``` ### Impact rules ```txt id="o5gwsx" ImpactTrack must reference a decision, consultation, or result snapshot. Impact updates must preserve timestamp and responsible actor. Handoffs into KeenKonnect must be links, not ownership transfer of civic truth. Public accountability snapshots must be reproducible from source records. ``` --- ## 22. External Tool Boundary Contract External OSS tools are pattern sources only in first pass. ### First-pass strategy ```txt id="4fb8vy" Consider.it = mimic Kialo-style = mimic Loomio = mimic Citizen OS = mimic Decidim = mimic CONSUL Democracy = mimic DemocracyOS = mimic ``` ### Deferred ```txt id="t661ya" Polis LiquidFeedback All Our Ideas Your Priorities OpenSlides ``` ### Adapter-only future boundary If a future annex is approved, it must use: ```txt id="zcqgwt" ExternalArtifact ProjectionMapping ``` Foreign tools must not write directly to: ```txt id="rbfjb4" EthikosTopic EthikosStance EthikosArgument BallotEvent DecisionRecord ImpactTrack ``` --- ## 23. Admin Registration Contract Every new backend model must define whether it appears in Django admin. ### Required admin decision For each model, specify: ```txt id="v1173z" admin_registered: true | false admin_readonly_fields list_display search_fields list_filter raw_id_fields audit_visibility ``` ### Admin-sensitive objects The following should generally be admin-visible: ```txt id="hes6ap" DecisionRecord LensDeclaration ReadingResult ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ModerationAction ImpactTrack ExternalArtifact ProjectionMapping ``` ### Sensitive admin rule Anonymous identity mappings and EkoH audit context must be admin-restricted. --- ## 24. Service-Layer Contract Backend domain logic must not be overloaded into serializers or ViewSets when it becomes non-trivial. ### Use services for ```txt id="8fimbz" Smart Vote aggregation EkoH weight lookup reading computation decision closing/publication draft version creation amendment application impact snapshot generation external artifact projection moderation action recording ``` ### Service module pattern Preferred structure: ```txt id="7pn5d5" backend/konnaxion/ethikos/services/ backend/konnaxion/smart_vote/services/ backend/konnaxion/ekoh/services/ ``` The current backend already uses service modules for EkoH and Smart Vote, including `weight_calculator.py` under Smart Vote services. ### Service anti-drift rule ```txt id="wn9tm9" Do not put weighted voting algorithms in EthikosArgumentSerializer. Do not put EkoH score calculations in Ethikos ViewSets. Do not put draft versioning rules directly in frontend code. Do not put complex moderation side effects only in page components. ``` --- ## 25. Transaction and Integrity Contract Backend operations must preserve data integrity. ### Transaction-required operations Use database transactions for: ```txt id="uxgypv" closing a decision publishing a reading creating a draft version accepting an amendment accepting an argument suggestion into an argument casting or replacing a Smart Vote ballot updating aggregated result rows creating impact snapshot records ``` ### Uniqueness constraints to consider Future models should consider uniqueness for: ```txt id="cs78or" EthikosStance: user + topic ArgumentImpactVote: user + argument DiscussionParticipantRole: user + topic/discussion ReadingResult: reading_key + input_scope + lens_hash + snapshot_ref DraftVersion: draft + version_number DecisionRecord: decision_key or topic + protocol + opened_at ``` Do not add constraints blindly; each must be validated against existing data and documented in the migration plan. --- ## 26. Audit Contract Kintsugi backend changes must preserve auditability. ### Minimum audit fields Where applicable: ```txt id="ww3fvm" created_at updated_at created_by updated_by computed_at published_at source_snapshot_ref lens_hash algorithm_version audit_payload ``` ### Audit event candidates ```txt id="cygb2x" TopicCreated StanceRecorded ArgumentCreated ArgumentHidden ArgumentSourceAttached ArgumentImpactVoteRecorded ArgumentSuggestionSubmitted ArgumentSuggestionAccepted ArgumentSuggestionRejected DraftCreated DraftVersionCreated AmendmentSubmitted DecisionOpened DecisionClosed ReadingComputed ReadingPublished ImpactUpdated ModerationActionRecorded ExternalArtifactProjected ``` ### Audit anti-drift rules ```txt id="f0jqmb" Do not make weighted readings unreproducible. Do not lose the original source event. Do not overwrite baseline result rows with lens results. Do not delete moderation history when hiding content. Do not erase identity mapping required for admin audit in anonymous participation. ``` --- ## 27. Test Contract ### 27.1 Existing test state The current `backend/konnaxion/ethikos/tests.py` is only a stub in the snapshot. Kintsugi backend work must add real tests as backend capabilities expand. ### 27.2 Required test categories Each new backend resource should include tests for: ```txt id="v65z72" model creation serializer validation permission behavior ViewSet list/retrieve/create/update ownership assignment filtering behavior invalid payload rejection cross-topic parent/child validation migration application admin registration where applicable ``` ### 27.3 Ethikos regression tests Must preserve: ```txt id="xmgu85" create topic create stance update stance create argument create reply with valid parent_id reject reply when parent belongs to another topic hide/moderate argument if supported list arguments by topic ``` ### 27.4 Smart Vote / EkoH boundary tests Must verify: ```txt id="b3oifx" Smart Vote readings do not mutate EthikosStance. Smart Vote readings do not mutate EthikosArgument. EkoH context is referenced through snapshot/context fields. Baseline result can be reproduced without weighted lens. Weighted reading stores lens/snapshot metadata. ``` ### 27.5 Kialo-style tests Must verify: ```txt id="2xd7dw" ArgumentImpactVote range is 0..4. ArgumentImpactVote is not accepted as EthikosStance. ArgumentSource belongs to an argument. ArgumentSuggestion requires review when role is suggester. Anonymous author visibility is enforced. ``` --- ## 28. API Documentation Contract Every new backend endpoint must be documented in: ```txt id="aoz24h" 07_API_AND_SERVICE_CONTRACTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 15_BACKEND_ALIGNMENT_CONTRACT.md if backend convention changes ``` Endpoint docs must specify: ```txt id="lsh5yj" method path ViewSet serializer request payload response payload permission class filter params pagination error behavior ownership source-of-truth status ``` ### OpenAPI / schema rule If the project uses DRF Spectacular/OpenAPI generation, new ViewSets and serializers must be schema-friendly: ```txt id="xmqmgo" explicit fields explicit serializer classes no undocumented dynamic payloads stable enum values stable read/write field separation ``` --- ## 29. Environment and Settings Contract Kintsugi backend work must not add untracked settings. Any new setting must specify: ```txt id="h6qm99" setting name default value environment variable if any local behavior production behavior test behavior security implications ``` Existing EkoH / Smart Vote integration settings already define app additions, Celery beat schedules, database search path, and Kafka bootstrap configuration. ### Settings anti-drift rules ```txt id="ep8wqt" Do not add hardcoded production values. Do not add settings only in local.py. Do not add Celery schedules without documenting owner and cadence. Do not add Kafka/event settings unless implementation actually uses them. ``` --- ## 30. Background Tasks Contract Background tasks may be used for: ```txt id="z93fva" EkoH score recalculation Smart Vote aggregation reading recomputation impact snapshot refresh reporting/analytics refresh ``` They must not be used as a substitute for missing transactional writes. ### Task requirements Each task must document: ```txt id="yz307h" task name owning app input scope idempotency rule schedule if periodic retry behavior side effects audit output ``` --- ## 31. Error Handling Contract Backend errors must remain DRF-compatible. ### Required patterns ```txt id="g20gqg" 400 for validation errors 401 for unauthenticated writes 403 for forbidden actions 404 for missing resources or inaccessible resources where appropriate 409 for conflict/idempotency collision where explicitly implemented 500 only for unexpected errors ``` ### Error shape Use DRF-standard error shapes unless a future API contract defines a project-wide envelope. Example: ```json id="af9gs4" { "parent_id": ["The parent belongs to another topic."] } ``` or: ```json id="tvf3a0" { "detail": "You do not have permission to perform this action." } ``` --- ## 32. Pagination and Filtering Contract List endpoints should use DRF-compatible pagination and explicit query filters. Recommended filters by resource: | Resource | Filters | | --------------------- | --------------------------------------------------------------- | | Topics | `status`, `category`, `created_by`, `expertise_category` | | Stances | `topic`, `user` where allowed | | Arguments | `topic`, `parent`, `side`, `is_hidden` where admin | | Argument sources | `argument`, `topic` | | Argument impact votes | `argument`, `topic`, `user` where allowed | | Suggestions | `topic`, `status`, `submitted_by` | | Decisions | `topic`, `status`, `protocol` | | Readings | `reading_key`, `topic`, `decision`, `lens_hash`, `snapshot_ref` | | Drafts | `topic`, `decision`, `status` | | Impact tracks | `decision`, `status`, `owner` | Filtering must not leak hidden, anonymous, admin-only, or draft-only information. --- ## 33. Versioning Contract The Kintsugi first pass must use current API versioning conventions. Do not invent: ```txt id="pkt551" /api/v2/ethikos/ /api/v1/kintsugi/ /api/graphql/ ``` unless a future ADR and API migration plan explicitly approve it. ### Version fields inside records For derived/computed outputs, prefer record-level versioning fields: ```txt id="5qrt57" algorithm_version schema_version lens_version snapshot_version ``` instead of changing endpoint version prematurely. --- ## 34. Security Contract Backend implementation must preserve: ```txt id="8tl8h9" authentication for writes owner checks admin-only moderation controls anonymous identity protection auditability no client-submitted authority fields no direct external writes into core facts ``` ### Sensitive fields Sensitive fields must be hidden from public serializers unless explicitly authorized: ```txt id="1p8rh7" internal user ID in anonymous mode EkoH private score components raw ethics sub-scores admin moderation notes hidden argument content lens internals if not public external adapter credentials ``` --- ## 35. Data Privacy Contract Kintsugi backend additions must distinguish: | Data class | Visibility | | ----------------------------- | ----------------------------------------------- | | Public topic | public | | Public argument | public | | Hidden argument | moderator/admin | | Anonymous public label | public | | Anonymous real identity | admin/audit only | | User stance | user/admin or aggregated public depending route | | Baseline result | public when published | | Smart Vote reading | public when published | | EkoH private score components | restricted | | Draft in progress | restricted until published | | Impact snapshot | public when published | --- ## 36. Backend-to-Frontend Alignment Backend resources must align with frontend service contracts. ### Required matching docs Every backend endpoint added or changed must be reflected in: ```txt id="n84xgz" 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md ``` ### Service wrapper rule The frontend must call backend endpoints through service wrappers. Backend docs should therefore name the expected frontend service owner: ```txt id="1m6v7l" frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/admin.ts ``` or whichever current service file is actually used. --- ## 37. First-Pass Backend Priorities This contract does not create a backlog, but it defines likely backend priority areas for future backlog generation. ### Stabilize existing core ```txt id="oyodnx" EthikosTopic API EthikosStance API EthikosArgument API EthikosCategory API topic preview service/API shape argument filtering by topic ``` ### Add Kialo-style minimum backend support ```txt id="a6952o" ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` ### Add decision/readings support ```txt id="9v941e" DecisionProtocol DecisionRecord LensDeclaration ReadingResult ``` ### Add drafting/accountability support ```txt id="nj3zbo" Draft DraftVersion Amendment RationalePacket ImpactTrack ImpactUpdate ``` These are target candidates only. The final backlog belongs in: ```txt id="e0ndzj" 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 38. Non-Goals This backend contract does not: * generate migrations; * generate model code; * generate serializers; * generate ViewSets; * define final field lists; * define Smart Vote formulas; * define EkoH score logic; * define frontend components; * define product copy; * import OSS code; * propose a full external merge. --- ## 39. Anti-Drift Rules Future backend generation must obey: ```txt id="deks5l" Do not create a new backend app for Kialo. Do not create a new backend app for Kintsugi. Do not import OSS backend code. Do not rename EthikosTopic. Do not rename EthikosStance. Do not rename EthikosArgument. Do not rename EthikosCategory. Do not change EthikosStance range from -3..+3. Do not treat ArgumentImpactVote as EthikosStance. Do not treat Smart Vote ReadingResult as a source ballot. Do not let Smart Vote mutate Korum/Konsultations source facts. Do not let EkoH become the voting engine. Do not write foreign tool data directly into Korum/Konsultations core tables. Do not expand /api/home/*. Do not invent /api/kintsugi/*. Do not invent /api/kialo/*. Do not skip serializers for new resources. Do not skip tests for new backend behavior. Do not create implementation tasks inside this document. ``` --- ## 40. Required Backend Review Checklist Before any Kintsugi backend PR, verify: ```txt id="l72ww0" [ ] Does this preserve /api/ethikos/* as the canonical Ethikos API prefix? [ ] Does this preserve current Ethikos models? [ ] Does this use DRF ViewSet + Serializer + Router conventions? [ ] Does this assign ownership from request.user, not client payload? [ ] Does this avoid direct OSS-code import? [ ] Does this avoid creating konnaxion.kialo? [ ] Does this preserve Smart Vote read-only behavior on upstream facts? [ ] Does this preserve EkoH as context, not voting engine? [ ] Does this avoid expanding /api/home/*? [ ] Does this include migrations if models changed? [ ] Does this include tests? [ ] Does this update API/payload/frontend contract docs if endpoint shapes changed? [ ] Does this preserve anonymous/audit separation where applicable? [ ] Does this document target-state vs current-state clearly? ``` --- ## 41. Related Documents This backend contract must be read with: ```txt id="ceflir" 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 42. Final Contract Statement The Kintsugi backend implementation must extend the existing Django/DRF backend, especially `konnaxion.ethikos`, without replacing the current Ethikos core. The current backend truth is: ```txt id="z6plfs" App: konnaxion.ethikos API prefix: /api/ethikos/ Current models: EthikosCategory, EthikosTopic, EthikosStance, EthikosArgument Current pattern: DRF ViewSet + Serializer + Router Compatibility aliases: /api/deliberate/... and /api/deliberate/elite/... ``` The Kintsugi backend may add non-breaking models, serializers, ViewSets, services, tasks, and audit records. It must not rename the current core, import OSS systems, create a Kialo backend app, or allow Smart Vote/EkoH/external tools to mutate Korum/Konsultations source facts. --- ## V4.1 EkoH rating-access resolver All backend consumers that disclose individual EkoH rating data MUST use `konnaxion.ekoh.services.rating_access.resolve_rating_access`. Modules MUST NOT infer EkoH access from strings such as CEO, manager, supervisor, or Ethikos role labels. EkoH remains self-contained apart from the configured user model and generic external scope identifiers. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 08158e3ee2a0fa1296a97ff5a8d440d379fb6cd1a499f3bfb46f52324ccf1185 CONTENT_BYTES: 28262 ================================================================================================ # 16 — Test and Smoke Contract **Document ID:** `16_TEST_AND_SMOKE_CONTRACT.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical testing contract **Last aligned:** 2026-04-25 **Primary scope:** ethiKos Kintsugi upgrade validation **Implementation mode:** Documentation-first, partial native mimic, no full external merge --- ## 1. Purpose This document defines the minimum test, smoke, and regression contract for the ethiKos Kintsugi upgrade. The goal is to ensure that every Kintsugi implementation step preserves the existing stable baseline while adding new civic deliberation, decision, Smart Vote, EkoH, impact, and Kialo-style argument-mapping capabilities. This document prevents test drift by defining: - what must continue to work; - what must be tested before and after each Kintsugi implementation slice; - what belongs in backend tests; - what belongs in frontend smoke tests; - what belongs in API contract tests; - what belongs in migration drift tests; - what must not be treated as optional once a Kintsugi feature is implemented. --- ## 2. Scope This contract applies to: ```txt /ethikos/* /api/ethikos/* /api/kollective/* konnaxion.ethikos konnaxion.kollective_intelligence konnaxion.ekoh frontend/app/ethikos/* frontend/services/* frontend/smoke/* backend/tests/* ```` It covers the following Kintsugi route families: ```txt id="91qzk8" /ethikos/deliberate/* /ethikos/decide/* /ethikos/impact/* /ethikos/pulse/* /ethikos/trust/* /ethikos/admin/* /ethikos/learn/* /ethikos/insights ``` It also covers Kintsugi-specific test obligations for: ```txt id="emk8eo" Korum Konsultations Smart Vote EkoH Kialo-style argument mapping Mimic-vs-annex boundaries Legacy endpoint containment ``` --- ## 3. Canonical Variables Used ```yaml id="39p7mx" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true CURRENT_BASELINE: FRONTEND_BUILD_WORKS: true PLAYWRIGHT_SMOKE_RAN_SUCCESSFULLY: true BACKEND_LOCAL_STARTUP_WORKS_WITH_UV: true AUTH_CSRF_CATEGORY_TOPIC_CREATION_FIXED: true ARGUMENT_POSTING_WORKS: true EKOH_MIGRATION_0002_CREATED_AND_APPLIED: true REMAINING_VISIBLE_ETHIKOS_BUG: "Deliberate preview drawer shows 'Preview / No data'" PRIMARY_ROUTE_SURFACE: "/ethikos/*" CURRENT_ETHIKOS_ENDPOINTS: TOPICS: "/api/ethikos/topics/" STANCES: "/api/ethikos/stances/" ARGUMENTS: "/api/ethikos/arguments/" CATEGORIES: "/api/ethikos/categories/" CURRENT_COMPAT_ENDPOINTS: DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." RELATED_ENDPOINTS: KOLLECTIVE_VOTES: "/api/kollective/votes/" LEGACY_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "ballots" - "consultation results" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" VOTE_TYPE_SEPARATION: ETHIKOS_STANCE_RANGE: "-3..+3" KIALO_IMPACT_VOTE_RANGE: "0..4" SMART_VOTE_READING_IS_DERIVED: true KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_IMPACT_VOTE_IS_TOPIC_STANCE: false KIALO_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ``` --- ## 4. Non-goals This document does not define the full implementation backlog. It also does not require: * complete production-grade load testing in the first Kintsugi pass; * browser coverage for every visual state; * full external OSS integration tests; * tests against imported Kialo, Loomio, Decidim, CONSUL, Citizen OS, Consider.it, or DemocracyOS code; * full annex/sidecar test suites; * replacing current tests with a new test framework; * changing the existing route surface to make testing easier. The purpose is to stabilize the current Konnaxion testing contract before implementation tasks are generated. --- ## 5. Current Stable Baseline The following baseline is considered already achieved and must not regress: ```yaml id="6gpx48" frontend_build: "working" playwright_smoke: "passed" backend_local_startup_with_uv: "working" auth_csrf_category_topic_creation: "fixed" argument_posting: "working" ekoh_migration_0002: "created_and_applied" known_open_bug: "Deliberate preview drawer shows Preview / No data" ``` This baseline means the Kintsugi upgrade may proceed as documentation and architecture work, but every implementation slice must preserve these guarantees. --- ## 6. Test Layers Kintsugi validation is divided into five layers. ```txt id="efztd8" Layer 1 — Build and static validation Layer 2 — Backend unit/API tests Layer 3 — Frontend smoke/navigation tests Layer 4 — Cross-layer contract tests Layer 5 — Kintsugi domain invariant tests ``` Each layer has a different purpose. | Layer | Purpose | Required before merge | | ----------------- | ------------------------------------------------------- | ------------------------- | | Build/static | Detect syntax/type/package breakage | Yes | | Backend API | Validate models, serializers, permissions, endpoints | Yes | | Frontend smoke | Validate route render and navigation health | Yes | | Contract | Validate payload shape and service/API alignment | Yes for changed routes | | Domain invariants | Validate Korum/Konsultations/Smart Vote/EkoH boundaries | Yes for Kintsugi features | --- ## 7. Minimum Commands The exact command names may vary by environment, but the following categories are required. ### 7.1 Backend local startup ```bash id="mwm1re" cd backend uv run python manage.py check uv run python manage.py migrate uv run python manage.py runserver ``` ### 7.2 Backend tests ```bash id="e4s35n" cd backend uv run pytest ``` If a narrower target is needed: ```bash id="1sk7z7" cd backend uv run pytest backend/tests/ uv run pytest backend/tests/test_smoke_platform.py ``` ### 7.3 Frontend build ```bash id="9b5nd5" cd frontend npm run build ``` ### 7.4 Frontend smoke ```bash id="m1s3p0" cd frontend npx playwright test frontend/smoke/smoke.spec.ts ``` Or, if the project script wraps Playwright: ```bash id="zhx9tz" cd frontend npm run smoke ``` ### 7.5 Migration drift check ```bash id="bs4oz2" cd backend uv run python manage.py makemigrations --check --dry-run ``` This command is mandatory before considering Kintsugi schema work stable. --- ## 8. Backend Smoke Contract ### 8.1 Existing backend smoke expectations The backend smoke suite must confirm that the platform can: ```txt id="e79w8d" Start Django Load URL routing Authenticate or create a test user Access basic API documentation/admin paths where applicable Create or retrieve EthikosCategory Create or retrieve EthikosTopic POST EthikosStance POST EthikosArgument POST or validate Kollective vote endpoint when available Run without migration drift ``` ### 8.2 Required Ethikos API smoke paths The following endpoints must remain smoke-covered: ```txt id="lzcqoe" GET /api/ethikos/topics/ POST /api/ethikos/topics/ GET /api/ethikos/topics/{id}/ GET /api/ethikos/categories/ POST /api/ethikos/categories/ GET /api/ethikos/stances/ POST /api/ethikos/stances/ GET /api/ethikos/arguments/ POST /api/ethikos/arguments/ ``` ### 8.3 Required compatibility smoke paths Compatibility routes must be tested if they remain registered: ```txt id="1xs4wf" GET /api/deliberate/... GET /api/deliberate/elite/... ``` These tests may be lightweight. Their goal is not to duplicate all canonical endpoint tests, but to ensure that compatibility aliases do not silently break. ### 8.4 Required Kollective / Smart Vote smoke path The current decision/vote path must remain validated where available: ```txt id="j9160n" GET or POST /api/kollective/votes/ ``` If the endpoint is optional in the router, the test must distinguish: ```txt id="gk9x1g" Endpoint missing because optional module is not registered = documented skip Endpoint registered but broken = failure Endpoint registered and response < 500 = pass for smoke ``` --- ## 9. Backend Domain Tests ### 9.1 EthikosTopic tests Required assertions: ```txt id="ptmd0j" Can create topic with valid title and description. Can assign category if category exists. Topic status defaults to an allowed value. Topic status only allows known values. Topic has created_by where required. Topic timestamps are set. Topic can be listed through API. Topic can be retrieved through API. ``` ### 9.2 EthikosCategory tests Required assertions: ```txt id="o1109x" Can create category. Category name is stable. Category can be associated to topics. Category list endpoint works. ``` ### 9.3 EthikosStance tests Required assertions: ```txt id="fkf1n2" Can create stance for user/topic. Stance value accepts values from -3 to +3. Stance value rejects values outside -3..+3. One user/topic stance rule is respected if enforced. Stance is not treated as Smart Vote reading. ``` ### 9.4 EthikosArgument tests Required assertions: ```txt id="v3r2ki" Can create argument for topic. Can create pro argument. Can create con argument. Can create neutral argument if supported. Can create reply using parent argument. Can list arguments for topic. Can hide/moderate argument if moderation field exists. Argument posting works through API. ``` ### 9.5 Kialo-style future tests Once Kialo-style models are implemented, the following tests become required: ```txt id="ktb9i4" ArgumentSource can be attached to EthikosArgument. ArgumentImpactVote accepts 0..4 only. ArgumentImpactVote is linked to an argument, not directly to a topic stance. ArgumentSuggestion can be submitted by a suggester role. ArgumentSuggestion requires approval before publication when role is suggester. DiscussionParticipantRole enforces allowed roles. DiscussionVisibilitySetting enforces author/vote visibility enums. Anonymous mode does not expose identity to non-admin participants. ``` --- ## 10. Frontend Smoke Contract ### 10.1 Current smoke behavior The frontend smoke suite should navigate a route, wait for `domcontentloaded`, assert a valid response, assert status `< 400`, and assert the page body is visible. Minimum behavior: ```txt id="qi1q43" page.goto(path, waitUntil='domcontentloaded') response exists status < 400 body is visible logs route status and timing ``` ### 10.2 Required route smoke set The smoke suite must cover at least one route in every ethiKos route family. Minimum set: ```txt id="z6bdns" /ethikos/deliberate/guidelines /ethikos/decide/public /ethikos/decide/results /ethikos/impact/tracker /ethikos/pulse/overview /ethikos/trust/profile /ethikos/learn/glossary /ethikos/insights /ethikos/admin/audit ``` Preferred full ethiKos smoke set: ```txt id="1lfxgn" /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles /ethikos/decide/elite /ethikos/decide/public /ethikos/decide/results /ethikos/decide/methodology /ethikos/deliberate/elite /ethikos/deliberate/guidelines /ethikos/impact/feedback /ethikos/impact/outcomes /ethikos/impact/tracker /ethikos/insights /ethikos/learn/changelog /ethikos/learn/glossary /ethikos/learn/guides /ethikos/pulse/health /ethikos/pulse/live /ethikos/pulse/overview /ethikos/pulse/trends /ethikos/trust/badges /ethikos/trust/credentials /ethikos/trust/profile ``` ### 10.3 Dynamic topic route smoke The dynamic route: ```txt id="wcd5fr" /ethikos/deliberate/[topic] ``` must not be smoke-tested with a fake ID unless the test fixture creates a real topic first. Required pattern: ```txt id="m9nzwz" 1. Create topic through backend API or fixture. 2. Navigate to /ethikos/deliberate/{createdTopicIdOrSlug}. 3. Assert route loads with status < 400. 4. Assert page body is visible. 5. Assert topic title or stable data-testid is visible. ``` ### 10.4 Admin route auth behavior Admin routes may require authentication or admin role. Allowed outcomes must be explicit: ```txt id="qyzybm" Public smoke environment: - admin route may redirect to login only if documented - redirect must not be mistaken for successful admin page render Authenticated smoke environment: - admin route must render with status < 400 - admin shell must be visible ``` The current smoke principle treats redirects to login as failure unless adjusted. Kintsugi tests must choose one mode and document it. --- ## 11. Frontend Shell Smoke Contract All ethiKos pages must remain inside the existing shell structure. Smoke checks SHOULD assert the presence of a stable shell marker, when available: ```txt id="980gd7" MainLayout is present EthikosPageShell is present page title area is present module content is visible no duplicate full-page header is introduced ``` If data-testid markers do not exist yet, this contract recommends adding stable test identifiers: ```tsx id="sr7jsk" data-testid="ethikos-shell" data-testid="ethikos-page-title" data-testid="ethikos-page-content" ``` Required rule: ```txt id="rbnzum" Frontend smoke should validate that route rendering works. Frontend smoke should not depend on fragile visual text unless no better selector exists. ``` --- ## 12. API and Service Contract Tests Every Kintsugi feature must have a service-layer contract. ### 12.1 Service-layer rule Frontend pages SHOULD call APIs through services, not raw page-level fetches. Required test posture: ```txt id="qy0yqj" If a route depends on a backend endpoint, the corresponding frontend service must have a documented payload contract. If a page uses a new Kintsugi endpoint, a service wrapper must exist. If raw fetch is used, it must be legacy or explicitly documented. ``` ### 12.2 Required service contracts The following service contracts must be tested or type-checked as they are introduced: ```txt id="s9lctr" fetchEthikosTopics createEthikosTopic fetchEthikosCategories createEthikosCategory createEthikosStance createEthikosArgument fetchTopicPreview fetchArgumentTree createArgumentSource createArgumentImpactVote submitArgumentSuggestion fetchDecisionRecords createDecisionRecord fetchReadingResults fetchImpactTracks fetchAdminAuditEvents fetchModerationQueue ``` ### 12.3 Legacy endpoint containment Tests SHOULD detect accidental new usage of: ```txt id="f8vhk4" /api/home/* ``` Policy: ```txt id="6kk4qa" Existing /api/home/* usage may be documented as legacy. New Kintsugi work must not add new /api/home/* calls. Tests or static checks should fail on new /api/home/* additions unless explicitly waived. ``` --- ## 13. Korum Test Contract Korum owns deliberation truth. Required Korum tests: ```txt id="ljcaz6" Topic creation Topic listing Topic detail retrieval Stance creation Stance validation -3..+3 Argument creation Argument reply creation Argument side validation Argument moderation/hiding if supported Argument tree retrieval once implemented Argument source attachment once implemented Argument impact vote 0..4 once implemented Suggested claim approval once implemented ``` Korum tests must enforce: ```txt id="jevn3e" Korum records are canonical source facts. Smart Vote cannot mutate Korum records. EkoH cannot mutate Korum records. Foreign tools cannot write directly into Korum core tables. ``` --- ## 14. Konsultations Test Contract Konsultations owns consultation, ballot, result snapshot, and impact tracking truth. Required Konsultations tests once models exist: ```txt id="rewwj0" Intake submission creation Consultation creation Ballot event creation DecisionRecord creation DecisionProtocol validation EligibilityRule validation ImpactTrack creation ImpactUpdate creation Result snapshot creation ``` Before dedicated Konsultations models exist, tests must explicitly document whether the route is: ```txt id="udab5p" Using EthikosTopic as temporary consultation container Using Kollective votes as temporary ballot endpoint Using stub/mock data Not yet wired ``` Stub/mock use must not be confused with canonical Kintsugi completion. --- ## 15. Smart Vote and EkoH Test Contract ### 15.1 Smart Vote tests Smart Vote owns derived readings. Required tests once reading models exist: ```txt id="x6b1ue" Can create LensDeclaration. Can compute or store ReadingResult. ReadingResult includes reading_key. ReadingResult includes lens_hash. ReadingResult includes computed_at. ReadingResult includes results_payload. ReadingResult includes snapshot_ref when EkoH context is used. ReadingResult references topic_id or consultation_id. Baseline reading remains available. Derived reading is clearly separate from baseline. ``` ### 15.2 Smart Vote immutability tests Required invariant: ```txt id="xzub5l" Smart Vote must not mutate upstream Korum/Konsultations facts. ``` Test strategy: ```txt id="rnb2qj" 1. Create source topic/stance/argument or ballot. 2. Compute/store reading. 3. Re-read source records. 4. Assert source records are unchanged. 5. Assert reading exists as derived artifact. ``` ### 15.3 EkoH tests EkoH owns context, not vote mutation. Required tests: ```txt id="jbjign" EkoH snapshot can be referenced by reading. EkoH snapshot is optional for raw baseline reading. EkoH snapshot is required for expertise/ethics-weighted reading. EkoH context does not directly alter raw stance/ballot values. ``` --- ## 16. Kialo-Style Argument Mapping Test Contract Kialo-style mimic belongs under: ```txt id="8zj1ny" /ethikos/deliberate/* ``` It extends Korum. It does not create a separate Kialo module. ### 16.1 Required test distinction Tests must distinguish: ```txt id="9cvb5w" EthikosStance: range: -3..+3 level: topic model: EthikosStance ArgumentImpactVote: range: 0..4 level: argument/claim-to-parent impact proposed model: ArgumentImpactVote Smart Vote Reading: level: derived aggregate proposed model: ReadingResult ``` ### 16.2 Required Kialo-style tests Once implemented: ```txt id="hucd4m" Argument tree renders parent-child relationships. Pro/con/neutral sides render correctly. Argument source can be added, edited, removed if supported. Impact vote accepts 0..4 only. Impact vote does not create or modify EthikosStance. Suggested claim submitted by suggester is not immediately published. Admin/editor can approve suggested claim. Anonymous author identity is hidden from normal participants. Admin can see required moderation metadata. Discussion topology is single_thesis by default unless multi_thesis is explicitly selected. ``` ### 16.3 Required frontend checks ```txt id="tp4ess" ArgumentTreeView renders. ArgumentNodeCard renders. ArgumentSourcesPanel renders when a node has sources. GuidedVotingDrawer does not block base route smoke if not implemented. AnonymousModeBanner appears when anonymous mode is active. SuggestedClaimsPanel is role-aware. ``` --- ## 17. Impact and Accountability Test Contract Impact tracking belongs to ethiKos/Konsultations. Required tests once impact models exist: ```txt id="kpcux5" Can create ImpactTrack linked to DecisionRecord. Can update ImpactTrack status. Impact status accepts allowed values only. ImpactTrack can include public evidence links. ImpactTrack can be displayed under /ethikos/impact/tracker. Impact outcome can be displayed under /ethikos/impact/outcomes. Impact feedback can be submitted under /ethikos/impact/feedback. ``` Allowed impact status values: ```txt id="8m1bg1" planned in_progress blocked completed cancelled ``` Anti-drift invariant: ```txt id="au2gt6" KeenKonnect may receive handoff links later, but KeenKonnect Project is not the canonical civic impact truth for Kintsugi first pass. ``` --- ## 18. Admin, Audit, and Moderation Test Contract Admin routes must verify that governance controls exist. Required tests: ```txt id="62xt1v" Admin audit route renders. Admin moderation route renders. Admin roles route renders. Moderation queue can display arguments or suggested claims. Moderation action can hide or approve relevant artifact if implemented. Role settings enforce allowed values. Anonymous identity visibility follows role rules. Audit events are emitted for critical Kintsugi actions once audit exists. ``` Critical audit event types: ```txt id="rwh8j7" TopicCreated StanceRecorded ArgumentCreated ArgumentUpdated ArgumentHidden ArgumentSourceAttached ArgumentImpactVoteRecorded ArgumentSuggestionSubmitted ArgumentSuggestionAccepted ArgumentSuggestionRejected DecisionOpened DecisionClosed ReadingComputed ImpactUpdated ModerationActionRecorded ``` Audit tests may be added incrementally, but any implemented audit event must be deterministic and testable. --- ## 19. Known Bug Regression Contract ### BUG-001 ```yaml id="48tu3h" title: "Deliberate preview drawer shows 'Preview / No data'" route: "/ethikos/deliberate/[topic]" status: "known_open" classification: "targeted bugfix, not architecture" ``` ### Required test after fix Once the preview drawer is fixed, add a regression test. Expected behavior: ```txt id="eogkqu" Given a real topic exists When the user opens the topic preview drawer Then the drawer displays topic title or summary And the drawer does not display "No data" for a valid topic And the drawer handles missing/invalid topic with an explicit empty/error state ``` ### Required test category ```txt id="0l5ko0" Frontend route/component test OR Playwright smoke extension Service contract test for fetchTopicPreview Backend API test only if a dedicated preview endpoint exists ``` ### Anti-drift rule The preview bug must not be used to redesign the entire route family. --- ## 20. Migration Drift Contract Before and after Kintsugi schema work: ```bash id="3f0w01" uv run python manage.py makemigrations --check --dry-run uv run python manage.py migrate uv run pytest ``` Required assertions: ```txt id="mxtuvt" No unexpected migrations are generated. All committed migrations apply cleanly. EkoH migration 0002 remains stable. New Kintsugi migrations are explicit and named. New models do not alter existing Ethikos core tables destructively. ``` Migration drift failures are blocking. --- ## 21. Test Data and Fixtures Kintsugi tests should use predictable fixtures. ### 21.1 Required baseline fixtures ```txt id="kzjgyh" test_user admin_user ethikos_category ethikos_topic ethikos_open_topic ethikos_closed_topic ethikos_stance ethikos_argument ethikos_argument_reply ``` ### 21.2 Required future fixtures ```txt id="b24yxf" argument_source argument_impact_vote argument_suggestion decision_protocol decision_record lens_declaration reading_result ekoh_snapshot_ref impact_track moderation_action ``` ### 21.3 Fixture rules ```txt id="n9tbdd" Fixtures must not rely on production IDs. Fixtures must not rely on external OSS services. Fixtures must create records through canonical models or APIs. Fixtures must not bypass invariants unless explicitly testing invalid data. ``` --- ## 22. CI Gate Contract The following checks are required for any Kintsugi implementation PR: ```txt id="fw9m5f" Backend check passes. Backend migrations apply. Backend makemigrations dry-run has no unexpected changes. Backend tests pass. Frontend build passes. Frontend smoke passes. Changed route has at least one smoke or contract test. Changed endpoint has at least one API test. Changed model has migration and model test. Changed payload shape is documented. ``` Optional but recommended: ```txt id="m1hqa6" Frontend typecheck Frontend lint Storybook build Visual regression for key Ethikos routes Coverage report ``` --- ## 23. First-Pass Required Test Matrix | Area | Required before Kintsugi implementation | Required after implementation | | ---------------- | ------------------------------------------ | ----------------------------------------- | | Build | frontend build, backend check | unchanged | | Smoke | current Playwright route smoke | all route families covered | | Ethikos API | topics, categories, stances, arguments | same plus new Korum endpoints | | Deliberate | route loads | topic preview fixed, argument tree tested | | Decide | route loads | decision protocol/result tested | | Results | route loads | baseline vs reading tested | | Impact | route loads | impact tracker tested | | Admin | route loads/auth behavior documented | audit/moderation/roles tested | | Smart Vote | optional vote endpoint behavior documented | reading result tested | | EkoH | migration 0002 stable | snapshot reference tested | | Kialo-style | not imported | native mimic tests only | | Legacy endpoints | known `/api/home/*` use documented | no new `/api/home/*` use | --- ## 24. Acceptance Criteria A Kintsugi implementation slice may be considered test-complete only when: ```txt id="sn8mib" 1. Existing baseline still passes. 2. No unexpected migrations are generated. 3. Changed backend endpoints have API tests. 4. Changed frontend routes have smoke or component coverage. 5. Changed service payloads are documented and validated. 6. Korum/Konsultations/Smart Vote/EkoH ownership is preserved. 7. Vote-type separation is preserved. 8. Legacy /api/home/* usage is not expanded. 9. Known preview drawer bug is either still documented or covered by regression test after fix. 10. No full external OSS merge or Kialo module is introduced. ``` --- ## 25. Anti-Drift Rules ```txt id="plzj51" Do not treat smoke passing as proof of full feature correctness. Do not treat route render as proof of backend contract correctness. Do not add Kintsugi implementation without tests for changed contracts. Do not add models without migration drift checks. Do not add new API endpoints without service-layer alignment. Do not add route-level raw fetches unless explicitly documented. Do not collapse EthikosStance, ArgumentImpactVote, and Smart Vote Reading. Do not test external OSS code in first pass. Do not create tests for imaginary routes. Do not expand /api/home/*. ``` --- ## 26. Related Docs This document depends on: ```txt id="b45qbg" 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 27. Final Contract The Kintsugi test contract is: ```txt id="ozpm9m" Preserve the current stable baseline. Test every changed route, endpoint, model, and payload. Keep smoke tests fast and broad. Keep API tests precise and invariant-driven. Keep Smart Vote and EkoH read/derived boundaries testable. Keep Kialo-style mimic native to /ethikos/deliberate/*. Never allow tests to normalize route, endpoint, or ownership drift. ``` --- ## V4.1 EkoH rating-access smoke matrix Tests MUST cover public, private, self, staff compatibility, direct scope grants, descendant scope grants, cross-department denial, ratings-vs-history detail, profile redaction, and Smart Vote participant-detail filtering. Aggregate baseline/reading arithmetic MUST remain unchanged by display access. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 0830745c08d03d93bad817386d6929de20f08462e8ddeb46e3bc792d374562c3 CONTENT_BYTES: 23385 ================================================================================================ # 17 — Known Bugs and Non-Kintsugi Items **Document ID:** `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Canonical scope-control contract **Audience:** maintainers, frontend implementers, backend implementers, AI assistants, reviewers **Primary purpose:** prevent bugfixing, legacy cleanup, and unrelated implementation work from drifting into the Kintsugi architecture upgrade. --- ## 1. Purpose This document separates: 1. known bugs that may require targeted fixes; 2. technical cleanup items that are real but not part of the Kintsugi architecture definition; 3. deferred features and OSS integrations; 4. non-goals that must not be reintroduced during parallel documentation or implementation work. The Kintsugi upgrade is a **documentation-first architecture upgrade**. It must not become an open-ended bugfixing, refactoring, OSS integration, or frontend rewrite campaign. The clean-slate plan explicitly says the next work should be **Kintsugi planning for Ethikos, not bugfixing**, and identifies the remaining visible ethiKos bug as the Deliberate preview drawer showing “Preview / No data.” --- ## 2. Scope This document covers: * known visible bugs; * known technical risks; * items to defer; * items to classify outside Kintsugi; * anti-drift rules for AI-generated work; * triage categories for future findings. This document does **not** provide implementation fixes. Fixes belong in the implementation backlog only after the documentation pack and code-reading plan are stable. Related implementation details belong to: ```txt 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 3. Canonical Variables Used ```yaml DOCUMENT_ID: "17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" DOCS_BEFORE_CODE: true BUGFIXING_IS_NOT_PRIMARY_SCOPE: true IMPLEMENTATION_BACKLOG_AFTER_DOCS: true PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_API_SURFACE: - "/api/ethikos/*" - "/api/kollective/*" KNOWN_OPEN_VISIBLE_BUG: BUG_ID: "BUG-001" TITLE: "Deliberate preview drawer shows 'Preview / No data'" CLASSIFICATION: "targeted_bugfix_not_architecture" STATUS: "known_open" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false LEGACY_API_EXPANSION_ALLOWED: false NEW_KIALO_MODULE_ALLOWED: false NEW_KINTSUGI_ROUTE_FAMILY_ALLOWED: false ``` --- ## 4. Current Stable Baseline The following baseline is accepted and must not be repeatedly re-litigated in Kintsugi documentation sessions: ```yaml CURRENT_BASELINE: FRONTEND_BUILD_WORKS: true PLAYWRIGHT_SMOKE_RAN_SUCCESSFULLY: true BACKEND_LOCAL_STARTUP_WORKS_WITH_UV: true AUTH_FIXED: true CSRF_FIXED: true CATEGORY_CREATION_FIXED: true TOPIC_CREATION_FIXED: true ARGUMENT_POSTING_WORKS: true EKOH_MIGRATION_0002_CREATED_AND_APPLIED: true REMAINING_VISIBLE_ETHIKOS_BUG: "Deliberate preview drawer shows 'Preview / No data'" ``` These facts are carried from the clean-slate plan and are the accepted context for the Kintsugi documentation phase. --- ## 5. Known Bugs Registry ## 5.1 BUG-001 — Deliberate Preview Drawer Shows “Preview / No data” ```yaml BUG_ID: "BUG-001" TITLE: "Deliberate preview drawer shows 'Preview / No data'" STATUS: "known_open" SEVERITY: "visible_ui_bug" CLASSIFICATION: "targeted_bugfix_not_architecture" AFFECTED_AREA: "ethiKos / Deliberate" LIKELY_ROUTE_SURFACE: - "/ethikos/deliberate/elite" - "/ethikos/deliberate/[topic]" LIKELY_FRONTEND_SERVICE: - "frontend/services/deliberate.ts" LIKELY_API_SURFACE: - "/api/ethikos/topics/{id}/" - "/api/ethikos/arguments/?topic={id}" DO_NOT_USE_AS_ARCHITECTURE_DRIVER: true ``` ### Observed behavior The Deliberate preview drawer opens with a generic title/state such as: ```txt Preview / No data ``` or otherwise appears empty when a preview should be available. ### Current implementation evidence The frontend drawer already has explicit states for: * loading; * preview object present; * preview object absent; * no latest statements available. When `preview` is missing, the drawer renders “No preview data available.” The current `fetchTopicPreview` service is designed to be resilient: it fetches topic metadata from `ethikos/topics/{topicId}/`, tries to fetch latest arguments from `ethikos/arguments/?topic=`, and still returns topic metadata even if argument loading fails. The endpoint graph currently marks `fetchTopicPreview` as a loose mapping from `/deliberate/topics/:id/preview` to `GET api/ethikos/topics`, which indicates that the conceptual preview route and the actual backend topic endpoint are not yet formalized as a strict contract. ### Classification This is a **targeted bugfix**, not a Kintsugi architecture issue. It must not trigger: * a redesign of `/ethikos/deliberate/*`; * a new preview API namespace; * a new Kialo route; * a new Kintsugi frontend shell; * a new debate data model; * replacement of the current ethiKos service layer. ### Acceptable resolution path The fix should be limited to verifying: ```yaml BUG_001_ACCEPTABLE_INVESTIGATION: CHECK_ROUTE_PARAM_ID: true CHECK_RESOLVED_PREVIEW_ID: true CHECK_DRAWER_STATE_ASSIGNMENT: true CHECK_FETCH_TOPIC_PREVIEW_RETURN_SHAPE: true CHECK_TOPIC_DETAIL_ENDPOINT_RESPONSE: true CHECK_ARGUMENTS_QUERY_RESPONSE: true CHECK_EMPTY_STATEMENTS_COPY: true ``` ### Non-acceptable resolution path ```yaml BUG_001_FORBIDDEN_RESPONSES: - "Create /api/kintsugi/preview/" - "Create /api/kialo/preview/" - "Replace EthikosArgument with Claim" - "Rewrite Deliberate page architecture" - "Move topic preview into Smart Vote" - "Move topic preview into EkoH" - "Use this bug to justify a full Kialo module" - "Use this bug to justify a full external OSS merge" ``` ### Target backlog format When this bug is eventually moved to implementation, it should be represented as: ```yaml TASK_ID: "BUG-001" TASK_TYPE: "targeted_bugfix" TITLE: "Fix Deliberate preview drawer empty state" SOURCE_DOC: "17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md" AFFECTED_DOCS: - "07_API_AND_SERVICE_CONTRACTS.md" - "14_FRONTEND_ALIGNMENT_CONTRACT.md" - "16_TEST_AND_SMOKE_CONTRACT.md" AFFECTED_FRONTEND: - "frontend/app/ethikos/deliberate/elite/page.tsx" - "frontend/services/deliberate.ts" AFFECTED_BACKEND: - "backend/konnaxion/ethikos/views.py" - "backend/konnaxion/ethikos/serializers.py" EXPECTED_TEST: - "Preview drawer shows topic title and metadata when topic exists" - "Preview drawer does not show total empty state when arguments are empty" - "Preview drawer still opens with topic metadata when latest statements are empty" ``` --- ## 6. Known Technical Cleanup Items The following items are real, but they are **not** architecture-definition work. They may be referenced in Kintsugi docs only as constraints or future backlog candidates. --- ## 6.1 Legacy `/api/home/*` Usage ```yaml ITEM_ID: "TECH-DEBT-001" TITLE: "Legacy /api/home/* endpoint usage" STATUS: "known_cleanup_item" CLASSIFICATION: "service_contract_cleanup" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description Some frontend-to-backend mappings still reference legacy `/api/home/*` routes, including categories, debate categories, debate topics, response formats, public votes, and topic vote endpoints. ### Correct Kintsugi policy Kintsugi must not expand this usage. ```yaml API_HOME_POLICY: MAY_ADD_NEW_HOME_CALLS: false MAY_WRAP_TEMPORARILY_FOR_MIGRATION: true MUST_REPLACE_LONG_TERM: true TARGET_REPLACEMENTS: TOPICS: "/api/ethikos/topics/" STANCES: "/api/ethikos/stances/" ARGUMENTS: "/api/ethikos/arguments/" VOTES: "/api/kollective/votes/" ``` ### Not a Kintsugi architecture decision This cleanup must not be used to: * rename `/api/ethikos/*`; * introduce `/api/deliberation/*`; * introduce `/api/kintsugi/*`; * introduce GraphQL for basic CRUD; * rewrite the frontend service layer. --- ## 6.2 Loose Endpoint Mappings ```yaml ITEM_ID: "TECH-DEBT-002" TITLE: "Loose service-to-backend mappings" STATUS: "known_cleanup_item" CLASSIFICATION: "contract_formalization" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description The endpoint graph identifies several frontend service calls as loose mappings. Examples include: * `frontend/services/deliberate.ts` preview/detail/topic calls mapped loosely to `api/ethikos/topics`; * `frontend/services/impact.ts` calls mapped loosely to `api/keenkonnect/projects`; * learn routes mapped loosely to KonnectED resources. ### Correct Kintsugi policy Loose mappings should be formalized in: ```txt 07_API_AND_SERVICE_CONTRACTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md ``` ### Not a Kintsugi architecture decision Loose mapping cleanup must not become a full rewrite. --- ## 6.3 Impact Currently Depends on KeenKonnect-like Project Semantics ```yaml ITEM_ID: "TECH-DEBT-003" TITLE: "Impact service is loosely mapped to KeenKonnect projects" STATUS: "known_cleanup_item" CLASSIFICATION: "ownership_alignment" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description The endpoint graph shows `/impact/feedback`, `/impact/outcomes`, and `/impact/tracker` service functions loosely mapped to `api/keenkonnect/projects`. ### Correct Kintsugi policy Kintsugi ownership should eventually be: ```yaml IMPACT_TRUTH_OWNER: "ethiKos / Konsultations" KEENKONNECT_ROLE: "handoff or execution/project implementation surface" KEENKONNECT_MUST_NOT_OWN_CIVIC_IMPACT_TRUTH: true ``` ### Not a first-step bugfix This should be documented in the route and data model plans, then converted into backlog later. --- ## 6.4 Konsultations Hooks Are Incomplete or Partially Stubbed ```yaml ITEM_ID: "TECH-DEBT-004" TITLE: "Konsultations hooks are incomplete or partially stubbed" STATUS: "known_cleanup_item" CLASSIFICATION: "future_consultation_backend_formalization" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description Current Konsultations logic partially maps consultation behavior onto ethiKos topics and stances. One hook explicitly aggregates consultation results from `/api/ethikos/stances/?topic=`, and another `useConsultations.ts` hook is still a stub. ### Correct Kintsugi policy This must be handled by the Konsultations contract in: ```txt 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md ``` ### Not a bugfix scope Do not attempt to fully implement Konsultations during documentation generation. --- ## 6.5 Optional or Incomplete Backend Modules ```yaml ITEM_ID: "TECH-DEBT-005" TITLE: "Optional or incomplete backend modules" STATUS: "known_platform_alpha_signal" CLASSIFICATION: "readiness_signal" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description The completion report identifies several backend modules as partial or optional, notes that vote endpoints are imported under `try/except`, and recommends eliminating or gating mocks/stubs before beta readiness. ### Correct Kintsugi policy Kintsugi docs may reference these as readiness constraints, but must not attempt to resolve all platform incompleteness. --- ## 6.6 EkoH Migration Drift Risk ```yaml ITEM_ID: "TECH-DEBT-006" TITLE: "Verify EkoH model source and GiST index setup" STATUS: "known_follow_up" CLASSIFICATION: "migration_discipline" KINTSUGI_ARCHITECTURE_BLOCKER: false ``` ### Description The clean-slate plan says the EkoH migration `0002...` was created and applied successfully, but also notes that the EkoH model source should be verified so future `makemigrations` does not drift again. ### Correct Kintsugi policy This belongs to backend migration hygiene. It must not turn into a redesign of Smart Vote or EkoH. --- ## 7. Non-Kintsugi Items The following items must not be included as active Kintsugi implementation work. --- ## 7.1 General Frontend/Backend Debugging ```yaml NON_KINTSUGI_ITEM: "general_frontend_backend_debugging" STATUS: "excluded" ``` Do not rehash: * previous frontend build errors; * previous CSRF/auth debugging; * previous category creation debugging; * previous argument posting debugging; * previous migration debugging; * previous Ant Design warning cleanup. These are baseline history, not current Kintsugi scope. --- ## 7.2 Full External OSS Integration ```yaml NON_KINTSUGI_ITEM: "full_external_oss_merge" STATUS: "excluded" ``` Kintsugi first pass uses **partial native mimic**, not full merge. Do not directly merge or embed: * Consider.it; * Kialo; * Loomio; * Citizen OS; * Decidim; * CONSUL Democracy; * DemocracyOS; * Polis; * LiquidFeedback; * All Our Ideas; * Your Priorities; * OpenSlides. The clean-slate plan explicitly says there should be no big-bang full merge; existing ethiKos frame and route families remain stable; partial native mimic is the current strategy; annex/sidecar tools are deferred. --- ## 7.3 Deferred OSS Sources ```yaml NON_KINTSUGI_ITEM: "deferred_oss_sources" STATUS: "excluded_from_first_pass" ``` These are not first pass: ```txt Polis LiquidFeedback All Our Ideas Your Priorities OpenSlides ``` They may receive public credit or future study, but they must not drive current route, model, service, or migration design. --- ## 7.4 New Top-Level Kintsugi Application ```yaml NON_KINTSUGI_ITEM: "new_top_level_kintsugi_app" STATUS: "forbidden" ``` Do not create: ```txt /kintsugi /api/kintsugi/* frontend/app/kintsugi/* backend/konnaxion/kintsugi/ ``` Kintsugi is an upgrade layer for ethiKos, not a new standalone application. --- ## 7.5 New Kialo Module or Kialo API ```yaml NON_KINTSUGI_ITEM: "new_kialo_module" STATUS: "forbidden" ``` Do not create: ```txt /kialo /api/kialo/* frontend/app/kialo/* backend/konnaxion/kialo/ ``` Kialo-style features belong under: ```txt /ethikos/deliberate/* /api/ethikos/* konnaxion.ethikos ``` The codebase already has first-class ethiKos Deliberate routes and canonical ethiKos endpoints; Kialo-style work must extend those surfaces instead of creating a separate app. --- ## 7.6 GraphQL or WebSocket Rewrite ```yaml NON_KINTSUGI_ITEM: "graphql_or_websocket_rewrite" STATUS: "excluded" ``` The current guidance says to use the services layer and existing `/api/...` prefixes, not to invent paths, and not to use GraphQL or WebSockets for CRUD unless the codebase explicitly does so. Do not introduce GraphQL or WebSockets for: * topics; * stances; * arguments; * categories; * votes; * readings; * drafts; * impact tracks. --- ## 7.7 New Layout Shell or Theme System ```yaml NON_KINTSUGI_ITEM: "new_layout_shell_or_theme" STATUS: "excluded" ``` Do not create a new global shell, route shell, theme provider, or duplicated navigation system. The current ethiKos frontend is already implemented under `/ethikos/*` with page groups for Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin, and it uses `EthikosPageShell` and `PageContainer` consistently. --- ## 7.8 Full Konsultations Implementation ```yaml NON_KINTSUGI_ITEM: "full_konsultations_implementation" STATUS: "deferred_to_backlog" ``` The documentation may define Konsultations ownership and target contracts. It must not implement the entire Konsultations backend during documentation generation. --- ## 7.9 Full Smart Vote / EkoH Implementation ```yaml NON_KINTSUGI_ITEM: "full_smart_vote_ekoh_implementation" STATUS: "deferred_to_backlog" ``` This documentation pack may define: * readings; * lenses; * snapshot references; * audit fields; * result publication rules. It must not implement the entire weighted voting system during doc generation. --- ## 7.10 Reports / Insights Rewrite ```yaml NON_KINTSUGI_ITEM: "reports_insights_rewrite" STATUS: "excluded" ``` Insights may consume ethiKos and Kollective data, but Kintsugi must not become a Reports module rewrite. The Insights contract already describes analytics over Kollective and domain endpoints, including `/api/kollective/votes/` and ethiKos topics, stances, and arguments. --- ## 8. Classification System for Future Findings Future items must be classified before entering any backlog. ```yaml FINDING_CLASSIFICATION: ARCHITECTURE_CONTRACT: DESCRIPTION: "Belongs in Kintsugi docs before implementation." EXAMPLES: - "ownership boundary" - "route mapping" - "API contract" - "data model contract" TARGETED_BUGFIX: DESCRIPTION: "Small concrete defect with known surface." EXAMPLES: - "Preview drawer empty state" - "button disabled incorrectly" - "wrong data shape adapter" TECH_DEBT: DESCRIPTION: "Real cleanup, but not architecture-defining." EXAMPLES: - "legacy endpoint usage" - "loose service mapping" - "stub hook" PLATFORM_READINESS: DESCRIPTION: "Alpha/beta hardening item across the platform." EXAMPLES: - "mock mode" - "missing integration tests" - "optional backend module gating" DEFERRED_FEATURE: DESCRIPTION: "Valid future feature but not first pass." EXAMPLES: - "Polis-style clustering" - "LiquidFeedback delegation" - "OpenSlides meeting control" OUT_OF_SCOPE: DESCRIPTION: "Must not be done in Kintsugi." EXAMPLES: - "new top-level Kintsugi app" - "full OSS merge" - "GraphQL rewrite" ``` --- ## 9. Allowed vs Forbidden Work ## 9.1 Allowed During Documentation Generation ```yaml ALLOWED_DURING_DOC_GENERATION: - "Define known bug registry" - "Classify current visible bugs" - "Mark legacy routes as cleanup items" - "Document non-goals" - "Define triage rules" - "Reference current route and endpoint reality" - "Reserve implementation details for backlog" ``` --- ## 9.2 Not Allowed During Documentation Generation ```yaml FORBIDDEN_DURING_DOC_GENERATION: - "Implement bugfixes" - "Generate code patches" - "Create migrations" - "Invent new endpoints" - "Rewrite services" - "Refactor route hierarchy" - "Resolve all mocks/stubs" - "Merge external OSS code" - "Create implementation tasks outside doc 22" ``` --- ## 10. Known Items Summary Table | ID | Item | Type | Status | Kintsugi impact | Action | | --------------- | --------------------------------------------------- | ---------------------------: | -----: | ---------------------- | ----------------------------- | | `BUG-001` | Deliberate preview drawer shows “Preview / No data” | targeted bugfix | open | visible UI issue only | backlog later | | `TECH-DEBT-001` | Legacy `/api/home/*` usage | service cleanup | known | contract risk | document and replace later | | `TECH-DEBT-002` | Loose endpoint mappings | contract cleanup | known | alignment risk | formalize in docs | | `TECH-DEBT-003` | Impact mapped to KeenKonnect projects | ownership cleanup | known | future ownership risk | define native Impact contract | | `TECH-DEBT-004` | Konsultations hooks incomplete/stubbed | future backend formalization | known | scope risk | defer to data/API plan | | `TECH-DEBT-005` | Optional/incomplete backend modules | readiness signal | known | platform maturity risk | feature-gate later | | `TECH-DEBT-006` | EkoH migration drift risk | migration hygiene | known | backend hygiene risk | verify later | --- ## 11. Bug Intake Template Any new bug discovered during Kintsugi planning must use this format: ```yaml BUG_ID: "BUG-XXX" TITLE: "" STATUS: "candidate | confirmed | fixed | deferred" SEVERITY: "low | medium | high | critical" CLASSIFICATION: "targeted_bugfix | tech_debt | platform_readiness | out_of_scope" AFFECTED_AREA: "" AFFECTED_ROUTE_SURFACE: [] AFFECTED_FRONTEND_FILES: [] AFFECTED_BACKEND_FILES: [] AFFECTED_ENDPOINTS: [] SOURCE_EVIDENCE: [] KINTSUGI_ARCHITECTURE_BLOCKER: false WHY_NOT_ARCHITECTURE: "" ACCEPTABLE_FIX_SCOPE: [] FORBIDDEN_FIX_SCOPE: [] RELATED_DOCS: [] ``` --- ## 12. Non-Kintsugi Item Intake Template Any request that looks related but may be outside Kintsugi must use this format: ```yaml ITEM_ID: "NON-KINTSUGI-XXX" TITLE: "" REQUESTED_WORK: "" CLASSIFICATION: "out_of_scope | deferred_feature | platform_readiness | tech_debt" WHY_OUTSIDE_KINTSUGI: "" MAY_BE_REFERENCED_IN_DOCS: true MAY_ENTER_BACKLOG_LATER: true BLOCKS_DOC_GENERATION: false RELATED_DOCS: [] ``` --- ## 13. Anti-Drift Rules ```yaml ANTI_DRIFT_RULES: - "Do not turn BUG-001 into an architecture redesign." - "Do not restart the previous frontend/backend debugging history." - "Do not expand /api/home/*." - "Do not use loose mappings as permission to invent new APIs." - "Do not move civic impact truth into KeenKonnect." - "Do not implement Konsultations during documentation generation." - "Do not implement Smart Vote/EkoH during documentation generation." - "Do not create a new Kintsugi app." - "Do not create a new Kialo module." - "Do not introduce GraphQL or WebSockets for CRUD." - "Do not create a second layout shell." - "Do not create a new theme system." - "Do not merge external OSS projects." - "Do not treat deferred OSS sources as first-pass scope." - "Do not generate implementation backlog outside 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md." ``` --- ## 14. Related Documents ```txt 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 15. Final Contract Summary This file exists to prevent scope drift. The Kintsugi update must proceed as: ```txt documentation → contracts → code reading → backlog → implementation ``` It must not proceed as: ```txt visible bug → broad rewrite → new architecture → uncontrolled backlog ``` The only currently accepted open visible bug is: ```txt BUG-001 — Deliberate preview drawer shows “Preview / No data” ``` That bug is real, but it is not the architecture. Final rule: ```txt If an item does not clarify the Kintsugi architecture, route mapping, ownership model, API/service contract, data contract, or AI drift rules, it belongs outside the Kintsugi documentation pack or in the later implementation backlog. ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 390468f1e477900f215148a1fdb5ecd403564ac5699cb757a18067329e955968 CONTENT_BYTES: 33979 ================================================================================================ # 18 — ADR Register **File:** `18_ADR_REGISTER.md` **Doc pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Draft for parallel documentation generation **Mode:** Documentation-first architecture planning **Primary owner:** ethiKos / Kintsugi planning **Last updated:** 2026-04-25 **Related docs:** * `00_KINTSUGI_START_HERE.md` * `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` * `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` * `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` * `04_CANONICAL_NAMING_AND_VARIABLES.md` * `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` * `07_API_AND_SERVICE_CONTRACTS.md` * `08_DATA_MODEL_AND_MIGRATION_PLAN.md` * `09_SMART_VOTE_EKOH_READING_CONTRACT.md` * `10_FIRST_PASS_INTEGRATION_MATRIX.md` * `11_MIMIC_VS_ANNEX_RULEBOOK.md` * `14_FRONTEND_ALIGNMENT_CONTRACT.md` * `15_BACKEND_ALIGNMENT_CONTRACT.md` * `20_AI_GENERATION_GUARDRAILS.md` * `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` * `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` --- ## 1. Purpose This document records the **Architecture Decision Records** for the ethiKos Kintsugi upgrade. Its purpose is to prevent architectural drift during parallel AI-assisted documentation and future implementation work. Each ADR records: * the decision; * the context; * the consequences; * the documents affected; * the anti-drift rule created by the decision. These ADRs are binding for the Kintsugi documentation pack unless explicitly superseded by a later ADR. --- ## 2. Scope This ADR register covers decisions about: * OSS integration strategy; * ethiKos route stability; * Korum / Konsultations boundaries; * Smart Vote and EkoH boundaries; * Kialo-style argument mapping; * data model evolution; * frontend/backend alignment; * migration sequencing; * known legacy issues; * documentation-first workflow. This ADR register does **not** define: * final backend code; * final frontend code; * complete serializer definitions; * full endpoint payloads; * backlog tasks; * final implementation schedule. Those belong in the technical contract docs and implementation backlog template. --- ## 3. Canonical Variables Used ```yaml id="adr-vars-001" DOCUMENT_NAME: "18_ADR_REGISTER.md" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_API_PREFIX: "/api/ethikos/*" KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "aggregations" - "result publication" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" DOCS_BEFORE_CODE: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true ``` --- ## 4. Source Basis The current ethiKos implementation already has a concrete `/ethikos/*` frontend route surface with Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin route families; the canonical backend scope is currently `/api/ethikos/topics/`, `/api/ethikos/stances/`, `/api/ethikos/arguments/`, and `/api/ethikos/categories/`, backed by `EthikosCategory`, `EthikosTopic`, `EthikosStance`, and `EthikosArgument`. The clean-slate plan establishes that the Kintsugi work should be planning-first, not bugfix-first; it explicitly preserves the existing Ethikos frame and route families, rejects a full external merge now, requires partial native mimic, and defers code inspection until docs are stable. The boundaries document establishes the core Kintsugi principle: ethiKos keeps a baseline truth while allowing Smart Vote readings/lenses, preserves existing core tables and routes, and adds only non-breaking fields/tables such as reading audit fields, `ExternalArtifact`, `ProjectionMapping`, and drafting tables. The Kialo corpus makes Kialo-style structured deliberation relevant as a native mimic target for `/ethikos/deliberate/*`, including discussion topology, participant roles, permissions, sources, navigation surfaces, and claim-oriented workflows. --- ## 5. ADR Status Values ```yaml id="adr-status-values" ADR_STATUS_VALUES: PROPOSED: "Documented but not yet accepted." ACCEPTED: "Binding decision for this documentation pack." SUPERSEDED: "Replaced by a later ADR." DEPRECATED: "No longer recommended but retained for historical context." ``` Unless otherwise stated, all ADRs in this register are **Accepted**. --- ## 6. ADR Index | ADR | Title | Status | | ------- | ------------------------------------------------------------------------------ | -------- | | ADR-001 | No full OSS merge for the first Kintsugi pass | Accepted | | ADR-002 | Existing ethiKos route families remain stable | Accepted | | ADR-003 | Korum and Konsultations remain separate ownership domains | Accepted | | ADR-004 | Smart Vote publishes readings only | Accepted | | ADR-005 | EkoH is context, not the voting engine | Accepted | | ADR-006 | Drafting is a bounded ethiKos capability | Accepted | | ADR-007 | External tools use mimic first, annex later | Accepted | | ADR-008 | `/api/home/*` legacy calls must be removed or isolated | Accepted | | ADR-009 | Impact belongs to ethiKos/Konsultations truth, not KeenKonnect truth | Accepted | | ADR-010 | Implementation backlog comes after docs and code-reading | Accepted | | ADR-011 | Kialo-style features extend Korum; no separate Kialo module | Accepted | | ADR-012 | Existing Ethikos core models must not be renamed or replaced | Accepted | | ADR-013 | Separate topic stances, claim impact votes, and Smart Vote readings | Accepted | | ADR-014 | Kintsugi database changes must be non-breaking additive migrations | Accepted | | ADR-015 | Frontend implementation must stay inside the existing shell and services layer | Accepted | | ADR-016 | Route concepts from older docs are conceptual, not implementation routes | Accepted | | ADR-017 | OSS source documents are pattern references, not source-of-truth architecture | Accepted | | ADR-018 | Known bugs must not drive Kintsugi architecture | Accepted | | ADR-019 | EkoH migration drift must be treated as a schema-stability concern | Accepted | | ADR-020 | ADRs are binding across parallel documentation generation | Accepted | --- # ADR-001 — No full OSS merge for the first Kintsugi pass **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos Kintsugi planning ## Context Kintsugi uses inspiration from civic technology systems, including Consider.it, Kialo-style argument mapping, Loomio, Citizen OS, Decidim, CONSUL Democracy, and DemocracyOS. However, the clean-slate plan explicitly rejects a full external merge for the current pass and preserves the existing ethiKos frame and route families. ## Decision The first Kintsugi pass MUST NOT merge any external OSS platform directly into Konnaxion. The first pass MUST use: ```yaml id="adr-001-decision" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false ``` ## Consequences * External systems are treated as pattern sources. * No external app becomes a first-pass dependency. * No external database schema becomes canonical. * No external route family becomes canonical. * Licensing and architectural risk are reduced. * Implementation remains aligned with the existing Konnaxion stack. ## Anti-drift rule ```txt id="adr-001-rule" Do not propose a direct merge of Consider.it, Kialo, Loomio, Citizen OS, Decidim, CONSUL Democracy, DemocracyOS, Polis, LiquidFeedback, All Our Ideas, Your Priorities, or OpenSlides into the Konnaxion core. ``` --- # ADR-002 — Existing ethiKos route families remain stable **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos Kintsugi planning ## Context The current ethiKos frontend is already implemented under `/ethikos/*` with specific route families: Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin. Older conceptual docs mention routes such as `/platforms/konnaxion/ethikos`, `/platforms/konnaxion/ethikos/kintsugi`, `/platforms/konnaxion/ethikos/korum`, and `/consult`, but these are not the current implementation route surface. ## Decision The Kintsugi upgrade MUST preserve and upgrade the existing `/ethikos/*` route families. Canonical implementation route families: ```txt id="adr-002-routes" /ethikos/decide/* /ethikos/deliberate/* /ethikos/trust/* /ethikos/pulse/* /ethikos/impact/* /ethikos/learn/* /ethikos/insights /ethikos/admin/* ``` ## Consequences * Kintsugi does not create a parallel frontend application. * Korum maps primarily to `/ethikos/deliberate/*`. * Konsultations maps across Decide, Impact, and relevant consultation-derived surfaces. * Smart Vote readings appear through Decide, Results, Insights, and Methodology surfaces. * EkoH context appears through Trust, Decide, and Insights where appropriate. ## Anti-drift rule ```txt id="adr-002-rule" Do not replace the existing /ethikos/* route surface with /kintsugi, /kialo, /consult, /platforms/konnaxion/ethikos/*, or any other new first-pass route family. ``` --- # ADR-003 — Korum and Konsultations remain separate ownership domains **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos Kintsugi planning ## Context The Kintsugi boundaries define ethiKos as a deliberation and decision-formation module with submodule boundaries. Korum owns structured debates, while Konsultations owns consultation intake, ballots, result snapshots, and impact tracking. ## Decision Korum and Konsultations MUST remain distinct ownership domains. ```yaml id="adr-003-ownership" KORUM_OWNS: - "topics" - "stances" - "arguments" - "argument moderation" KONSULTATIONS_OWNS: - "intake" - "ballots" - "result snapshots" - "impact tracking" ``` ## Consequences * Argument graph work belongs to Korum. * Topic-level stance capture belongs to Korum. * Formal consultation result snapshots belong to Konsultations. * Impact tracking belongs to Konsultations. * Shared objects must have explicit ownership. * UI pages may combine data from both domains, but write ownership remains separated. ## Anti-drift rule ```txt id="adr-003-rule" Do not collapse Korum and Konsultations into a generic Debate module or a generic Consultation module without ownership boundaries. ``` --- # ADR-004 — Smart Vote publishes readings only **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos / Smart Vote planning ## Context The Kintsugi boundary rule is “single truth, multiple readings”: baseline events remain visible and canonical, while Smart Vote computes explicit readings/lenses over that data. ## Decision Smart Vote MUST publish derived readings and MUST NOT mutate upstream source facts. ```yaml id="adr-004-smart-vote" SMART_VOTE_OWNS: - "readings" - "lens declarations" - "aggregations" - "result publication" SMART_VOTE_MUTATES_SOURCE_FACTS: false ``` ## Consequences * Smart Vote may compute `ReadingResult`. * Smart Vote may define `LensDeclaration`. * Smart Vote may publish result interpretations. * Smart Vote must not rewrite `EthikosStance`. * Smart Vote must not rewrite `EthikosArgument`. * Smart Vote must not rewrite Konsultations ballot source events. * Every non-baseline reading must be declared and reproducible. ## Anti-drift rule ```txt id="adr-004-rule" Do not implement Smart Vote as a mutation layer over EthikosTopic, EthikosStance, EthikosArgument, ballot events, or baseline results. ``` --- # ADR-005 — EkoH is context, not the voting engine **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos / EkoH / Smart Vote planning ## Context Kollective Intelligence provides the cross-module intelligence substrate, including EkoH and Smart Vote concepts. The technical reference identifies EkoH and Smart Vote as part of the broader merit-weighted decision and reputation substrate, while ethiKos remains the structured deliberation and consultation module. ## Decision EkoH MUST provide expertise, ethics, cohort, and snapshot context. EkoH MUST NOT become the voting engine. ```yaml id="adr-005-ekoh" EKOH_OWNS: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshots" EKOH_IS_VOTING_ENGINE: false EKOH_MUTATES_VOTES: false ``` ## Consequences * EkoH can provide `snapshot_ref`. * EkoH can provide expertise and ethics context. * EkoH can support Smart Vote lenses. * EkoH cannot mutate baseline votes. * EkoH cannot replace Smart Vote. * EkoH cannot own ethiKos decision results. ## Anti-drift rule ```txt id="adr-005-rule" Do not treat EkoH as the source of ballots, stances, readings, or decision records. ``` --- # ADR-006 — Drafting is a bounded ethiKos capability **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos Kintsugi planning ## Context Kintsugi’s civic pipeline includes drafting as a bridge between deliberation and decision. Citizen OS contributes useful patterns for phases and drafting, but the first pass must not merge external systems. ## Decision Drafting MUST be added as a bounded ethiKos capability using additive models. First-pass drafting model vocabulary MAY include: ```txt id="adr-006-models" Draft DraftVersion Amendment RationalePacket ``` ## Consequences * Drafts do not replace topics. * Draft versions do not replace arguments. * Amendments do not mutate prior draft versions. * Drafting remains auditable. * Drafting can connect Korum deliberation to Decide outcomes. ## Anti-drift rule ```txt id="adr-006-rule" Do not store draft versions by overwriting EthikosTopic.description or EthikosArgument.content. ``` --- # ADR-007 — External tools use mimic first, annex later **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos Kintsugi planning ## Context The Kintsugi strategy distinguishes “mimic” from “annex.” The current first pass is partial native mimic only. External tools may later be represented through boundary objects such as `ExternalArtifact` and `ProjectionMapping`, but they must not write directly to core tables. ## Decision The default external tool strategy is native mimic. Annex is deferred and requires: ```yaml id="adr-007-annex" ANNEX_REQUIRES_ISOLATION: true ANNEX_REQUIRES_REPLACEABILITY: true ANNEX_REQUIRES_NO_CORE_TABLE_WRITES: true ANNEX_REQUIRES_LICENSE_CLEARANCE: true ANNEX_REQUIRES_ADAPTER_LAYER: true ``` ## Consequences * First-pass OSS patterns are translated into native Konnaxion concepts. * External artifacts are optional boundary references, not source truth. * Future annex integrations must use adapter boundaries. * No OSS tool is allowed to dominate the ethiKos product shape. ## Anti-drift rule ```txt id="adr-007-rule" If an OSS pattern conflicts with ethiKos architecture, mimic the pattern only; do not import the architecture. ``` --- # ADR-008 — `/api/home/*` legacy calls must be removed or isolated **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** frontend/backend alignment ## Context Current API guidance requires frontend calls to use the services layer and respect existing `/api/...` prefixes. It explicitly says not to rename `/api/ethikos/...` to invented alternatives and not to use GraphQL or WebSockets for CRUD unless the codebase explicitly does so. Some legacy or loose mappings still point to older `/api/home/*` style endpoints in the broader analysis. ## Decision Kintsugi MUST NOT expand `/api/home/*`. Any remaining `/api/home/*` usage MUST be: 1. removed; 2. isolated behind compatibility services; or 3. explicitly marked as legacy pending replacement. ## Consequences * API contracts remain centered on `/api/ethikos/*`. * New Kintsugi data must not be added under `/api/home/*`. * Services must be cleaned up before implementation hardening. * Documentation must not introduce new `/api/home/*` references. ## Anti-drift rule ```txt id="adr-008-rule" Do not create new Kintsugi service calls against /api/home/*. ``` --- # ADR-009 — Impact belongs to ethiKos/Konsultations truth, not KeenKonnect truth **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** ethiKos / Konsultations planning ## Context Impact surfaces currently exist under `/ethikos/impact/*`. The functional interpretation of the current docs says Impact translates consultations and debates into feedback, outcomes, and tracker views. KeenKonnect may own project collaboration and delivery workflows, but civic accountability must remain part of ethiKos/Konsultations truth. ## Decision Impact tracking for Kintsugi MUST belong to ethiKos/Konsultations. KeenKonnect MAY receive handoff links or execution references, but it MUST NOT become the canonical owner of ethiKos civic impact. ## Consequences * `ImpactTrack` belongs to ethiKos/Konsultations. * `ImpactUpdate` belongs to ethiKos/Konsultations. * KeenKonnect links are references, not source truth. * Impact remains accountable to decisions and topics. ## Anti-drift rule ```txt id="adr-009-rule" Do not make KeenKonnect Project the canonical data source for /ethikos/impact/*. ``` --- # ADR-010 — Implementation backlog comes after docs and code-reading **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** Kintsugi planning ## Context The clean-slate plan defines the work order: refine documentation, add companion docs, inspect downloaded OSS repos, then produce implementation backlog. It explicitly warns against mixing product strategy and low-level code tasks too early. ## Decision Implementation backlog MUST be generated only after: 1. core Kintsugi docs are stable; 2. companion docs are drafted; 3. current code is inspected; 4. OSS repo patterns are reviewed against reality. ## Consequences * Docs remain architectural and normative. * Backlog tasks do not pollute strategy docs. * Parallel documentation generation can proceed safely. * Implementation tasks can later reference stable decisions. ## Anti-drift rule ```txt id="adr-010-rule" Do not generate backend/frontend implementation tasks inside strategy, boundaries, route, or data model docs except by reference to 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md. ``` --- # ADR-011 — Kialo-style features extend Korum; no separate Kialo module **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** Korum / Deliberate planning ## Context The Kialo corpus provides first-pass inspiration for structured deliberation: discussion topology, participant roles, permissions, sources, navigation, claim structure, and related discussion mechanics. The Kintsugi first pass uses native mimic, not direct code import or a separate Kialo module. ## Decision Kialo-style features MUST extend Korum under `/ethikos/deliberate/*`. ```yaml id="adr-011-kialo" KIALO_STRATEGY: "native_mimic" KIALO_ROUTE_SCOPE: "/ethikos/deliberate/*" KIALO_BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ``` ## Consequences * Kialo “claims” map conceptually to `EthikosArgument`. * Kialo discussion topology maps to ethiKos topic settings. * Kialo participant roles map to ethiKos discussion roles. * Kialo source/citation behavior maps to `ArgumentSource`. * No `/kialo` route is created. * No `konnaxion.kialo` app is created. ## Anti-drift rule ```txt id="adr-011-rule" Do not create a separate Kialo module, Kialo app, Kialo route family, or Kialo database core in the first pass. ``` --- # ADR-012 — Existing Ethikos core models must not be renamed or replaced **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** backend alignment ## Context The current canonical ethiKos backend uses `EthikosCategory`, `EthikosTopic`, `EthikosStance`, and `EthikosArgument`. These are already connected to frontend services and UI behavior. ## Decision The current core ethiKos models MUST be preserved. ```yaml id="adr-012-models" PRESERVE_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" RENAME_EXISTING_MODELS: false DELETE_EXISTING_MODELS: false REPLACE_EXISTING_MODELS: false ``` ## Consequences * Kintsugi data changes must be additive. * `EthikosArgument` must not be renamed to `Claim`. * `EthikosStance` must not be replaced by Smart Vote readings. * `EthikosTopic` remains the anchor for deliberation and consultation. * New models may reference existing models. ## Anti-drift rule ```txt id="adr-012-rule" Do not rename or replace EthikosCategory, EthikosTopic, EthikosStance, or EthikosArgument. ``` --- # ADR-013 — Separate topic stances, claim impact votes, and Smart Vote readings **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** data model / Smart Vote / Korum planning ## Context Current ethiKos stances are topic-level numeric values constrained to `-3..+3`. Kialo-style voting introduces claim-level impact voting, which must remain separate from topic-level stances and Smart Vote readings. ## Decision The Kintsugi data model MUST maintain three separate concepts: ```yaml id="adr-013-votes" EthikosStance: level: "topic-level" range: "-3..+3" owner: "Korum" ArgumentImpactVote: level: "argument/claim-level" range: "0..4" owner: "Korum" ReadingResult: level: "derived aggregation" range: "lens-dependent" owner: "Smart Vote" ``` ## Consequences * Claim impact votes do not alter topic stances. * Topic stances do not become Smart Vote readings. * Smart Vote readings are derived from declared inputs. * Results can be explained without mixing semantics. ## Anti-drift rule ```txt id="adr-013-rule" EthikosStance != ArgumentImpactVote != ReadingResult. ``` --- # ADR-014 — Kintsugi database changes must be non-breaking additive migrations **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** backend/data model alignment ## Context The boundaries document states that the Kintsugi upgrade is a documentation and boundary upgrade first, and that existing core tables and routes must remain stable. It recommends adding only non-breaking fields/tables such as reading audit fields, external artifact boundaries, and drafting tables. ## Decision Kintsugi migrations MUST be additive and non-breaking. Allowed: ```yaml id="adr-014-allowed" ADD_NEW_TABLES: true ADD_NULLABLE_FIELDS: true ADD_SAFE_DEFAULT_FIELDS: true ADD_INDEXES: true ADD_AUDIT_TABLES: true ``` Forbidden: ```yaml id="adr-014-forbidden" RENAME_EXISTING_TABLES: false DELETE_EXISTING_TABLES: false DELETE_EXISTING_FIELDS: false CHANGE_EXISTING_PRIMARY_KEYS: false CHANGE_EXISTING_ENDPOINT_SEMANTICS: false ``` ## Consequences * Current data remains readable. * Migrations can be staged safely. * Existing smoke tests should continue to pass. * Kintsugi extensions can be rolled out incrementally. ## Anti-drift rule ```txt id="adr-014-rule" Do not generate destructive migrations for the Kintsugi first pass. ``` --- # ADR-015 — Frontend implementation must stay inside the existing shell and services layer **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** frontend alignment ## Context The current ethiKos frontend uses `EthikosPageShell` and `PageContainer` consistently, and the route structure is already deeper and more explicit than older simplified navigation concepts. API guidance also requires frontend API calls to use the services layer and established `/api/...` routes. ## Decision Kintsugi frontend work MUST stay inside the existing ethiKos shell and services layer. ## Consequences * No second shell is created. * No second theme system is created. * Page groups remain under `/ethikos/*`. * New API calls must go through services. * Components may be added, but layout ownership remains stable. ## Anti-drift rule ```txt id="adr-015-rule" Do not create a new Kintsugi shell, Kialo shell, or standalone civic-tech shell for first-pass Kintsugi pages. ``` --- # ADR-016 — Route concepts from older docs are conceptual, not implementation routes **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** source-of-truth alignment ## Context Older Kintsugi and boundaries docs include recommended public surfaces such as `/platforms/konnaxion/ethikos`, `/platforms/konnaxion/ethikos/kintsugi`, and `/consult`. The code snapshot and technical reference show the actual implementation route surface under `/ethikos/*`. ## Decision Older conceptual route references MAY remain in public strategy docs as conceptual surfaces, but implementation planning MUST target the actual `/ethikos/*` routes. ## Consequences * Prevents route drift. * Keeps implementation grounded in the snapshot. * Allows conceptual docs to discuss future public positioning without breaking current architecture. ## Anti-drift rule ```txt id="adr-016-rule" When route docs conflict, implementation reality wins over older conceptual route proposals. ``` --- # ADR-017 — OSS source documents are pattern references, not source-of-truth architecture **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** OSS code-reading planning ## Context The first-pass OSS source list includes civic-tech systems whose product ideas are useful, but their architecture, stack, licensing model, or route design may not fit Konnaxion. ## Decision OSS source documents are pattern references only. They MUST NOT override: 1. current Konnaxion code reality; 2. Kintsugi boundaries; 3. canonical naming variables; 4. existing ethiKos route families; 5. existing backend app structure. ## Consequences * OSS review remains useful without causing architectural drift. * Strong patterns can be mimicked. * Unfit architecture can be rejected. * Annexes remain future-only unless explicitly approved. ## Anti-drift rule ```txt id="adr-017-rule" Do not treat an OSS repo’s native data model, route model, or app architecture as canonical for ethiKos. ``` --- # ADR-018 — Known bugs must not drive Kintsugi architecture **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** Kintsugi planning ## Context The clean-slate baseline carries one known visible bug: the Deliberate preview drawer shows “Preview / No data”. The plan explicitly frames the next phase as Kintsugi planning, not broad bugfixing. ## Decision Known bugs MUST be tracked separately from Kintsugi architecture. The preview drawer issue is classified as: ```yaml id="adr-018-bug" BUG_001: title: "Deliberate preview drawer shows 'Preview / No data'" classification: "targeted_bugfix_not_architecture" ``` ## Consequences * The architecture is not redesigned around one drawer bug. * The bug can be fixed with a targeted service/UI correction. * Documentation remains focused on Kintsugi upgrade contracts. ## Anti-drift rule ```txt id="adr-018-rule" Do not use BUG_001 to justify redesigning Deliberate, Korum, Ethikos routes, or the data model. ``` --- # ADR-019 — EkoH migration drift must be treated as a schema-stability concern **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** backend/schema alignment ## Context The stable baseline says EkoH migration `0002` was created and applied. The clean-slate plan also mentions verifying EkoH model source and GiST/index setup so future `makemigrations` does not drift again. ## Decision EkoH migration drift must be treated as a schema-stability issue, not a Kintsugi feature design issue. ## Consequences * Future EkoH migration changes require explicit review. * Kintsugi docs may reference EkoH snapshots, but should not rewrite EkoH schema casually. * Schema drift prevention belongs in backend alignment and test/smoke contracts. ## Anti-drift rule ```txt id="adr-019-rule" Do not generate new EkoH schema changes for Kintsugi unless they are explicitly required by the Smart Vote/EkoH reading contract and verified against current migrations. ``` --- # ADR-020 — ADRs are binding across parallel documentation generation **Status:** Accepted **Date:** 2026-04-25 **Decision owner:** documentation governance ## Context The Kintsugi documentation pack is being generated in parallel conversations. Parallel generation creates a high risk of naming drift, scope drift, route drift, and model drift. ## Decision This ADR register is binding across all parallel documentation generation. If another generated doc conflicts with this ADR register, resolve as follows: ```yaml id="adr-020-conflict" IF_CONFLICT_WITH_CODE_SNAPSHOT: "Code snapshot wins for implementation reality." IF_CONFLICT_WITH_BOUNDARIES_DOC: "Boundaries doc wins for ownership and write rules." IF_CONFLICT_WITH_CANONICAL_VARIABLES: "Canonical variables win for naming and constants." IF_CONFLICT_WITH_ADR_REGISTER: "ADR register wins for architectural decisions." IF_CONFLICT_WITH_OSS_DOC: "ADR register wins; OSS remains pattern reference only." ``` ## Consequences * Parallel docs can be reconciled. * AI-generated content has a governance layer. * Drift is easier to detect and correct. * Later ADRs can supersede earlier ADRs explicitly. ## Anti-drift rule ```txt id="adr-020-rule" Every generated Kintsugi document must comply with this ADR register or explicitly mark a proposed conflict for review. ``` --- ## 7. ADR Template for Future Decisions Use this template for any new ADR. ```md id="adr-template" # ADR-XXX — Title **Status:** Proposed | Accepted | Superseded | Deprecated **Date:** YYYY-MM-DD **Decision owner:** ## Context Describe the problem, prior constraints, current implementation reality, and relevant documents. ## Decision State the decision clearly. ## Consequences List positive, negative, and neutral consequences. ## Alternatives considered List alternatives and why they were rejected or deferred. ## Related docs - `...` ## Anti-drift rule State the future rule created by this ADR. ``` --- ## 8. Supersession Policy An ADR may only be superseded by another ADR. A superseding ADR MUST include: ```yaml id="supersession-policy" SUPERSEDES: "ADR-XXX" REASON: "Clear reason for replacement" MIGRATION_IMPACT: "none | docs-only | code-required | data-migration-required" ``` Old ADRs MUST remain in the register for historical traceability. --- ## 9. Anti-Drift Summary The following rules summarize the current ADR set: ```txt id="adr-summary-rules" Do not full-merge OSS platforms. Do not replace /ethikos/* routes. Do not create a separate Kialo module. Do not rename EthikosArgument to Claim. Do not collapse EthikosStance, ArgumentImpactVote, and ReadingResult. Do not let Smart Vote mutate source facts. Do not turn EkoH into a voting engine. Do not let external tools write core ethiKos tables. Do not expand /api/home/*. Do not make KeenKonnect the canonical owner of civic impact. Do not generate implementation backlog before docs and code-reading. Do not create destructive migrations. Do not use known bugs as architecture drivers. ``` --- ## 10. Related Documents This ADR register must be read together with: ```txt id="related-docs" 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 11. Final Register Statement The ethiKos Kintsugi upgrade is a documentation-first, architecture-controlled, non-breaking expansion of the existing ethiKos module. The binding direction is: ```txt id="final-direction" partial native mimic no full OSS merge existing /ethikos/* routes preserved existing core Ethikos models preserved Korum and Konsultations separated Smart Vote as readings only EkoH as context only Kialo-style as native Deliberate/Korum pattern implementation backlog after docs and code-reading ``` Any generated document or implementation plan that violates this register must be corrected before use. --- ## ADR-012 — EkoH owns rating disclosure without becoming a second RBAC system **Status:** Accepted — 2026-08-20 **Decision:** EkoH owns disclosure of EkoH-owned ratings through `RatingVisibilitySetting`, generic hierarchical `RatingAccessScope`, `RatingScopeSubject`, and `RatingAccessGrant`. EkoH does not define business roles such as CEO or Supervisor and does not duplicate Konnaxion identity/permission systems. Identity visibility remains separate in `ConfidentialitySetting`; contextual influence remains owned by Smart Vote readings. **Reason:** public figures may require publicly reviewable ratings, while organisational use requires bounded access such as enterprise-wide leadership and department-only supervision. A generic scope/grant model satisfies both without coupling EkoH to Ethikos, Team Builder, KeenKonnect, Kontrol, or a specific HR schema. **Contract:** `27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md`. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/19_OSS_CODE_READING_PLAN.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 8d145766c927b6eb571a231d7d90aebb37f4fa2dc06cfb395b3c3f8bd328c392 CONTENT_BYTES: 36614 ================================================================================================ # 19 — OSS Code Reading Plan **File:** `19_OSS_CODE_READING_PLAN.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Normative planning document **Audience:** architecture, backend, frontend, product, future AI/code-reading sessions **Primary goal:** define how to inspect downloaded OSS civic-tech repositories without drifting into premature implementation, full merges, or speculative architecture. --- ## 1. Purpose This document defines the code-reading plan for the first-pass OSS repositories considered in the ethiKos Kintsugi upgrade. The goal is to inspect external civic-tech repositories **after the Kintsugi documentation contracts are stable**, in order to extract useful patterns for native implementation inside ethiKos. The code-reading process must answer: 1. What exists in the OSS codebase, not just in product documentation? 2. Which concepts are useful for ethiKos? 3. Which concepts can be mimicked natively? 4. Which concepts should be deferred? 5. Which concepts must not be imported because they conflict with Konnaxion architecture? 6. Which ethiKos route family, model, service, or contract would receive the pattern? The clean-slate plan explicitly states that OSS repo inspection comes only after documentation is stable, and that the purpose is to confirm real code patterns, avoid assumptions from docs alone, and produce implementation backlog only afterward. --- ## 2. Scope This document covers code-reading for the first-pass OSS sources: ```yaml id="6v9mth" FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" ``` This document also identifies deferred OSS sources: ```yaml id="k33l6u" DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ``` The deferred sources may be referenced for public inspiration or future research, but they are **not part of the first-pass code-reading workload**. --- ## 3. Non-goals This document does **not** authorize: * importing OSS code directly into Konnaxion; * creating new top-level apps for external tools; * replacing existing `/ethikos/*` routes; * replacing existing `/api/ethikos/*` endpoints; * creating a separate Kialo module; * creating a separate Loomio, Decidim, CONSUL, Citizen OS, or DemocracyOS module; * writing implementation tasks before the code-reading report is complete; * rewriting Konnaxion around the architecture of an external project; * adding GraphQL, WebSocket, Rails, Node, or other foreign stack assumptions into Konnaxion unless explicitly approved in a later ADR. --- ## 4. Canonical variables used ```yaml id="bzihmt" DOCUMENT_ID: "19_OSS_CODE_READING_PLAN.md" KINTSUGI: UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false DOCS_BEFORE_CODE: true CODE_READING_BEFORE_BACKLOG: true PRIMARY_ROUTE_SURFACE: "/ethikos/*" CURRENT_ETHIKOS_ROUTES: DECIDE: "/ethikos/decide/*" DELIBERATE: "/ethikos/deliberate/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" IMPACT: "/ethikos/impact/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" CURRENT_ETHIKOS_BACKEND: APP: "konnaxion.ethikos" API_TOPICS: "/api/ethikos/topics/" API_STANCES: "/api/ethikos/stances/" API_ARGUMENTS: "/api/ethikos/arguments/" API_CATEGORIES: "/api/ethikos/categories/" COMPAT_ALIASES: - "/api/deliberate/..." - "/api/deliberate/elite/..." CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" ANNEX_REQUIREMENTS: ISOLATED: true REPLACEABLE: true NO_CORE_TABLE_WRITES: true LICENSE_CLEARANCE_REQUIRED: true ADAPTER_LAYER_REQUIRED: true FORBIDDEN_FIRST_PASS: FULL_CODE_IMPORT: true DIRECT_DB_WRITES_FROM_EXTERNAL_TOOLS: true ROUTE_REPLACEMENT: true NEW_TOP_LEVEL_FOREIGN_APP: true ``` --- ## 5. Source basis This plan is grounded in the following project facts: 1. The clean-slate Kintsugi plan requires documentation first, then OSS code inspection, then implementation backlog. 2. The current ethiKos implementation already has first-class route families under `/ethikos/*`, including Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin. 3. The current canonical ethiKos backend is centered on `EthikosTopic`, `EthikosStance`, `EthikosArgument`, and `EthikosCategory`, exposed through `/api/ethikos/topics/`, `/stances/`, `/arguments/`, and `/categories/`. 4. Konnaxion uses a Next.js App Router frontend and a Django modular monolith backend with REST APIs exposed through DRF under `/api/...`. 5. External tools must be treated as inspiration sources. The Kintsugi strategy explicitly rejects blind merging and requires either native mimicry or isolated sidecar boundaries. 6. The Kialo corpus adds specific structured-deliberation concepts such as sources, single-thesis vs multi-thesis topology, perspectives, background info, lifecycle controls, and small-group modes. --- ## 6. Reading discipline OSS code reading must follow a strict sequence. ```yaml id="d01hmh" CODE_READING_SEQUENCE: 1: "Confirm repository identity" 2: "Confirm license" 3: "Confirm stack" 4: "Map application boundaries" 5: "Identify data models" 6: "Identify route/controller/API patterns" 7: "Identify frontend UX patterns" 8: "Identify permissions and roles" 9: "Identify audit/moderation/accountability patterns" 10: "Extract mimic candidates" 11: "Reject incompatible patterns" 12: "Map useful patterns to existing Ethikos route families" 13: "Produce code-reading report" 14: "Only then feed implementation backlog" ``` The reader must not jump directly from an OSS feature to a Konnaxion task. Every pattern must pass through: ```yaml id="8j2b3p" PATTERN_FILTER: - "Is it real in code?" - "Is it useful for Kintsugi?" - "Can it be mimicked natively?" - "Does it preserve Ethikos ownership boundaries?" - "Does it fit existing /ethikos/* routes?" - "Does it avoid foreign writes to core tables?" - "Does it avoid stack capture?" - "Does it require a new model, service, or only UI behavior?" ``` --- ## 7. Required output per repository Each OSS code-reading pass must produce a mini-report with this exact structure. ```markdown id="9j46vo" # OSS Code Reading Report — ## 1. Repository identity - Name: - Local path: - Upstream URL: - License: - Stack: - Primary language/framework: - Runtime requirements: - Database: - Frontend framework: - Backend framework: ## 2. Product role - What civic problem does it solve? - Which Kintsugi stage does it resemble? - Which ethiKos route family could receive its pattern? ## 3. Actual code architecture - App structure: - Core modules: - Important models: - Important controllers/routes/views: - Important services/jobs: - Permission/role system: - Admin/moderation system: - Test coverage observed: ## 4. Feature inventory | Feature | Exists in code? | Location | Notes | |---|---:|---|---| ## 5. Pattern extraction | Pattern | Mimic candidate? | Annex candidate? | Reject? | Reason | |---|---:|---:|---:|---| ## 6. Konnaxion mapping | OSS concept | Ethikos/Konnaxion concept | Route family | Backend owner | Data impact | |---|---|---|---|---| ## 7. Risks - License risk: - Stack mismatch: - Data ownership risk: - UX dominance risk: - Security/privacy risk: - Migration risk: - Maintenance risk: ## 8. Decision - Recommendation: mimic / defer / annex-later / reject - First-pass priority: high / medium / low / none - Required Kintsugi docs to update: - Required ADR if any: ## 9. Evidence - Files inspected: - Models inspected: - Routes inspected: - Components inspected: - Tests inspected: ``` --- ## 8. Repository reading checklist Every repository must be inspected against the same checklist. ```yaml id="r56tx9" REPO_READING_CHECKLIST: IDENTITY: - "README" - "license file" - "package manager / dependency file" - "deployment files" - "documentation index" STACK: - "frontend framework" - "backend framework" - "database" - "job queue" - "auth system" - "API style" DOMAIN: - "core civic entities" - "proposal/debate/topic models" - "vote/stance models" - "comment/argument models" - "draft/document models" - "process/phase models" - "accountability/outcome models" INTEGRATION: - "API routes" - "service layer" - "adapters" - "webhooks" - "exports/imports" - "background jobs" GOVERNANCE: - "roles" - "permissions" - "moderation" - "audit logs" - "privacy/confidentiality" - "anonymity" TESTING: - "unit tests" - "integration tests" - "e2e tests" - "fixtures" - "seed data" EXTRACTABILITY: - "standalone pattern" - "deeply coupled pattern" - "license-sensitive pattern" - "too stack-specific" - "safe to mimic in Ethikos" ``` --- ## 9. Evaluation rubric Each discovered pattern must be scored. ```yaml id="b6op6b" PATTERN_SCORE: PRODUCT_FIT: 0: "not relevant" 1: "interesting but weak fit" 2: "useful" 3: "strong fit" 4: "core Kintsugi fit" ARCHITECTURE_FIT: 0: "conflicts with Konnaxion" 1: "requires major rewrite" 2: "requires significant adaptation" 3: "fits with modest adaptation" 4: "fits natively" IMPLEMENTATION_COST: 0: "not implementable" 1: "high cost" 2: "medium cost" 3: "low cost" 4: "configuration/UI only" RISK: 0: "unacceptable" 1: "high risk" 2: "medium risk" 3: "low risk" 4: "minimal risk" FIRST_PASS_PRIORITY: 0: "reject" 1: "defer" 2: "consider" 3: "include if easy" 4: "include" ``` A first-pass mimic candidate should normally score: ```yaml id="tsex46" FIRST_PASS_MINIMUM: PRODUCT_FIT: ">= 3" ARCHITECTURE_FIT: ">= 3" IMPLEMENTATION_COST: ">= 2" RISK: ">= 3" ``` --- ## 10. First-pass source plans ## 10.1 Consider.it ```yaml id="w7v4fg" SOURCE: NAME: "Consider.it" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 2 — Deliberation" PRIMARY_ROUTE_TARGET: "/ethikos/deliberate/*" SECONDARY_ROUTE_TARGETS: - "/ethikos/pulse/*" - "/ethikos/insights" EXPECTED_PATTERN: - "reason capture" - "pro/con deliberation compression" - "structured rationale summaries" - "opinion positioning if present" ``` ### Reading goals Inspect Consider.it for: * how pro/con reasons are represented; * whether reasons are separate from votes; * whether it supports stance positioning; * how arguments/reasons are clustered or summarized; * whether participants can compare their position to others; * what moderation or admin primitives exist; * whether there are exportable decision artifacts. ### Konnaxion mapping ```yaml id="x4q98a" CONSIDER_IT_MAPPING: reason: "EthikosArgument" pro_con_side: "EthikosArgument.side" stance_position: "EthikosStance" reason_cluster: "ArgumentGraph / future summary artifact" route_target: "/ethikos/deliberate/[topic]" ``` ### First-pass likely mimic ```yaml id="u9jujl" FIRST_PASS_MIMIC: - "clearer pro/con reason capture" - "argument compression panel" - "reason summary by stance bucket" - "participant-position context if simple" ``` ### Defer ```yaml id="hvm0cm" DEFER: - "full opinion-map engine" - "complex clustering" - "direct external code reuse" ``` --- ## 10.2 Kialo-style argument mapping ```yaml id="5aps0h" SOURCE: NAME: "Kialo-style argument mapping" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 2 — Deliberation" PRIMARY_ROUTE_TARGET: "/ethikos/deliberate/[topic]" EXPECTED_PATTERN: - "thesis" - "claim" - "pro/con edge" - "sources" - "impact voting" - "discussion topology" - "roles" - "visibility" - "perspectives" ``` Kialo is the canonical first-pass structured deliberation reference for Korum. Its documentation contains explicit patterns for discussion topology, sources, background information, perspectives, scheduled start/stop windows, and small-group controls. ### Reading goals Inspect Kialo-style source material for: * single-thesis vs multi-thesis topology; * claim creation; * pro/con relation semantics; * source/citation attachment; * discussion-level source views; * impact vote semantics; * anonymous discussions; * author visibility; * vote visibility; * participant roles; * suggested claims; * perspectives; * templates; * small groups; * discussion lifecycle start/stop; * export behavior. ### Konnaxion mapping ```yaml id="4g8ydk" KIALO_MAPPING: Discussion: "EthikosTopic" Thesis: "EthikosTopic.title + description / future thesis field" Claim: "EthikosArgument" ProConEdge: "EthikosArgument.parent + EthikosArgument.side" Source: "ArgumentSource" ImpactVote: "ArgumentImpactVote" SuggestedClaim: "ArgumentSuggestion" Perspective: "DiscussionPerspective / Smart Vote lens depending context" ParticipantRole: "DiscussionParticipantRole" ``` ### First-pass likely mimic ```yaml id="28esp2" FIRST_PASS_MIMIC: - "argument tree using current EthikosArgument.parent" - "pro/con/neutral side enforcement" - "claim source attachment" - "discussion-level sources panel" - "claim impact vote separated from EthikosStance" - "suggested claims queue" - "basic participant role settings" - "background info block" - "single-thesis default" ``` ### Defer ```yaml id="wsyspg" DEFER: - "small group mode" - "sunburst minimap" - "clone-from-template" - "custom perspectives" - "discussion export" - "move/link claim between discussions" ``` ### Hard anti-drift rules ```yaml id="0dql4d" KIALO_FORBIDDEN: - "Do not rename EthikosArgument to Claim." - "Do not create a new Kialo app." - "Do not create /kialo routes." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." ``` --- ## 10.3 Loomio ```yaml id="o35q1d" SOURCE: NAME: "Loomio" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 4 — Decision" PRIMARY_ROUTE_TARGET: "/ethikos/decide/*" SECONDARY_ROUTE_TARGETS: - "/ethikos/admin/*" - "/ethikos/learn/*" EXPECTED_PATTERN: - "proposal lifecycle" - "decision protocol" - "timeboxed decision" - "outcome publication" - "participant notification" ``` The currently available Loomio documentation focuses on authentication and account linking, so code-reading must go beyond docs and inspect actual proposal, poll, outcome, group, and permission implementation if present. ### Reading goals Inspect Loomio for: * proposal models; * poll/vote models; * decision closing behavior; * outcome publishing; * group permissions; * notification triggers; * timeboxed participation; * discussion-to-decision transition; * reason/comment capture around decisions. ### Konnaxion mapping ```yaml id="ttghpi" LOOMIO_MAPPING: group: "Ethikos participation context / future consultation group" proposal: "DecisionRecord" poll: "DecisionProtocol instance" vote: "BallotEvent or Smart Vote Vote depending context" outcome: "DecisionRecord.published_outcome" closing_at: "DecisionRecord.closes_at" ``` ### First-pass likely mimic ```yaml id="z9rd0z" FIRST_PASS_MIMIC: - "decision lifecycle states" - "proposal open/close window" - "outcome summary" - "decision protocol vocabulary" - "result publishing pattern" ``` ### Defer ```yaml id="coueh7" DEFER: - "full Loomio group model" - "email/code auth patterns" - "OAuth/SSO account-linking logic" - "native Loomio notifications" ``` --- ## 10.4 Citizen OS ```yaml id="ba8hio" SOURCE: NAME: "Citizen OS" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 3 — Drafting" PRIMARY_ROUTE_TARGET: "/ethikos/decide/* or future bounded drafting surface" SECONDARY_ROUTE_TARGETS: - "/ethikos/deliberate/*" - "/ethikos/impact/*" EXPECTED_PATTERN: - "collaborative drafting" - "topic phases" - "document editing" - "versioning" - "signing/voting transition" ``` Citizen OS documentation indicates a separated architecture with frontend, API, and Etherpad integration, which makes direct first-pass integration inappropriate. The first pass should mimic drafting patterns, not import infrastructure. ### Reading goals Inspect Citizen OS for: * topic lifecycle states; * draft/document models; * versioning patterns; * comments around text; * editing permissions; * transition from discussion to vote; * Etherpad integration boundaries; * exports; * user roles and groups. ### Konnaxion mapping ```yaml id="5h4rl5" CITIZEN_OS_MAPPING: Topic: "EthikosTopic / Consultation" DraftDocument: "Draft" DraftVersion: "DraftVersion" TextProposal: "Amendment" VotePhase: "DecisionRecord" Comment: "EthikosArgument or DraftComment depending scope" ``` ### First-pass likely mimic ```yaml id="fujqbe" FIRST_PASS_MIMIC: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" - "transition from deliberation to draft to decision" ``` ### Defer ```yaml id="9kc77l" DEFER: - "Etherpad integration" - "real-time collaborative editing" - "full Citizen OS API compatibility" - "document signing infrastructure" ``` --- ## 10.5 Decidim ```yaml id="q0gf7a" SOURCE: NAME: "Decidim" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 5 — Process and accountability" PRIMARY_ROUTE_TARGET: "/ethikos/impact/*" SECONDARY_ROUTE_TARGETS: - "/ethikos/admin/*" - "/ethikos/pulse/*" - "/ethikos/learn/*" EXPECTED_PATTERN: - "participatory process architecture" - "components" - "phases" - "proposals" - "accountability" - "admin governance" ``` Decidim’s documentation is developer-oriented and generated through an Antora/AsciiDoc system, with extensive modules beyond the root README. ### Reading goals Inspect Decidim for: * participatory process model; * component architecture; * proposals; * debates; * meetings; * consultations; * surveys; * accountability components; * admin permissions; * audit logs; * scopes/areas/taxonomies; * lifecycle phase configuration; * public result/accountability pages. ### Konnaxion mapping ```yaml id="3thg7x" DECIDIM_MAPPING: ParticipatoryProcess: "Ethikos Process / ConsultationProcess" Phase: "ProcessPhase" Proposal: "DecisionRecord or Draft depending stage" AccountabilityResult: "ImpactTrack" AdminPermission: "Ethikos admin role" Taxonomy: "EthikosCategory / TopicTag" ``` ### First-pass likely mimic ```yaml id="6y0qnx" FIRST_PASS_MIMIC: - "process phases" - "accountability tracker" - "public milestone/status view" - "admin process controls" - "taxonomy-aware process grouping" ``` ### Defer ```yaml id="hdwa84" DEFER: - "full component marketplace" - "full Decidim admin architecture" - "direct GraphQL/API compatibility" - "full participatory-space abstraction" ``` --- ## 10.6 CONSUL Democracy ```yaml id="nr6atv" SOURCE: NAME: "CONSUL Democracy" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 4/5 — Decision and accountability" PRIMARY_ROUTE_TARGET: "/ethikos/decide/*" SECONDARY_ROUTE_TARGETS: - "/ethikos/admin/*" - "/ethikos/impact/*" EXPECTED_PATTERN: - "proposal thresholds" - "eligibility" - "census" - "participatory budgeting concepts" - "admin customization" ``` CONSUL documentation includes customization surfaces for controllers, components, models, routes, CSS, tests, and translations, which suggests strong platform-level coupling; first pass should mimic policy patterns, not stack structure. ### Reading goals Inspect CONSUL for: * proposal model; * support/endorsement thresholds; * voting eligibility; * census integration; * budget allocation; * admin controls; * moderation; * result publication; * accountability tracking; * customization extension points. ### Konnaxion mapping ```yaml id="weqi5e" CONSUL_MAPPING: Proposal: "DecisionRecord" SupportThreshold: "EligibilityRule / DecisionProtocol.threshold" CensusEligibility: "EligibilityRule" BudgetVote: "Future decision modality" ResultPublication: "ReadingResult / DecisionRecord outcome" Accountability: "ImpactTrack" ``` ### First-pass likely mimic ```yaml id="g3afep" FIRST_PASS_MIMIC: - "eligibility rules" - "proposal thresholds" - "public participation gates" - "support count / threshold display" - "accountability-style status" ``` ### Defer ```yaml id="zz6xco" DEFER: - "full participatory budgeting" - "census integration" - "Rails customization pattern" - "direct CONSUL route/controller model" ``` --- ## 10.7 DemocracyOS ```yaml id="avlmda" SOURCE: NAME: "DemocracyOS" FIRST_PASS_STATUS: "mimic" PRIMARY_KINTSUGI_STAGE: "Stage 2/4 — Deliberation and decision" PRIMARY_ROUTE_TARGET: "/ethikos/decide/*" SECONDARY_ROUTE_TARGETS: - "/ethikos/deliberate/*" - "/ethikos/admin/*" EXPECTED_PATTERN: - "proposal-centric policy debate" - "forum/topic organization" - "commentary around proposals" - "roles and permissions" - "visibility configuration" ``` DemocracyOS documentation includes configuration and install docs, suggesting that code-reading should focus on proposal, topic, forum, role, and permission models rather than operational setup. ### Reading goals Inspect DemocracyOS for: * proposal/topic models; * forum or space models; * discussion/comment models; * vote behavior; * role/permission settings; * visibility settings; * tags/categories; * admin configuration; * notification and activity patterns. ### Konnaxion mapping ```yaml id="3ew1k3" DEMOCRACY_OS_MAPPING: Proposal: "DecisionRecord" Forum: "Ethikos process or category context" Topic: "EthikosTopic" Comment: "EthikosArgument" Vote: "BallotEvent or Smart Vote Vote depending decision context" Visibility: "DiscussionVisibilitySetting" ``` ### First-pass likely mimic ```yaml id="0vck29" FIRST_PASS_MIMIC: - "proposal-centric debate page" - "clear proposal status" - "discussion attached to policy/proposal" - "visibility/role controls" ``` ### Defer ```yaml id="itdnht" DEFER: - "full DemocracyOS configuration model" - "foreign forum architecture" - "direct Mongo/Node assumptions" ``` --- ## 11. Deferred source policy The following sources are not part of first-pass code reading. ```yaml id="blcznk" DEFERRED_SOURCE_POLICY: Polis: status: "deferred_public_credit_only" reason: "valuable consensus/opinion mapping, but not first-pass scope" LiquidFeedback: status: "deferred_public_credit_only" reason: "delegation/governance math too complex for first pass" All_Our_Ideas: status: "deferred" reason: "pairwise ranking not required in first-pass Kintsugi" Your_Priorities: status: "deferred" reason: "idea intake/prioritization later" OpenSlides: status: "deferred_possible_future_annex" reason: "assembly/parliament mode is outside first-pass Ethikos route upgrade" ``` If a future reader inspects these anyway, the result must be stored in a future research note, not folded into first-pass Kintsugi backlog. --- ## 12. Cross-source comparison matrix After all first-pass repos are read, produce a comparison table. ```markdown id="m66jcf" | Source | Real code feature | Useful pattern | Route target | Data target | Mimic now | Defer | Reject | Notes | |---|---|---|---|---|---:|---:|---:|---| | Consider.it | | | /ethikos/deliberate/* | EthikosArgument | | | | | | Kialo-style | | | /ethikos/deliberate/* | EthikosArgument + extensions | | | | | | Loomio | | | /ethikos/decide/* | DecisionRecord | | | | | | Citizen OS | | | Drafting / Decide | Draft / Amendment | | | | | | Decidim | | | /ethikos/impact/* | ProcessPhase / ImpactTrack | | | | | | CONSUL Democracy | | | /ethikos/decide/* | EligibilityRule / DecisionProtocol | | | | | | DemocracyOS | | | /ethikos/decide/* | DecisionRecord / EthikosArgument | | | | | ``` --- ## 13. Required final OSS reading deliverables The OSS code-reading phase must produce these outputs before implementation backlog generation. ```yaml id="6ongkh" REQUIRED_DELIVERABLES: - "OSS_READING_REPORT_CONSIDER_IT.md" - "OSS_READING_REPORT_KIALO_STYLE.md" - "OSS_READING_REPORT_LOOMIO.md" - "OSS_READING_REPORT_CITIZEN_OS.md" - "OSS_READING_REPORT_DECIDIM.md" - "OSS_READING_REPORT_CONSUL_DEMOCRACY.md" - "OSS_READING_REPORT_DEMOCRACY_OS.md" - "OSS_CROSS_SOURCE_COMPARISON.md" - "OSS_PATTERN_TO_ETHIKOS_ROUTE_MAPPING.md" - "OSS_RISK_AND_LICENSE_NOTES.md" ``` These are working reports, not permanent Kintsugi pack files unless promoted later. --- ## 14. Evidence rules Every OSS code-reading report must cite concrete evidence. ```yaml id="l5i90p" EVIDENCE_REQUIRED: - "file path inspected" - "model/entity file path" - "controller/view/route file path" - "frontend component file path" - "test file path if available" - "configuration file path" - "license file path" ``` Forbidden evidence style: ```yaml id="6gf6lq" FORBIDDEN_EVIDENCE: - "The docs say it has X, so code must have X." - "The product is known for X, so implement X." - "This seems similar to Konnaxion, so merge it." - "The README implies a feature, so assume its data model." ``` Correct evidence style: ```yaml id="4od0tb" CORRECT_EVIDENCE: - "Feature found in model file X and controller Y." - "Docs mention feature, but code path not found." - "Code implements feature, but stack coupling is too high." - "Pattern is useful, but must be mimicked as native Ethikos data." ``` --- ## 15. License and dependency review Before any pattern is promoted to implementation backlog, record: ```yaml id="nbss53" LICENSE_REVIEW_FIELDS: repository_name: "" license_detected: "" license_file_path: "" copyleft_risk: "none | low | medium | high | unknown" attribution_required: "yes | no | unknown" code_reuse_allowed: "yes | no | unknown" mimic_allowed: "yes | no | unknown" notes: "" ``` First-pass Kintsugi assumes: ```yaml id="wmz27h" LICENSE_POLICY: DIRECT_CODE_REUSE_DEFAULT: false PRODUCT_PATTERN_MIMIC_DEFAULT: true ATTRIBUTION_REQUIRED_IN_PUBLIC_CREDIT: true LEGAL_REVIEW_REQUIRED_FOR_IMPORT: true ``` --- ## 16. Stack compatibility review Each repo must be classified by stack compatibility. ```yaml id="xti57y" STACK_COMPATIBILITY_LEVELS: native_fit: description: "Pattern fits Konnaxion's Next.js + Django/DRF architecture." mimic_fit: description: "Pattern useful but source stack differs; mimic natively." adapter_fit_later: description: "Could become a sidecar or adapter later." reject: description: "Stack or architecture conflicts with Konnaxion goals." ``` Expected defaults: ```yaml id="xebkpd" EXPECTED_STACK_DEFAULTS: ConsiderIt: "mimic_fit" KialoStyle: "mimic_fit" Loomio: "mimic_fit" CitizenOS: "mimic_fit" Decidim: "mimic_fit" CONSULDemocracy: "mimic_fit" DemocracyOS: "mimic_fit" ``` --- ## 17. Route-mapping discipline All useful patterns must map to existing ethiKos route families. The current route structure is already explicit and should not be replaced by older simplified `/debate`, `/consult`, or `/reputation` concepts. ```yaml id="4glwgq" ROUTE_MAPPING_RULES: ConsiderIt: primary: "/ethikos/deliberate/*" KialoStyle: primary: "/ethikos/deliberate/*" Loomio: primary: "/ethikos/decide/*" CitizenOS: primary: "/ethikos/decide/*" possible_future: "/ethikos/draft/* only if separately approved" Decidim: primary: "/ethikos/impact/*" secondary: "/ethikos/admin/*" CONSULDemocracy: primary: "/ethikos/decide/*" secondary: "/ethikos/admin/*" DemocracyOS: primary: "/ethikos/decide/*" secondary: "/ethikos/deliberate/*" ``` Forbidden: ```yaml id="2cs3qk" FORBIDDEN_ROUTE_OUTPUTS: - "/kialo" - "/loomio" - "/decidim" - "/consul" - "/democracyos" - "/kintsugi as separate product app" - "/api/deliberation/..." ``` --- ## 18. Backend-mapping discipline The current Konnaxion backend is a Django modular monolith with DRF under `/api/...`; this must remain the implementation reality. ```yaml id="xxm30m" BACKEND_MAPPING_RULES: KORUM_PATTERNS: target_app: "konnaxion.ethikos" allowed_current_models: - "EthikosTopic" - "EthikosStance" - "EthikosArgument" - "EthikosCategory" DECISION_PATTERNS: target_app: "konnaxion.ethikos or kollective_intelligence depending exact ownership" proposed_models: - "DecisionProtocol" - "DecisionRecord" - "EligibilityRule" READING_PATTERNS: target_app: "konnaxion.kollective_intelligence / Smart Vote layer" proposed_models: - "LensDeclaration" - "ReadingResult" DRAFTING_PATTERNS: target_app: "konnaxion.ethikos" proposed_models: - "Draft" - "DraftVersion" - "Amendment" - "RationalePacket" IMPACT_PATTERNS: target_app: "konnaxion.ethikos / Konsultations ownership" proposed_models: - "ImpactTrack" - "ImpactUpdate" ``` Forbidden: ```yaml id="d0onjs" FORBIDDEN_BACKEND_OUTPUTS: - "Create konnaxion.kialo" - "Create konnaxion.loomio" - "Create konnaxion.decidim" - "Create Rails sidecar in first pass" - "Create Node/Mongo dependency in first pass" - "Let external tool write directly to Ethikos core tables" ``` --- ## 19. Frontend-mapping discipline The Konnaxion frontend uses a shared shell, Ant Design, and module-specific page shells. Module pages plug into the global shell rather than acting as separate top-level apps. ```yaml id="7ynyr4" FRONTEND_MAPPING_RULES: USE_EXISTING_SHELL: true USE_ETHIKOS_PAGE_SHELL: true USE_PAGE_CONTAINER: true USE_SERVICES_LAYER: true RAW_FETCH_IN_COMPONENTS: "avoid" NEW_TOP_LEVEL_FOREIGN_UI: false ``` Every UI pattern found in OSS must be translated into one of: ```yaml id="gbszt3" ETHIKOS_UI_TARGETS: - "Deliberate topic page" - "Argument tree component" - "Sources panel" - "Decision workflow card" - "Decision result view" - "Impact tracker" - "Admin moderation/audit view" - "Insights analytics panel" - "Learn/methodology explanation" ``` --- ## 20. Security, privacy, and governance review Every repo must be checked for governance-relevant behavior. ```yaml id="a9i4gr" SECURITY_PRIVACY_GOVERNANCE_CHECKLIST: - "authentication model" - "authorization model" - "role hierarchy" - "anonymous or pseudonymous participation" - "author visibility" - "vote visibility" - "moderation workflow" - "audit logs" - "export behavior" - "personal data exposure" - "admin override capabilities" ``` For Kintsugi, these are especially important: ```yaml id="xjov9r" KINTSUGI_SENSITIVE_AREAS: - "anonymous deliberation" - "expertise-weighted voting" - "EkoH score exposure" - "moderator identity visibility" - "suggested claim approval" - "result publication" - "source/evidence export" ``` --- ## 21. Code-reading order Use this exact order. ```yaml id="y1y3ft" RECOMMENDED_READING_ORDER: 1: source: "Kialo-style" reason: "Defines the strongest Korum / Deliberate contract." 2: source: "Consider.it" reason: "Complements Kialo with reason capture and deliberation compression." 3: source: "Loomio" reason: "Clarifies proposal lifecycle and decision protocols." 4: source: "Citizen OS" reason: "Clarifies drafting/versioning patterns." 5: source: "Decidim" reason: "Clarifies process/accountability architecture." 6: source: "CONSUL Democracy" reason: "Clarifies eligibility and threshold mechanics." 7: source: "DemocracyOS" reason: "Clarifies proposal-centric policy debate." ``` --- ## 22. Promotion rule: from code-reading to backlog A pattern can enter the implementation backlog only if all conditions are true. ```yaml id="8s1qwc" PROMOTION_CONDITIONS: - "The pattern exists in code or is clearly documented as a product behavior." - "The pattern maps to an existing Ethikos route family." - "The pattern does not require full external merge." - "The pattern can be implemented natively in Konnaxion." - "The ownership boundary is clear." - "The data model impact is known." - "The API/service impact is known." - "The test impact is known." - "The risk level is acceptable." - "The relevant Kintsugi doc is updated or referenced." ``` A pattern must be rejected or deferred if: ```yaml id="dhicf2" DEFER_OR_REJECT_WHEN: - "It requires replacing Ethikos route families." - "It requires direct foreign DB writes." - "It requires importing a large external stack." - "It conflicts with Korum/Konsultations/Smart Vote/EkoH ownership." - "It duplicates an existing Konnaxion capability." - "It depends on deferred sources." - "It cannot be tested safely in the current stack." ``` --- ## 23. Anti-drift rules ```yaml id="vyz4ww" ANTI_DRIFT_RULES: - "Do not inspect OSS code before the Kintsugi documentation contracts are stable." - "Do not convert repo findings directly into implementation tasks." - "Do not assume README/product claims equal implemented code." - "Do not import external code in first pass." - "Do not create foreign route families." - "Do not create foreign Django apps for first-pass mimic." - "Do not replace /ethikos/* with OSS-native navigation." - "Do not replace /api/ethikos/* with invented endpoints." - "Do not expand /api/home/* usage." - "Do not treat deferred sources as first-pass." - "Do not let a powerful OSS architecture dominate Konnaxion architecture." - "Do not mix product strategy, code-reading, and implementation backlog in the same artifact." ``` --- ## 24. Acceptance checklist This document is satisfied when the OSS code-reading phase can produce: ```yaml id="nrl3hi" ACCEPTANCE_CHECKLIST: per_repo_reports: - "Each first-pass source has a code-reading report." - "Each report identifies stack, license, core models, routes, and permissions." - "Each report distinguishes code reality from product idea." - "Each report maps patterns to /ethikos/* route families." - "Each report recommends mimic, defer, annex-later, or reject." cross_source_outputs: - "A cross-source comparison matrix exists." - "A pattern-to-route mapping exists." - "A risk/license note exists." - "Deferred sources remain deferred." drift_control: - "No full merge is recommended." - "No external route family is created." - "No external app is created for first pass." - "No implementation backlog is generated before reading reports." ``` --- ## 25. Related documents ```yaml id="npx7yx" RELATED_DOCS: - "00_KINTSUGI_START_HERE.md" - "01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md" - "02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md" - "03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md" - "04_CANONICAL_NAMING_AND_VARIABLES.md" - "05_CURRENT_STATE_BASELINE.md" - "06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md" - "07_API_AND_SERVICE_CONTRACTS.md" - "08_DATA_MODEL_AND_MIGRATION_PLAN.md" - "10_FIRST_PASS_INTEGRATION_MATRIX.md" - "11_MIMIC_VS_ANNEX_RULEBOOK.md" - "14_FRONTEND_ALIGNMENT_CONTRACT.md" - "15_BACKEND_ALIGNMENT_CONTRACT.md" - "18_ADR_REGISTER.md" - "20_AI_GENERATION_GUARDRAILS.md" - "21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md" - "22_IMPLEMENTATION_BACKLOG_TEMPLATE.md" ``` --- ## 26. Final normative summary ```yaml id="qkpp80" FINAL_CONTRACT: OSS_CODE_READING_PURPOSE: "extract patterns, not import systems" FIRST_PASS_STRATEGY: "native mimic" FULL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false PRIMARY_ROUTE_SURFACE: "/ethikos/*" PRIMARY_BACKEND_STYLE: "Django REST Framework under /api/..." PRIMARY_FRONTEND_STYLE: "Next.js App Router inside shared Konnaxion shell" FIRST_PASS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" DEFERRED_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" OUTPUT_BEFORE_BACKLOG: - "per-repo reading reports" - "cross-source comparison" - "pattern-to-route mapping" - "risk/license notes" ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/20_AI_GENERATION_GUARDRAILS.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b7894326ff28ca723c2e2b251d76e0d823d6b267ee6b5d2ea091f5ef806bd4f8 CONTENT_BYTES: 36195 ================================================================================================ # 20 — AI Generation Guardrails **File:** `20_AI_GENERATION_GUARDRAILS.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Status:** Canonical AI-generation constraint document **Module:** `ethiKos` **Platform:** `Konnaxion` --- ## 1. Purpose This document defines mandatory guardrails for any AI system generating documentation, code plans, implementation tickets, refactors, migrations, tests, or architectural analysis for the **ethiKos Kintsugi Upgrade**. Its purpose is to prevent: - route drift; - naming drift; - model drift; - endpoint drift; - ownership drift; - OSS integration drift; - Smart Vote / EkoH semantic drift; - Kialo-style deliberation drift; - accidental full rewrite proposals; - premature implementation backlog generation; - contradictory documents created in parallel AI conversations. This document is especially important because the Kintsugi documentation pack may be generated across multiple parallel AI conversations. Every AI session MUST obey this file and the canonical variables defined in `00_KINTSUGI_START_HERE.md`. --- ## 2. Scope This document applies to all AI-generated work related to the ethiKos Kintsugi Upgrade, including: - Kintsugi documentation files; - route plans; - API plans; - data model plans; - migration plans; - frontend plans; - backend plans; - ADRs; - OSS code-reading plans; - implementation backlog templates; - future implementation tickets; - code-generation prompts; - refactor prompts; - test-generation prompts; - bugfix prompts that touch Kintsugi-adjacent areas. This document applies whether the AI session is generating one file, several files, code patches, review comments, or implementation steps. --- ## 3. Canonical variables used ```yaml id="3jqbmr" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false BIG_BANG_REWRITE_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_ETHIKOS_FRAME_STABLE: true DOCS_BEFORE_CODE: true CODE_INSPECTION_AFTER_DOCS: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true ```` ```yaml id="n6b9yq" PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_ROUTE_FAMILIES: DECIDE: "/ethikos/decide/*" DELIBERATE: "/ethikos/deliberate/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" IMPACT: "/ethikos/impact/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" ``` ```yaml id="kppdy5" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_ENDPOINTS_CANONICAL: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" ``` ```yaml id="c1wtyr" OWNERSHIP: KORUM_OWNS: - "Topics" - "Arguments" - "Threaded argument graph" - "Topic-level stance events" - "Debate moderation" KONSULTATIONS_OWNS: - "Intake" - "Consultations" - "Citizen suggestions" - "Ballot capture" - "Result snapshots" - "Impact tracking" SMART_VOTE_OWNS: - "Derived readings" - "Lens declarations" - "Aggregations" - "Result publication" EKOH_OWNS: - "Expertise context" - "Ethics context" - "Cohort eligibility" - "Snapshots" ``` ```yaml id="ou9a60" KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ``` --- ## 4. Source-of-truth priority order When an AI session sees conflicting information, it MUST use this priority order. ```yaml id="b4rz8b" SOURCE_PRIORITY_ORDER: 1_CODE_SNAPSHOT_REALITY: description: "Routes, files, current endpoints, current models, current implementation state." 2_BOUNDARIES_DOC: description: "Korum/Konsultations/Smart Vote/EkoH ownership, write rules, pipeline." 3_CLEAN_SLATE_PLAN: description: "First-pass scope, no full merge, docs first, code inspection second." 4_KIALO_CORE_DOCS: description: "Structured deliberation contract for /ethikos/deliberate/*." 5_OSS_SOURCE_DOCS: description: "Pattern inspiration only; never direct merge in first pass." 6_PRIOR_MASTER_DOCS: description: "Use only after correcting scope and route reality." ``` Rules: * If code snapshot reality conflicts with an older conceptual doc, code snapshot reality wins for current implementation. * If ownership boundaries conflict with an OSS pattern, ownership boundaries win. * If an OSS pattern conflicts with ethiKos architecture, mimic the useful pattern only. * If a generated document conflicts with this guardrail file, this guardrail file wins unless a later ADR explicitly supersedes it. * If an AI session is unsure whether something is implemented, it MUST mark it as “requires code inspection” rather than inventing an answer. --- ## 5. Generation mode AI-generated Kintsugi work MUST follow these generation rules. ```yaml id="96khjh" GENERATION_MODE: DOCS_BEFORE_CODE: true GENERATE_ONE_FILE_PER_CONVERSATION: true EACH_CONVERSATION_MUST_OBEY_CANONICAL_VARIABLES: true DO_NOT_REINTERPRET_SCOPE: true DO_NOT_CREATE_NEW_ARCHITECTURE_UNLESS_DOC_EXPLICITLY_ASSIGNED: true IF_CONFLICT_USE_SOURCE_PRIORITY_ORDER: true ``` For parallel documentation generation: * one conversation SHOULD generate exactly one document; * each conversation MUST receive or reference the same canonical variable block; * each generated document MUST include its own purpose, scope, variables, non-goals, anti-drift rules, and related docs; * each generated document MUST avoid redefining global constants unless that is its assigned purpose. --- ## 6. Required output style AI-generated documentation SHOULD use: ```yaml id="uicrtr" OUTPUT_STYLE: LANGUAGE: "English technical documentation unless user explicitly asks French." FORMAT: "Markdown" TONE: "Precise, normative, implementation-aligned." NORMATIVE_TERMS_ALLOWED: - "MUST" - "MUST NOT" - "SHOULD" - "MAY" ``` Each document SHOULD include: ```text id="83qp4r" 1. Purpose 2. Scope 3. Canonical variables used 4. Source-of-truth references 5. Non-goals 6. Main contract or content 7. Anti-drift rules 8. Related documents ``` The AI MUST NOT use casual speculation such as: * “maybe we can just add...” * “it would be cool to...” * “let’s merge...” * “we can replace the architecture with...” * “I assume the endpoint is...” If uncertain, the AI MUST write: ```text id="08bxwp" Requires code inspection before implementation. ``` --- ## 7. Absolute forbidden outputs The following outputs are forbidden across the Kintsugi documentation pack and all related AI work. ```yaml id="6wqdaa" FORBIDDEN: - "Do not propose full external OSS merge." - "Do not create a new Kialo app." - "Do not create a new top-level Kintsugi frontend app." - "Do not rename EthikosArgument to Claim." - "Do not rename /api/ethikos/... to /api/deliberation/..." - "Do not convert EkoH into a voting engine." - "Do not let Smart Vote mutate upstream facts." - "Do not let foreign tools write to Korum/Konsultations core tables." - "Do not treat Kialo impact votes as Ethikos stances." - "Do not treat Kialo impact votes as Smart Vote ballots." - "Do not expand /api/home/*." - "Do not create a second layout shell." - "Do not create a second theme system." - "Do not produce implementation tasks before documentation contracts unless generating doc 22." ``` These forbidden outputs are binding. --- ## 8. Route guardrails The current primary route surface is: ```yaml id="n77mbx" PRIMARY_ROUTE_SURFACE: "/ethikos/*" ``` Allowed ethiKos route families: ```yaml id="vwtjz8" ALLOWED_ETHIKOS_ROUTE_FAMILIES: - "/ethikos/decide/*" - "/ethikos/deliberate/*" - "/ethikos/trust/*" - "/ethikos/pulse/*" - "/ethikos/impact/*" - "/ethikos/learn/*" - "/ethikos/insights" - "/ethikos/admin/*" ``` AI MUST NOT invent new route families such as: ```yaml id="wv7srh" FORBIDDEN_ROUTE_FAMILIES: - "/kialo/*" - "/kintsugi/*" - "/ethikos/kialo/*" - "/ethikos/kintsugi/*" - "/platforms/konnaxion/ethikos/*" - "/consult/*" - "/debate/*" - "/deliberation/*" ``` Exception: * A document MAY mention older conceptual routes as historical or public-facing references. * A document MUST NOT make them implementation targets unless a later route-plan ADR explicitly approves them. If a new route is proposed, it MUST be classified as: ```yaml id="qba72z" NEW_ROUTE_STATUS: - "concept_only" - "requires_route_plan" - "requires_ADR" - "not_first_pass" ``` --- ## 9. Endpoint guardrails Canonical API endpoints are: ```yaml id="pivemn" CURRENT_ENDPOINTS_CANONICAL: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" ``` Compatibility endpoints: ```yaml id="w90t43" CURRENT_ENDPOINTS_COMPATIBILITY: DELIBERATE_ALIAS: "/api/deliberate/..." DELIBERATE_ELITE_ALIAS: "/api/deliberate/elite/..." ``` Legacy/problematic endpoints: ```yaml id="rgfuto" LEGACY_OR_PROBLEMATIC_ENDPOINTS: API_HOME_PREFIX: "/api/home/*" RULE: "Do not expand /api/home/* usage. Replace, isolate, or mark legacy." ``` AI MUST NOT invent or promote endpoints such as: ```yaml id="ltrz3r" FORBIDDEN_OR_UNAPPROVED_ENDPOINTS: - "/api/deliberation/*" - "/api/kialo/*" - "/api/kintsugi/*" - "/api/citizenos/*" - "/api/loomio/*" - "/api/decidim/*" - "/api/consul/*" - "/api/democracyos/*" ``` If a future endpoint is needed, it MUST be defined in: ```text id="b0zqwz" 07_API_AND_SERVICE_CONTRACTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 15_BACKEND_ALIGNMENT_CONTRACT.md 18_ADR_REGISTER.md ``` --- ## 10. Model guardrails Current ethiKos models are: ```yaml id="jt7tv3" CURRENT_ETHIKOS_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" ``` AI MUST preserve these rules: ```yaml id="bfh5a3" MODEL_RULES: BREAK_EXISTING_MODELS: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_FIELDS: false ADD_NON_BREAKING_TABLES_ALLOWED: true ADD_NON_BREAKING_FIELDS_ALLOWED: true MIGRATIONS_REQUIRED_FOR_NEW_MODELS: true FUTURE_MAKEMIGRATIONS_DRIFT_MUST_BE_AVOIDED: true ``` Forbidden model changes: ```yaml id="9x35n1" FORBIDDEN_MODEL_CHANGES: - "Do not rename EthikosArgument to Claim." - "Do not rename EthikosTopic to Discussion." - "Do not rename EthikosStance to Vote." - "Do not remove EthikosArgument.parent." - "Do not remove EthikosArgument.side." - "Do not replace EthikosStance with Smart Vote." - "Do not store drafting version history directly inside EthikosArgument." - "Do not store Smart Vote readings directly as source facts on Korum records." ``` Allowed model planning: ```yaml id="fv3d0s" ALLOWED_MODEL_PLANNING: - "Add non-breaking support tables." - "Add non-breaking fields after migration review." - "Create derived-artifact tables for readings." - "Create drafting tables separate from arguments." - "Create Kialo-style support tables inside konnaxion.ethikos." - "Create annex boundary tables only as ExternalArtifact and ProjectionMapping." ``` --- ## 11. Ownership guardrails Ownership MUST remain stable. ```yaml id="rzweg3" OWNERSHIP_GUARDRAILS: KORUM: MUST_OWN: - "Topics used for deliberation" - "Arguments" - "Argument graph" - "Topic-level stance events" - "Debate moderation" KONSULTATIONS: MUST_OWN: - "Intake" - "Consultation ballots" - "Citizen suggestions" - "Result snapshots" - "Impact tracking" SMART_VOTE: MUST_OWN: - "Readings" - "Lens declarations" - "Aggregations" - "Published result interpretations" EKOH: MUST_OWN: - "Expertise context" - "Ethics context" - "Cohort eligibility" - "Snapshot context" ``` AI MUST NOT: * assign impact truth to KeenKonnect; * assign source facts to Smart Vote; * assign vote mutation to EkoH; * assign Korum arguments to an external tool; * assign Konsultations ballots to an external tool; * merge Korum and Konsultations ownership without an ADR. --- ## 12. Smart Vote and EkoH guardrails Smart Vote is a reading and aggregation layer. EkoH is an expertise, ethics, cohort, and snapshot context layer. They MUST NOT be collapsed. ```yaml id="1aoh2g" SMART_VOTE_EKOH_RULES: SMART_VOTE_MUTATES_KORUM_RECORDS: false SMART_VOTE_MUTATES_KONSULTATIONS_RECORDS: false SMART_VOTE_WRITES_ONLY_DERIVED_ARTIFACTS: true EKOH_IS_VOTING_ENGINE: false EKOH_MUTATES_VOTES: false WEIGHTED_OUTCOME_REQUIRES_REPRODUCIBILITY: true READING_FORMULA: "Reading = f(BaselineEvents, LensDeclaration, SnapshotContext?)" ``` Canonical reading fields: ```yaml id="8tgctu" SMART_VOTE_EKOH_FIELDS: BASELINE_READING: "raw_unweighted" WEIGHTED_READING: "declared_lens_output" SNAPSHOT_FIELD: "snapshot_ref" LEGACY_EKOH_SNAPSHOT_FIELD: "ekoh_snapshot_id" LENS_ID_FIELD: "reading_key" LENS_HASH_FIELD: "lens_hash" RESULT_PAYLOAD_FIELD: "results_payload" COMPUTED_AT_FIELD: "computed_at" ``` AI MUST NOT write: * “EkoH calculates the vote result”; * “Smart Vote updates the original stance”; * “Weighted vote replaces baseline vote”; * “The expertise score is the vote”; * “ReadingResult is the source vote”; * “EkoH is the voting engine.” Correct phrasing: ```text id="0gus2m" Smart Vote publishes declared readings derived from baseline events, lens declarations, and optional EkoH snapshot context. ``` --- ## 13. Vote-type separation guardrails AI MUST keep these three concepts separate. ```yaml id="r5s19s" VOTE_TYPE_SEPARATION: ETHIKOS_STANCE: RANGE: "-3..+3" LEVEL: "topic-level" OWNER: "Korum" MODEL: "EthikosStance" MEANING: "User stance on topic." KIALO_IMPACT_VOTE: RANGE: "0..4" LEVEL: "argument/claim-level" OWNER: "Korum" PROPOSED_MODEL: "ArgumentImpactVote" MEANING: "Impact of a claim on its parent; combines veracity and relevance." SMART_VOTE_READING: RANGE: "not fixed; depends on lens and modality" LEVEL: "derived aggregation" OWNER: "Smart Vote" PROPOSED_MODEL: "ReadingResult" MEANING: "Published derived reading of baseline events." ``` Forbidden conflations: ```yaml id="xv1gsw" FORBIDDEN_VOTE_CONFLATIONS: CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false ``` AI MUST NOT use “vote” generically when the distinction matters. Use the precise term: * `EthikosStance` * `ArgumentImpactVote` * `BallotEvent` * `ReadingResult` * `LensDeclaration` --- ## 14. Kialo-style guardrails Kialo-style argument mapping is a native mimic reference for Korum under `/ethikos/deliberate/*`. ```yaml id="c8bdcc" KIALO_GUARDRAILS: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ``` Canonical mapping: ```yaml id="rkjqzh" KIALO_CANONICAL_MAPPING: KIALO_DISCUSSION: "EthikosTopic" KIALO_THESIS: "Topic thesis/prompt field; current fallback is EthikosTopic.title + description" KIALO_CLAIM: "EthikosArgument" KIALO_PRO_CON_EDGE: "EthikosArgument.parent + EthikosArgument.side" KIALO_SOURCE: "ArgumentSource" KIALO_IMPACT_VOTE: "ArgumentImpactVote" KIALO_SUGGESTED_CLAIM: "ArgumentSuggestion" KIALO_PERSPECTIVE: "DiscussionPerspective / Smart Vote lens depending context" KIALO_PARTICIPANT_ROLE: "DiscussionParticipantRole" ``` AI MUST NOT: * create `konnaxion.kialo`; * create `/kialo`; * create `/ethikos/kialo`; * import Kialo code; * rename `EthikosArgument` to `Claim`; * collapse Kialo claim impact voting into `EthikosStance`; * allow suggested claims to publish without approval for `suggester`; * expose real identities in anonymous mode to normal participants. AI MAY use “claim” as a UX term if the document clearly states: ```text id="w85wng" Claim is the Kialo-style conceptual/UX term. The current backend model remains EthikosArgument. ``` --- ## 15. External OSS guardrails First-pass OSS sources: ```yaml id="wkzaj2" FIRST_PASS_OSS_SOURCES: - "Consider.it" - "Kialo-style argument mapping" - "Loomio" - "Citizen OS" - "Decidim" - "CONSUL Democracy" - "DemocracyOS" ``` Deferred OSS sources: ```yaml id="4u0m9a" DEFERRED_OSS_SOURCES: - "Polis" - "LiquidFeedback" - "All Our Ideas" - "Your Priorities" - "OpenSlides" ``` AI MUST interpret first-pass OSS sources as pattern inspiration only. ```yaml id="3jipe1" OSS_RULES: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" MIMIC_FIRST_PASS: true ANNEX_FIRST_PASS_ALLOWED: false FULL_CODE_IMPORT_DEFAULT: false ANNEX_REQUIRES_ISOLATION: true ANNEX_REQUIRES_REPLACEABILITY: true ANNEX_REQUIRES_NO_CORE_TABLE_WRITES: true ANNEX_REQUIRES_LICENSE_CLEARANCE: true ANNEX_REQUIRES_ADAPTER_LAYER: true ``` AI MUST NOT generate first-pass implementation plans for deferred sources. Allowed language: ```text id="fjbui7" Polis is deferred and may be referenced only as future inspiration or public credit. ``` Forbidden language: ```text id="lqvzwh" Implement Polis clustering in first pass. ``` --- ## 16. Mimic vs Annex guardrails Default strategy is native mimic. ```yaml id="ky2xob" MIMIC_VS_ANNEX: DEFAULT_EXTERNAL_TOOL_STRATEGY: "mimic" MIMIC_FIRST_PASS: true ANNEX_REQUIRES_ISOLATION: true ANNEX_REQUIRES_REPLACEABILITY: true ANNEX_REQUIRES_NO_CORE_TABLE_WRITES: true ANNEX_REQUIRES_LICENSE_CLEARANCE: true ANNEX_REQUIRES_ADAPTER_LAYER: true FULL_CODE_IMPORT_DEFAULT: false ``` Annex integration is not first pass. If a future annex is discussed, the AI MUST require: * `ExternalArtifact`; * `ProjectionMapping`; * read-only projection where possible; * no core table writes; * license clearance; * replaceability; * adapter layer; * ADR approval. AI MUST NOT say: ```text id="ma9xfc" Let's just plug in Decidim/Loomio/Citizen OS directly. ``` AI SHOULD say: ```text id="70do78" Mimic the pattern natively in ethiKos first. Consider annex only later if isolation, replaceability, license, and adapter requirements are satisfied. ``` --- ## 17. Frontend guardrails The frontend uses the existing Next.js App Router and shared shell. AI MUST preserve: ```yaml id="6yh91h" FRONTEND_GUARDRAILS: PRIMARY_ROUTE_SURFACE: "/ethikos/*" USE_EXISTING_ETHIKOS_LAYOUT: true USE_EXISTING_GLOBAL_SHELL: true USE_SERVICES_LAYER: true DO_NOT_CREATE_SECOND_SHELL: true DO_NOT_CREATE_SECOND_THEME_SYSTEM: true DO_NOT_CREATE_KIALO_ROUTE_FAMILY: true DO_NOT_CREATE_KINTSUGI_TOP_LEVEL_APP: true ``` AI MAY reference these existing shell concepts: ```yaml id="8cx6sw" EXISTING_LAYOUT_COMPONENTS: - "MainLayout" - "EthikosPageShell" - "PageContainer" - "Ant Design App context" ``` AI MUST NOT: * create a new Ethikos root layout; * create a separate Kialo shell; * create a second global navigation; * create a new theme switcher; * add direct raw fetches in page components unless explicitly documented as legacy; * bypass the service layer for new API calls. New frontend surfaces MUST be mapped to existing route families. Example: ```yaml id="7vj6t3" KIALO_STYLE_FRONTEND_SURFACES: ArgumentTreeView: route: "/ethikos/deliberate/[topic]" ArgumentSourcesPanel: route: "/ethikos/deliberate/[topic]" SuggestedClaimsPanel: route: "/ethikos/deliberate/[topic] and /ethikos/admin/moderation" GuidedVotingDrawer: route: "/ethikos/deliberate/[topic]" ``` --- ## 18. Backend guardrails The backend is Django/DRF. ```yaml id="moyf2g" BACKEND_GUARDRAILS: ETHIKOS_BACKEND_APP: "konnaxion.ethikos" KOLLECTIVE_BACKEND_APP: "konnaxion.kollective_intelligence" USERS_APP: "konnaxion.users" AUTH_USER_MODEL: "users.User" ROOT_URLCONF: "config.urls" API_ROUTER_FILE: "config/api_router.py" DEFAULT_API_STYLE: "Django REST Framework ViewSet + Serializer + Router" DEFAULT_DB: "PostgreSQL" ``` AI MUST NOT: * suggest replacing Django with Rails; * suggest replacing PostgreSQL with MongoDB; * suggest adding GraphQL for first-pass CRUD; * suggest moving Ethikos to a microservice; * create a new backend app for each OSS source; * create a second user model; * reference `auth.User` as the user model; * bypass DRF serializers/viewsets/routers for standard CRUD. AI MAY propose new DRF viewsets only if they align with: * `07_API_AND_SERVICE_CONTRACTS.md`; * `08_DATA_MODEL_AND_MIGRATION_PLAN.md`; * `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md`; * `15_BACKEND_ALIGNMENT_CONTRACT.md`. --- ## 19. Drafting guardrails Drafting is a bounded ethiKos capability. Citizen OS may inspire drafting and versioning, but AI MUST NOT import external collaborative editing infrastructure in first pass. ```yaml id="g3puka" DRAFTING_GUARDRAILS: DRAFTING_IS_BOUNDED_ETHIKOS_CAPABILITY: true CITIZEN_OS_STRATEGY: "native_mimic" ETHERPAD_ANNEX_FIRST_PASS: false DRAFTS_ARE_NOT_ARGUMENTS: true DRAFT_VERSIONS_ARE_NOT_ARGUMENT_THREADS: true ``` AI MUST separate: * `EthikosArgument` = deliberation contribution; * `Draft` = decision-ready text container; * `DraftVersion` = versioned text state; * `Amendment` = proposed text change; * `RationalePacket` = explanation of text choices. AI MUST NOT store drafting history directly in argument threads. --- ## 20. Impact guardrails Impact belongs to Konsultations/accountability truth, not KeenKonnect source truth. ```yaml id="62x1xe" IMPACT_GUARDRAILS: IMPACT_BELONGS_TO: "Konsultations + accountability handoff" IMPACT_DOES_NOT_BELONG_TO: "KeenKonnect as source of truth" KEENKONNECT_MAY_RECEIVE_HANDOFF: true KEENKONNECT_MUST_NOT_OWN_CIVIC_IMPACT_TRUTH: true ``` AI MUST NOT: * make `Project` the canonical civic impact record; * treat KeenKonnect as the source of truth for decisions; * collapse implementation project tracking and civic accountability tracking. Correct framing: ```text id="0oi55h" Konsultations owns civic impact tracking. KeenKonnect may receive execution handoff links after a decision. ``` --- ## 21. Known bug guardrails Known bug: ```yaml id="uacfix" KNOWN_BUGS: BUG_001: TITLE: "Deliberate preview drawer shows 'Preview / No data'" STATUS: "known_open" CLASSIFICATION: "targeted_bugfix_not_architecture" DO_NOT_USE_TO_REDESIGN_KINTSUGI: true ``` AI MUST NOT use this bug to justify: * route rewrite; * service rewrite; * backend redesign; * new preview architecture; * moving deliberation out of Ethikos; * replacing current pages. AI MAY say: ```text id="44lo5h" The preview drawer bug should be tracked separately as a targeted bugfix. ``` --- ## 22. Backlog guardrails The documentation pack must precede the implementation backlog. AI MUST NOT generate implementation tasks unless the assigned document is: ```text id="6smlo6" 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` or the user explicitly asks for a backlog after the docs have been generated. Forbidden in most documents: * “Task 1: create model...” * “Task 2: update serializer...” * “Sprint plan...” * “Implementation tickets...” * “Patch this file...” Allowed in planning docs: ```text id="u906ix" First-pass model candidate Requires code inspection Potential future migration Route target Service contract target ``` --- ## 23. Parallel-generation guardrails When generating documentation in parallel conversations: ```yaml id="60kpxx" PARALLEL_GENERATION_RULES: ONE_FILE_PER_CONVERSATION: true SAME_CANONICAL_VARIABLE_BLOCK_REQUIRED: true DO_NOT_GENERATE_OTHER_FILES: true DO_NOT_RENUMBER_DOC_PACK: true DO_NOT_RENAME_ASSIGNED_FILE: true DO_NOT_CHANGE_CANONICAL_FOLDER: true ``` Each generated document MUST include: ```text id="54qwqx" File name Pack name Canonical path Version Status Purpose Scope Canonical variables used Non-goals Anti-drift rules Related documents ``` Each generated document SHOULD refer to related documents by filename, not by vague phrasing. Good: ```text id="4uk9dw" See 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md. ``` Bad: ```text id="c2t3u4" See the other architecture doc. ``` --- ## 24. Language guardrails Default documentation language is English technical documentation. User-facing conversation may be French if the user writes in French, but generated files SHOULD remain English unless explicitly requested otherwise. Allowed: ```text id="vp5eal" Generate the Markdown file in English. ``` Allowed if explicitly requested: ```text id="jck5n2" Generate the Markdown file in French. ``` If uncertain, generate docs in English. --- ## 25. Naming guardrails Canonical display names: ```yaml id="oeyonw" PRODUCT_LANGUAGE: ETHIKOS_DISPLAY: "ethiKos" KORUM_DISPLAY: "Korum" KONSULTATIONS_DISPLAY: "Konsultations" SMART_VOTE_DISPLAY: "Smart Vote" EKOH_DISPLAY: "EkoH" KOLLECTIVE_INTELLIGENCE_DISPLAY: "Kollective Intelligence" ``` Canonical backend references: ```yaml id="cuigub" BACKEND_NAMES: ETHIKOS_BACKEND_APP: "konnaxion.ethikos" KOLLECTIVE_BACKEND_APP: "konnaxion.kollective_intelligence" USERS_APP: "konnaxion.users" ``` AI MUST NOT introduce inconsistent variants such as: ```yaml id="jzqfs4" FORBIDDEN_NAME_VARIANTS: - "EthicsOS" - "EthikosOS" - "Ethikos Kialo" - "Kialo module" - "Kintsugi app" - "SmartVote engine replacing Ethikos" - "EkoH voting engine" - "Korum app separate from Ethikos" - "Konsultations app separate from Ethikos" ``` Acceptable internal phrasing: ```text id="cnug2d" Korum is the structured debate submodule within ethiKos. Konsultations is the public consultation and accountability submodule within ethiKos. ``` --- ## 26. Payload and enum guardrails AI MUST use the canonical ranges and enum values unless a specific document proposes a change for review. ```yaml id="t17846" PAYLOAD_CONSTANTS: ID_TYPE_CURRENT_ETHIKOS: "integer" DATE_FORMAT: "ISO_8601" PAGINATION_STYLE: "DRF-compatible" ERROR_STYLE: "DRF-compatible" STANCE_VALUE_RANGE: "-3..+3" CLAIM_IMPACT_RANGE: "0..4" ``` Canonical enums: ```yaml id="feg84n" ENUMS: TOPIC_STATUS: - "open" - "closed" - "archived" ARGUMENT_SIDE: - "pro" - "con" - "neutral" DECISION_STATUS: - "draft" - "open" - "closed" - "published" - "archived" DRAFT_STATUS: - "draft" - "review" - "accepted" - "superseded" - "archived" IMPACT_STATUS: - "planned" - "in_progress" - "blocked" - "completed" - "cancelled" READING_STATUS: - "pending" - "computed" - "published" - "invalidated" AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" PARTICIPATION_TYPE: - "standard" - "anonymous" DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" ``` AI MUST NOT invent alternative enum values unless the document explicitly introduces them as proposed and non-canonical. --- ## 27. Required uncertainty language When code reality is unknown, AI MUST use uncertainty markers. Use: ```text id="6nvh1b" Requires code inspection before implementation. ``` Use: ```text id="ffmaba" This is a proposed support model, not a confirmed existing model. ``` Use: ```text id="ds7f73" This is a first-pass candidate, not a committed migration. ``` Do not use: ```text id="bn2ck8" The code already does this. ``` unless the code snapshot confirms it. --- ## 28. Guardrails by document ## 28.1 `00_KINTSUGI_START_HERE.md` MUST: * define the pack; * define first-pass scope; * define source priority; * define current baseline; * list all docs; * include final binding statement. MUST NOT: * include implementation tickets; * over-describe every model. --- ## 28.2 `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` MUST: * explain Kintsugi as native mimic; * explain the civic workflow; * define why external tools are inspiration only; * align with route families. MUST NOT: * revive deferred sources as first-pass work; * propose full platform merge. --- ## 28.3 `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` MUST: * define source hierarchy; * define conflict resolution; * define drift categories; * define AI behavior under uncertainty. MUST NOT: * duplicate all domain contracts. --- ## 28.4 `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` MUST: * lock Korum/Konsultations/Smart Vote/EkoH ownership; * lock write rules; * define stage ownership; * define foreign tool boundaries. MUST NOT: * create new model names casually; * blur source facts and derived readings. --- ## 28.5 `04_CANONICAL_NAMING_AND_VARIABLES.md` MUST: * define names, slugs, enums, route constants, endpoint constants; * be usable as copy/paste AI context. MUST NOT: * include strategy prose beyond what is needed. --- ## 28.6 `05_CURRENT_STATE_BASELINE.md` MUST: * reflect current code snapshot reality; * distinguish confirmed from proposed; * document known legacy endpoints. MUST NOT: * describe future features as current. --- ## 28.7 `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` MUST: * map Kintsugi onto actual `/ethikos/*` routes; * identify each route family’s role; * identify source inspirations per route. MUST NOT: * invent a new route family without ADR requirement. --- ## 28.8 `07_API_AND_SERVICE_CONTRACTS.md` MUST: * preserve `/api/ethikos/*`; * identify `/api/home/*` as legacy/problematic; * require service-layer wrappers. MUST NOT: * introduce `/api/deliberation/*`; * bypass DRF conventions. --- ## 28.9 `08_DATA_MODEL_AND_MIGRATION_PLAN.md` MUST: * preserve existing models; * distinguish existing vs proposed; * define non-breaking migration strategy. MUST NOT: * rename current models; * generate actual migration code unless explicitly requested later. --- ## 28.10 `09_SMART_VOTE_EKOH_READING_CONTRACT.md` MUST: * separate baseline events from readings; * define lens declarations; * define snapshot context; * define reproducibility. MUST NOT: * make EkoH the vote engine; * make readings source facts. --- ## 28.11 `10_FIRST_PASS_INTEGRATION_MATRIX.md` MUST: * include only approved first-pass sources; * mark deferred sources explicitly; * classify mimic vs annex. MUST NOT: * generate backlog tasks; * promote deferred sources. --- ## 28.12 `11_MIMIC_VS_ANNEX_RULEBOOK.md` MUST: * define mimic; * define annex; * define no-go criteria; * define future annex requirements. MUST NOT: * allow annex in first pass. --- ## 28.13 `12_CANONICAL_OBJECTS_AND_EVENTS.md` MUST: * define domain object vocabulary; * distinguish conceptual objects from current model names. MUST NOT: * force model renames. --- ## 28.14 `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` MUST: * define JSON shapes; * define field names; * define IDs, dates, pagination, errors. MUST NOT: * invent backend endpoints outside `07_API_AND_SERVICE_CONTRACTS.md`. --- ## 28.15 `14_FRONTEND_ALIGNMENT_CONTRACT.md` MUST: * preserve existing shell; * preserve route families; * require service-layer API access; * define Kialo-style frontend surfaces under Deliberate. MUST NOT: * create a second shell; * create a second theme system. --- ## 28.16 `15_BACKEND_ALIGNMENT_CONTRACT.md` MUST: * align with Django/DRF; * preserve app ownership; * define serializer/viewset/router expectations. MUST NOT: * introduce new backend style casually. --- ## 28.17 `16_TEST_AND_SMOKE_CONTRACT.md` MUST: * define minimum tests; * include existing smoke coverage; * include no-drift checks. MUST NOT: * assume unbuilt features are already testable. --- ## 28.18 `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` MUST: * isolate preview drawer bug; * list exclusions; * prevent architecture pollution from bugfix work. MUST NOT: * solve bugs directly. --- ## 28.19 `18_ADR_REGISTER.md` MUST: * list required ADRs; * assign decision status; * include consequences. MUST NOT: * replace detailed contracts. --- ## 28.20 `19_OSS_CODE_READING_PLAN.md` MUST: * define how to inspect OSS repos later; * distinguish product idea from code reality. MUST NOT: * infer code behavior from docs alone. --- ## 28.21 `20_AI_GENERATION_GUARDRAILS.md` MUST: * define all AI constraints; * prevent drift; * govern parallel generation. MUST NOT: * contradict `00_KINTSUGI_START_HERE.md`. --- ## 28.22 `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` MUST: * define Kialo-style mapping in full; * define claim/argument distinction; * define roles, sources, impact votes, visibility settings. MUST NOT: * create a Kialo app; * import Kialo code. --- ## 28.23 `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` MUST: * provide a backlog item format only; * avoid filling real backlog prematurely unless user explicitly asks later. MUST NOT: * generate full implementation plan before contracts are reviewed. --- ## 29. Final AI checklist Before producing any Kintsugi-related output, an AI session MUST check: ```yaml id="t1hb5w" FINAL_AI_CHECKLIST: - "Am I generating only the assigned document or requested output?" - "Am I preserving /ethikos/* route reality?" - "Am I preserving /api/ethikos/* endpoint reality?" - "Am I preserving current Ethikos models?" - "Am I separating EthikosStance, ArgumentImpactVote, and ReadingResult?" - "Am I keeping Smart Vote derived-only?" - "Am I keeping EkoH as context, not voting engine?" - "Am I treating OSS sources as mimic-only in first pass?" - "Am I keeping Kialo-style work inside Korum / Deliberate?" - "Am I avoiding /api/home/* expansion?" - "Am I avoiding implementation tasks unless assigned doc 22?" - "Am I marking uncertainty when code inspection is required?" ``` If any answer is “no,” the AI MUST revise before output. --- ## 30. Related documents This document governs or constrains: ```text id="q9yebx" 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 31. Final binding statement ```yaml id="4kadx4" FINAL_BINDING_STATEMENT: THIS_DOCUMENT_IS: "The AI-specific guardrail contract for the ethiKos Kintsugi documentation and future implementation planning process." ALL_AI_OUTPUTS_MUST: - "Preserve ethiKos route reality." - "Preserve backend ownership boundaries." - "Preserve current model names." - "Treat external civic-tech systems as native-mimic inspirations only in first pass." - "Separate source facts from derived readings." - "Keep Kialo-style features inside Korum under /ethikos/deliberate/*." - "Keep Smart Vote as readings, not source mutation." - "Keep EkoH as context, not vote engine." - "Avoid implementation tasks before documentation contracts." PRIMARY_DRIFT_CONTROL_RULE: "If an AI output conflicts with this file, the canonical variable block, or the source-of-truth hierarchy, the output is invalid unless a later explicit ADR supersedes it." ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c73b8f8fb2524ca9e6c7cd6ac2cbdf3e6e870db7a722fcd5e6ff280d7e8a5cd7 CONTENT_BYTES: 37786 ================================================================================================ # 21 — Kialo-style Argument Mapping Contract **File:** `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` **Pack:** `ethiKos Kintsugi Update Documentation Pack` **Canonical path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/` **Status:** Draft for execution alignment **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Primary module:** `ethiKos` **Route scope:** `/ethikos/deliberate/*` **Backend scope:** `konnaxion.ethikos` --- ## 1. Purpose This document defines the Kialo-style structured argument mapping contract for the ethiKos Kintsugi Upgrade. Kialo-style argument mapping is the canonical first-pass reference for strengthening **Korum**, the structured deliberation side of ethiKos. This contract defines how Kialo-style concepts map into the existing ethiKos architecture without importing Kialo code, creating a Kialo module, or renaming existing ethiKos models. The goal is to turn `/ethikos/deliberate/*` into a stronger structured deliberation workspace using: - thesis-centered discussions; - claim-like argument nodes; - pro/con parent-child relations; - evidence/source attachments; - claim-level impact voting; - suggested claims; - role-aware participation; - author visibility settings; - voting visibility settings; - optional perspectives; - optional minimap/tree navigation; - optional export and template patterns. This document is normative. Future docs, code-reading plans, payload contracts, frontend plans, and model proposals MUST obey it. --- ## 2. Scope This document covers the Kialo-style features that may be mimicked inside ethiKos. It covers: - canonical Kialo-to-ethiKos concept mapping; - route scope; - backend scope; - frontend scope; - first-pass features; - deferred features; - model candidates; - payload candidates; - permissions; - visibility rules; - anonymity rules; - source/evidence rules; - voting distinctions; - anti-drift rules. It does not define: - exact Django migration files; - exact serializer implementation; - exact React component code; - final visual design; - final database indexes; - production permission middleware; - final export implementation; - direct Kialo code import. Those details belong in companion implementation documents. --- ## 3. Canonical Variables Used ```yaml KIALO: STRATEGY: "native_mimic" ROLE_IN_KINTSUGI: "Canonical structured deliberation UX reference for Korum" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false KIALO_CANONICAL_MAPPING: KIALO_DISCUSSION: "EthikosTopic" KIALO_THESIS: "Topic thesis/prompt field; current fallback is EthikosTopic.title + description" KIALO_CLAIM: "EthikosArgument" KIALO_PRO_CON_EDGE: "EthikosArgument.parent + EthikosArgument.side" KIALO_SOURCE: "ArgumentSource" KIALO_IMPACT_VOTE: "ArgumentImpactVote" KIALO_SUGGESTED_CLAIM: "ArgumentSuggestion" KIALO_PERSPECTIVE: "DiscussionPerspective / Smart Vote lens depending context" KIALO_PARTICIPANT_ROLE: "DiscussionParticipantRole" KIALO_VALUES: KIALO_EDGE_SIDE_VALUES: - "pro" - "con" - "neutral" KIALO_IMPACT_VOTE_RANGE: "0..4" KIALO_IMPACT_VOTE_MEANING: "veracity + relevance to parent" KIALO_ROLES: - "owner" - "admin" - "editor" - "writer" - "suggester" - "viewer" KIALO_ANONYMITY_MODES: - "standard" - "anonymous" KIALO_AUTHOR_VISIBILITY: - "never" - "admins_only" - "all" KIALO_VOTE_VISIBILITY: - "all" - "admins_only" - "self_only" KIALO_DISCUSSION_TOPOLOGY: - "single_thesis" - "multi_thesis" KIALO_MINIMAP_MODES: - "tree" - "sunburst" CRITICAL_VOTE_RULES: CLAIM_IMPACT_VOTE_IS_TOPIC_STANCE: false CLAIM_IMPACT_VOTE_IS_SMART_VOTE_BALLOT: false ETHIKOS_STANCE_IS_READING: false SMART_VOTE_READING_IS_SOURCE_FACT: false ```` --- ## 4. Strategic Position Kialo-style argument mapping is not a new product module. It is a structured deliberation pattern to be mimicked inside ethiKos. The target is: ```txt /ethikos/deliberate/* ``` The owner is: ```txt Korum ``` The backend app remains: ```txt konnaxion.ethikos ``` The existing canonical models remain: ```txt EthikosTopic EthikosStance EthikosArgument EthikosCategory ``` The Kialo-style upgrade extends this foundation. It does not replace it. --- ## 5. Core Rule The core rule is: ```txt Kialo-style claims are UX/domain concepts. EthikosArgument remains the backend model. ``` The implementation MUST NOT rename `EthikosArgument` to `Claim`. The implementation MAY use the term “claim” in: * UI labels; * user-facing explanations; * documentation; * payload aliases; * frontend component names. But the backend source of truth remains: ```txt EthikosArgument ``` --- ## 6. Current ethiKos Reality The current ethiKos backend is centered on: ```txt EthikosCategory EthikosTopic EthikosStance EthikosArgument ``` The current canonical API endpoints are: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` Compatibility aliases may exist under: ```txt /api/deliberate/... /api/deliberate/elite/... ``` The current implemented frontend route surface includes: ```txt /ethikos/deliberate/elite /ethikos/deliberate/[topic] /ethikos/deliberate/guidelines ``` The Kialo-style contract MUST build on this existing reality. --- ## 7. Kialo-style Concepts Retained The following Kialo-style concepts are retained as first-class design references. | Kialo-style concept | Meaning for ethiKos | | -------------------- | -------------------------------------------------- | | Discussion | Topic-level deliberation container | | Thesis | Prompt, proposition, or central question | | Claim | Argument node | | Pro/Con relation | Parent-child argument relation with side | | Source | Evidence attached to an argument | | Impact vote | Claim-level impact score, separate from stance | | Suggested claim | Proposed argument requiring review or acceptance | | Participant role | Per-topic permission level | | Anonymous discussion | Participation mode with identity visibility limits | | Author visibility | Whether claim authors are visible | | Vote visibility | Whether claim impact votes are visible | | Background info | Admin-controlled context block | | Discussion topology | Single-thesis or multi-thesis structure | | Minimap | Navigation aid for large argument trees | | Perspective | Artificial or lens-based viewpoint over claims | | Template | Reusable discussion structure | | Small group mode | Branching discussion per cohort/group | | Export | Downloadable discussion or source output | --- ## 8. Canonical Concept Mapping ## 8.1 Discussion ```txt Kialo Discussion → EthikosTopic ``` An `EthikosTopic` is the canonical ethiKos container for a structured deliberation. A topic may represent: * a single-thesis discussion; * a multi-thesis discussion; * a consultation prompt; * a policy question; * a proposal debate. First-pass implementation SHOULD treat existing `EthikosTopic.title` and `EthikosTopic.description` as the fallback thesis/prompt source. Future implementation MAY add explicit fields such as: ```txt thesis discussion_topology background_info ``` Only non-breaking additions are allowed. --- ## 8.2 Thesis ```txt Kialo Thesis → Topic thesis / prompt / title + description ``` A thesis is the main claim, proposition, or question being debated. Single-thesis topology: ```txt One central thesis → pro/con argument tree ``` Multi-thesis topology: ```txt One central question → multiple possible thesis answers → each thesis has pro/con branches ``` First pass SHOULD support single-thesis behavior first. Multi-thesis behavior MAY be represented later through topic options, child thesis objects, or a non-breaking topology extension. --- ## 8.3 Claim ```txt Kialo Claim → EthikosArgument ``` A claim is a structured argument node. In ethiKos first pass, the claim maps to the existing `EthikosArgument`. A claim-like argument SHOULD have: ```txt id topic parent side content author created_at updated_at is_hidden ``` Future non-breaking extensions MAY include: ```txt summary claim_type source_count impact_score depth path is_suggested accepted_from_suggestion ``` --- ## 8.4 Pro/Con Edge ```txt Kialo Pro/Con edge → EthikosArgument.parent + EthikosArgument.side ``` The argument graph is represented as a parent-child structure. Allowed side values: ```txt pro con neutral ``` Rules: * A root argument MAY have no parent. * A child argument SHOULD indicate whether it supports or opposes its parent. * `neutral` MAY be used for clarifications, context notes, or unresolved mapping. * Cycles MUST NOT be allowed. * Moving arguments MUST preserve audit history. --- ## 8.5 Source ```txt Kialo Source → ArgumentSource ``` A source is evidence attached to an argument. A source SHOULD be treated as a distinct object, not embedded only in the argument body. First-pass `ArgumentSource` SHOULD support: ```txt id argument url citation_text quote note created_by created_at updated_at is_removed ``` A discussion-level source view SHOULD be possible. A source MAY be linked to multiple argument nodes only if `ArgumentSource` or future `ArgumentSourceLink` supports that explicitly. --- ## 8.6 Impact Vote ```txt Kialo Impact Vote → ArgumentImpactVote ``` An impact vote is a claim-level evaluation. It is not a topic stance. It is not a Smart Vote ballot. It is not a consultation vote. First-pass range: ```txt 0..4 ``` Meaning: ```txt Claim impact = perceived relevance + strength/veracity relative to its parent. ``` The exact UI labels MAY be refined later, but the storage contract MUST remain separate from `EthikosStance`. --- ## 8.7 Suggested Claim ```txt Kialo Suggested Claim → ArgumentSuggestion ``` A suggested claim is a proposed argument that is not yet part of the canonical argument tree. Suggested claims are useful for: * low-trust participation; * classroom/moderated contexts; * public proposal intake; * reducing vandalism; * allowing “suggester” role participation. An `ArgumentSuggestion` SHOULD become an `EthikosArgument` only after acceptance. Rejected suggestions SHOULD remain auditable. --- ## 8.8 Perspective ```txt Kialo Perspective → DiscussionPerspective or Smart Vote lens, depending context ``` A perspective can mean two different things. | Context | Meaning | | --------------- | ----------------------------------------- | | Deliberation UX | Artificial or saved viewpoint over claims | | Smart Vote | Declared lens for derived readings | This distinction MUST be preserved. First pass MAY defer custom perspectives unless the data model is already stable. A perspective MUST NOT mutate source arguments. --- ## 8.9 Participant Role ```txt Kialo Participant Role → DiscussionParticipantRole ``` Participant roles define what a user may do inside a topic-level deliberation. Allowed roles: ```txt owner admin editor writer suggester viewer ``` Roles are discussion/topic-specific. They do not replace global user roles. --- ## 9. First-Pass Features The following Kialo-style features are first-pass candidates. ## 9.1 Argument Tree Status: ```txt first_pass_candidate ``` Target route: ```txt /ethikos/deliberate/[topic] ``` Required behavior: * render arguments as a tree; * preserve parent-child relations; * show `pro`, `con`, or `neutral` side; * allow expanding/collapsing branches; * distinguish hidden/moderated arguments; * preserve current argument posting behavior. Data impact: ```txt No breaking change required if EthikosArgument.parent + side already exist. ``` --- ## 9.2 Source Attachments Status: ```txt first_pass_candidate ``` Target route: ```txt /ethikos/deliberate/[topic] ``` Required behavior: * attach source URL or citation to an argument; * optionally store quote/note; * show sources on argument detail; * support discussion-level source list; * support moderation/removal of sources. Data impact: ```txt New table candidate: ArgumentSource ``` --- ## 9.3 Argument Impact Vote Status: ```txt first_pass_candidate ``` Target route: ```txt /ethikos/deliberate/[topic] ``` Required behavior: * let eligible users rate impact of an argument/claim; * store impact votes separately from topic stances; * aggregate impact by argument; * never count impact vote as topic stance; * never count impact vote as Smart Vote ballot. Data impact: ```txt New table candidate: ArgumentImpactVote ``` --- ## 9.4 Suggested Claims Status: ```txt first_pass_candidate ``` Target routes: ```txt /ethikos/deliberate/[topic] /ethikos/admin/moderation ``` Required behavior: * allow users with `suggester` role to submit suggested claims; * route suggestions to moderation/approval queue; * allow admin/editor to accept, reject, or request revision; * accepted suggestions become canonical `EthikosArgument` records; * rejected suggestions remain auditable. Data impact: ```txt New table candidate: ArgumentSuggestion ``` --- ## 9.5 Participant Roles Status: ```txt first_pass_candidate ``` Target routes: ```txt /ethikos/deliberate/[topic] /ethikos/admin/roles ``` Required behavior: * support topic-specific roles; * roles must not replace global auth; * admin UI may manage participants; * role decisions should be auditable. Data impact: ```txt New table candidate: DiscussionParticipantRole ``` --- ## 9.6 Visibility Settings Status: ```txt first_pass_candidate ``` Target routes: ```txt /ethikos/deliberate/[topic] /ethikos/admin/roles ``` Required behavior: * configure author visibility; * configure impact vote visibility; * configure participation mode; * preserve privacy rules. Data impact: ```txt New table candidate: DiscussionVisibilitySetting ``` --- ## 9.7 Background Info Status: ```txt first_pass_candidate ``` Target route: ```txt /ethikos/deliberate/[topic] ``` Required behavior: * show topic context separate from argument nodes; * allow admin/moderator editing; * do not mix background info into the argument tree; * preserve prompt/context as orientation material. Data impact: ```txt Possible non-breaking field on EthikosTopic or separate TopicContext object. ``` --- ## 10. Deferred Features The following Kialo-style features are deferred unless later approved. | Feature | Status | Reason | | ------------------------------ | ----------------- | -------------------------------------------------- | | Sunburst minimap | Deferred | Nice UX, not required for first-pass correctness | | Small group mode | Deferred | Requires cohort/group branching | | Clone-from-template | Optional/deferred | Useful, but depends on stable templates | | Discussion export | Optional/deferred | Useful after sources and graph contracts stabilize | | Custom perspectives | Deferred | Must avoid confusion with Smart Vote lenses | | Claim extraction | Deferred | Requires cross-topic graph operations | | Cross-discussion claim linking | Deferred | Requires careful provenance and cycle rules | | Contact lists | Deferred | Belongs to broader participant management | | Instant access discussions | Deferred | Requires access-policy review | | Discussion chat | Deferred | Separate from argument graph | | Branch-seen tracking | Deferred | Useful for UX, not first-pass architecture | | Notifications | Deferred | Requires event/notification contract | --- ## 11. Explicitly Forbidden First-Pass Behaviors The following are forbidden: ```txt Create konnaxion.kialo. Create /kialo routes. Import Kialo code. Rename EthikosArgument to Claim. Replace EthikosStance with ArgumentImpactVote. Treat ArgumentImpactVote as Smart Vote ballot. Treat Kialo perspectives as Smart Vote readings by default. Expose anonymous identities to normal participants. Allow suggested claims to publish without approval when role = suggester. Allow external Kialo data to write directly into EthikosArgument. Create a second deliberation shell. Bypass /api/ethikos/* contracts. ``` --- ## 12. Role and Permission Contract ## 12.1 Role Hierarchy Allowed roles: ```txt viewer suggester writer editor admin owner ``` Higher roles inherit lower-role capabilities unless explicitly restricted. ## 12.2 Capabilities Matrix | Capability | Viewer | Suggester | Writer | Editor | Admin | Owner | | ------------------------------- | -----: | --------: | -----: | -----: | ----: | ----: | | View discussion | yes | yes | yes | yes | yes | yes | | View visible sources | yes | yes | yes | yes | yes | yes | | Submit suggested claim | no | yes | yes | yes | yes | yes | | Create canonical claim/argument | no | no | yes | yes | yes | yes | | Edit own claim | no | no | yes | yes | yes | yes | | Edit others’ claims | no | no | no | yes | yes | yes | | Attach source to own claim | no | no | yes | yes | yes | yes | | Edit/remove others’ sources | no | no | no | yes | yes | yes | | Accept/reject suggestions | no | no | no | yes | yes | yes | | Hide/moderate claims | no | no | no | no | yes | yes | | Manage roles | no | no | no | no | yes | yes | | Transfer ownership | no | no | no | no | no | yes | | Change visibility settings | no | no | no | no | yes | yes | | Delete/archive discussion | no | no | no | no | no | yes | This matrix is the documentation default. Final implementation MAY adjust details in `15_BACKEND_ALIGNMENT_CONTRACT.md`, but must preserve the overall hierarchy. --- ## 13. Visibility Contract ## 13.1 Author Visibility Allowed values: ```txt never admins_only all ``` Meaning: | Value | Meaning | | ------------- | -------------------------------------------------------------------------- | | `never` | Claim authors are hidden from all participants except system/audit context | | `admins_only` | Claim authors are visible only to admin/owner roles | | `all` | Claim authors are visible to all participants | Audit logs MUST retain real authorship even when UI hides authors. ## 13.2 Vote Visibility Allowed values: ```txt all admins_only self_only ``` Meaning: | Value | Meaning | | ------------- | ----------------------------------------------------------------------------- | | `all` | Aggregated and/or individual impact votes may be shown according to UI policy | | `admins_only` | Impact vote details are visible only to admin/owner roles | | `self_only` | A user sees only their own impact vote; aggregate may be hidden | Vote visibility applies to `ArgumentImpactVote`, not `EthikosStance`. ## 13.3 Participation Mode Allowed values: ```txt standard anonymous ``` Meaning: | Value | Meaning | | ----------- | --------------------------------------------------------------------- | | `standard` | Normal author display rules apply | | `anonymous` | Author identity is hidden according to discussion visibility settings | Anonymous participation MUST NOT erase audit identity. --- ## 14. Voting Contract The Kialo-style impact vote is distinct from all other ethiKos voting concepts. ## 14.1 EthikosStance ```yaml MODEL: "EthikosStance" RANGE: "-3..+3" LEVEL: "topic-level" OWNER: "Korum" MEANING: "User stance on topic." ``` ## 14.2 ArgumentImpactVote ```yaml MODEL: "ArgumentImpactVote" RANGE: "0..4" LEVEL: "argument/claim-level" OWNER: "Korum" MEANING: "Impact of a claim on its parent; combines relevance and strength/veracity." ``` ## 14.3 Smart Vote Reading ```yaml MODEL: "ReadingResult" RANGE: "not fixed" LEVEL: "derived aggregation" OWNER: "Smart Vote" MEANING: "Declared reading of baseline events." ``` ## 14.4 Forbidden Conflations ```txt ArgumentImpactVote MUST NOT be stored as EthikosStance. ArgumentImpactVote MUST NOT be posted to /api/kollective/votes/. ArgumentImpactVote MUST NOT determine baseline topic outcome. Smart Vote MUST NOT treat impact votes as ballots unless a future explicit lens says so. EthikosStance MUST NOT be displayed as claim impact. ``` --- ## 15. Discussion Topology Contract Supported topology values: ```txt single_thesis multi_thesis ``` ## 15.1 Single Thesis Single-thesis discussions have one central proposition. Structure: ```txt EthikosTopic └── Thesis / prompt ├── pro argument branch └── con argument branch ``` First pass SHOULD target this topology. ## 15.2 Multi Thesis Multi-thesis discussions have one central question and multiple possible thesis answers. Structure: ```txt EthikosTopic └── central question ├── thesis option A │ ├── pro branch │ └── con branch ├── thesis option B │ ├── pro branch │ └── con branch └── thesis option C ├── pro branch └── con branch ``` Multi-thesis support is deferred unless the data model explicitly supports it. --- ## 16. Source and Evidence Contract Sources are first-class evidence objects. A source MUST be attached to an argument, not only pasted into text. ## 16.1 `ArgumentSource` Recommended fields: ```yaml ArgumentSource: id: integer argument: FK(EthikosArgument) url: string | null citation_text: text | null quote: text | null note: text | null created_by: FK(User) created_at: datetime updated_at: datetime is_removed: boolean removed_by: FK(User) | null removed_at: datetime | null ``` ## 16.2 Source Rules * Sources SHOULD be editable separately from argument text. * Sources SHOULD be visible on the argument node or detail panel. * A discussion-level source list SHOULD be available. * Source removal SHOULD be soft-delete or audit-preserving. * Sources SHOULD be exportable later. * Source quality scoring is not first pass unless separately approved. --- ## 17. Suggested Claim Contract Suggested claims are proposed argument nodes pending review. ## 17.1 `ArgumentSuggestion` Recommended fields: ```yaml ArgumentSuggestion: id: integer topic: FK(EthikosTopic) parent: FK(EthikosArgument) | null side: "pro | con | neutral" content: text source_payload: json | null suggested_by: FK(User) status: "pending | accepted | rejected | revision_requested" reviewed_by: FK(User) | null reviewed_at: datetime | null accepted_argument: FK(EthikosArgument) | null created_at: datetime updated_at: datetime ``` ## 17.2 Suggestion Rules * `suggester` role may submit suggestions. * Suggestions are not canonical arguments until accepted. * Accepted suggestions MUST create or link to an `EthikosArgument`. * Rejected suggestions MUST remain auditable. * Revision requests SHOULD preserve prior content. --- ## 18. Participant Role Contract ## 18.1 `DiscussionParticipantRole` Recommended fields: ```yaml DiscussionParticipantRole: id: integer topic: FK(EthikosTopic) user: FK(User) role: "owner | admin | editor | writer | suggester | viewer" assigned_by: FK(User) | null assigned_at: datetime revoked_at: datetime | null is_active: boolean ``` ## 18.2 Role Rules * Roles are scoped to a topic/discussion. * Global staff status MAY override local permissions for administrative safety. * Role changes MUST be auditable. * There SHOULD be exactly one owner unless ownership transfer rules define otherwise. * Users without explicit role MAY receive default role based on topic visibility. --- ## 19. Discussion Visibility Contract ## 19.1 `DiscussionVisibilitySetting` Recommended fields: ```yaml DiscussionVisibilitySetting: id: integer topic: FK(EthikosTopic) participation_type: "standard | anonymous" author_visibility: "never | admins_only | all" vote_visibility: "all | admins_only | self_only" topology: "single_thesis | multi_thesis" link_sharing_enabled: boolean invite_required: boolean created_at: datetime updated_at: datetime ``` ## 19.2 Visibility Rules * Anonymous mode changes UI visibility, not audit identity. * Author visibility and vote visibility are separate settings. * Link sharing is not equivalent to public visibility. * Invite-required discussions need explicit participant onboarding. * Visibility changes SHOULD be recorded in audit logs. --- ## 20. Frontend Contract Kialo-style UI lives under: ```txt /ethikos/deliberate/* ``` It MUST use the existing ethiKos shell and page conventions. Required or candidate components: ```txt ArgumentTreeView ArgumentNodeCard ArgumentNodeDetailPanel ArgumentSourcesPanel ArgumentImpactVoteControl SuggestedClaimsPanel DiscussionSettingsPanel ParticipantRoleSettings AnonymousModeBanner BackgroundInfoPanel ``` Optional/deferred components: ```txt ArgumentMinimap SunburstMap GuidedVotingDrawer PerspectiveSelector DiscussionExportPanel TemplateCloneDialog SmallGroupModePanel ``` Frontend rules: * Do not create a Kialo module. * Do not create a Kialo route family. * Do not create a second shell. * Do not bypass `EthikosPageShell`. * Do not bypass the services layer. * Do not treat UI “claim” labels as backend model names. --- ## 21. Backend Contract Kialo-style features extend: ```txt konnaxion.ethikos ``` They do not create: ```txt konnaxion.kialo ``` Current core endpoints remain canonical: ```txt /api/ethikos/topics/ /api/ethikos/stances/ /api/ethikos/arguments/ /api/ethikos/categories/ ``` New endpoints MAY be added under the same prefix, such as: ```txt /api/ethikos/argument-sources/ /api/ethikos/argument-impact-votes/ /api/ethikos/argument-suggestions/ /api/ethikos/discussion-roles/ /api/ethikos/discussion-settings/ ``` Exact endpoint names MUST be finalized in `07_API_AND_SERVICE_CONTRACTS.md`. Backend rules: * Use Django REST Framework. * Use serializers and ViewSets. * Register with the existing router pattern. * Preserve `AUTH_USER_MODEL = "users.User"`. * Preserve current models. * Add non-breaking models only. * Add migrations explicitly. * Add tests for all new write paths. --- ## 22. Payload Contract Exact payloads are defined in `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md`. This document reserves the following payload names. ```txt ArgumentTreePayload ArgumentNodePayload ArgumentSourcePayload ArgumentImpactVotePayload ArgumentSuggestionPayload DiscussionSettingsPayload ParticipantRolePayload BackgroundInfoPayload ``` ## 22.1 `ArgumentNodePayload` Candidate shape: ```yaml ArgumentNodePayload: id: string topic_id: string parent_id: string | null side: "pro | con | neutral" content: string author_display: string | null author_visibility: "never | admins_only | all" created_at: string updated_at: string depth: integer children_count: integer source_count: integer impact_summary: average: number | null count: integer viewer_vote: integer | null moderation: is_hidden: boolean hidden_reason: string | null ``` ## 22.2 `ArgumentSourcePayload` Candidate shape: ```yaml ArgumentSourcePayload: id: string argument_id: string url: string | null citation_text: string | null quote: string | null note: string | null created_by_display: string | null created_at: string is_removed: boolean ``` ## 22.3 `ArgumentImpactVotePayload` Candidate shape: ```yaml ArgumentImpactVotePayload: id: string argument_id: string value: integer value_range: "0..4" created_at: string updated_at: string ``` ## 22.4 `ArgumentSuggestionPayload` Candidate shape: ```yaml ArgumentSuggestionPayload: id: string topic_id: string parent_id: string | null side: "pro | con | neutral" content: string suggested_by_display: string | null status: "pending | accepted | rejected | revision_requested" reviewed_by_display: string | null reviewed_at: string | null accepted_argument_id: string | null created_at: string ``` --- ## 23. Admin and Moderation Contract Kialo-style moderation belongs to: ```txt /ethikos/admin/moderation /ethikos/admin/audit /ethikos/admin/roles ``` Admin surfaces SHOULD support: * reviewing suggested claims; * hiding/unhiding arguments; * editing/removing improper sources; * assigning participant roles; * changing visibility settings; * reviewing audit trails; * detecting abuse in anonymous mode. Moderation actions MUST be auditable. Anonymous mode MUST NOT prevent admin investigation. --- ## 24. Audit Contract The following events SHOULD be recorded when implemented: ```txt ArgumentSourceAttached ArgumentSourceEdited ArgumentSourceRemoved ArgumentImpactVoteRecorded ArgumentSuggestionSubmitted ArgumentSuggestionAccepted ArgumentSuggestionRejected ArgumentSuggestionRevisionRequested DiscussionRoleAssigned DiscussionRoleRevoked DiscussionVisibilityChanged DiscussionBackgroundInfoChanged ArgumentMoved ArgumentHidden ArgumentUnhidden ``` Audit events SHOULD include: ```yaml AuditEvent: actor: User | service action: string target_type: string target_id: string topic_id: string before: json | null after: json | null created_at: datetime ``` --- ## 25. Relationship to Smart Vote and EkoH Kialo-style features live primarily in Korum. They may later inform Smart Vote readings, but they do not replace Smart Vote. Rules: ```txt ArgumentImpactVote is not a Smart Vote ballot. ArgumentSource is not an EkoH credential. DiscussionPerspective is not automatically a Smart Vote lens. Author visibility is not EkoH trust. Participant role is not global user permission. ``` Possible future Smart Vote integrations: * argument-quality lens; * evidence-density lens; * expert-perspective lens; * deliberation-depth lens; * source-supported-claim lens. These are future derived readings and MUST be declared as lenses before use. --- ## 26. Relationship to Korum Kialo-style argument mapping is the main UX and data-pattern reference for Korum. Korum owns: ```txt EthikosTopic EthikosStance EthikosArgument ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` Korum does not own: ```txt Smart Vote readings EkoH snapshots Konsultations ballots Impact tracking Draft final publication ``` --- ## 27. Relationship to Konsultations Kialo-style deliberation may support Konsultations by clarifying arguments before decision. However: * consultation ballots are not claim impact votes; * result snapshots are not argument trees; * impact tracking is not Kialo-style deliberation; * citizen suggestions for consultation may be related to `ArgumentSuggestion`, but they are not automatically the same object. If Konsultations uses Kialo-style suggestions, the relationship MUST be explicitly modeled. --- ## 28. Non-Goals This contract does not authorize: * importing Kialo code; * cloning Kialo UI exactly; * creating a Kialo backend app; * creating `/kialo/*`; * replacing `EthikosArgument`; * replacing `EthikosStance`; * making claim impact votes determine final decisions; * implementing small group mode immediately; * implementing custom perspectives immediately; * implementing discussion export immediately; * implementing sunburst minimap immediately; * implementing cross-discussion claim linking immediately; * implementing Kialo-specific auth; * implementing Kialo-specific contact lists; * bypassing ethiKos moderation and audit. --- ## 29. First-Pass Acceptance Criteria The Kialo-style first pass is successful when: 1. `/ethikos/deliberate/[topic]` can represent arguments as a structured tree. 2. Parent-child pro/con relations are visible. 3. Existing `EthikosArgument` remains the canonical backend model. 4. Topic-level stance remains `EthikosStance` with range `-3..+3`. 5. Claim-level impact vote is modeled separately with range `0..4`. 6. Sources can be attached to arguments as separate evidence objects. 7. Suggested claims can be submitted without becoming canonical immediately. 8. Participant roles are topic-specific. 9. Author visibility and vote visibility are explicit. 10. Anonymous mode hides UI identity but preserves audit identity. 11. No Kialo code is imported. 12. No new Kialo route or backend app is created. --- ## 30. Anti-Drift Rules These rules are binding. ```txt Do not rename EthikosArgument to Claim. Do not create konnaxion.kialo. Do not create /kialo routes. Do not import Kialo code. Do not treat Kialo impact votes as topic stances. Do not treat Kialo impact votes as Smart Vote ballots. Do not treat Kialo perspectives as Smart Vote readings unless explicitly declared as lenses. Do not expose anonymous identities to normal participants. Do not publish suggested claims without approval when role = suggester. Do not store sources only as inline text. Do not bypass /api/ethikos/*. Do not create a second deliberation shell. Do not make Kialo the product name of the feature. ``` --- ## 31. Related Docs | File | Relationship | | ----------------------------------------------- | ----------------------------------------------------- | | `00_KINTSUGI_START_HERE.md` | Pack entry point and baseline | | `01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md` | Strategy that defines Kialo-style as first-pass mimic | | `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` | Source priority and conflict resolution | | `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` | Korum/Konsultations/Smart Vote/EkoH boundaries | | `04_CANONICAL_NAMING_AND_VARIABLES.md` | Fixed naming and variables | | `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` | Route-level placement under `/ethikos/deliberate/*` | | `07_API_AND_SERVICE_CONTRACTS.md` | Endpoint and service contracts | | `08_DATA_MODEL_AND_MIGRATION_PLAN.md` | New model candidates and migrations | | `09_SMART_VOTE_EKOH_READING_CONTRACT.md` | Prevents vote/reading confusion | | `10_FIRST_PASS_INTEGRATION_MATRIX.md` | Places Kialo-style in first-pass mimic scope | | `11_MIMIC_VS_ANNEX_RULEBOOK.md` | Confirms native mimic strategy | | `12_CANONICAL_OBJECTS_AND_EVENTS.md` | Canonical objects/events for argument mapping | | `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` | Final JSON shape definitions | | `14_FRONTEND_ALIGNMENT_CONTRACT.md` | Frontend shell/component rules | | `15_BACKEND_ALIGNMENT_CONTRACT.md` | Django/DRF backend rules | | `16_TEST_AND_SMOKE_CONTRACT.md` | Test expectations | | `18_ADR_REGISTER.md` | Records no separate Kialo module decision | | `20_AI_GENERATION_GUARDRAILS.md` | AI anti-drift rules | | `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` | Future task format | --- ## 32. Final Contract The final Kialo-style contract is: ```txt Use Kialo as the structured deliberation reference. Mimic the pattern natively. Keep everything under /ethikos/deliberate/*. Keep backend ownership inside konnaxion.ethikos. Map Discussion to EthikosTopic. Map Claim to EthikosArgument. Map Pro/Con relation to parent + side. Add sources, impact votes, suggestions, roles, and visibility as non-breaking extensions. Never confuse claim impact with topic stance. Never create a Kialo module. Never import Kialo code. ``` Source basis: the Kialo core corpus for discussion topology, roles, sources, voting, anonymity, perspectives, navigation, and participant management; plus the current ethiKos route/API/model reality in the Konnaxion technical references and snapshot. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1} :contentReference[oaicite:2]{index=2} :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4} :contentReference[oaicite:5]{index=5} ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/22_IMPLEMENTATION_BACKLOG_TEMPLATE.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 77491d44f9b1a9b91b952c39c7abd9d3961cfed8d2e28b1e803947f2126d0208 CONTENT_BYTES: 43991 ================================================================================================ # 22 — Implementation Backlog Template **Project:** Konnaxion **Module:** ethiKos **Upgrade:** Kintsugi **Document ID:** `22_IMPLEMENTATION_BACKLOG_TEMPLATE.md` **Status:** Backlog generation template **Version:** `2026-04-25-kintsugi-doc-pack-v1` **Audience:** Human maintainers, implementation planners, AI coding agents, project managers, backend/frontend developers **Purpose:** Define the only approved format for converting the Kintsugi documentation pack into implementation tasks after documentation contracts and code-reading are complete. --- ## 1. Purpose This document defines the canonical implementation backlog format for the ethiKos Kintsugi upgrade. It exists to prevent premature, speculative, or drifted implementation work. The backlog must only be generated after: 1. the Kintsugi documentation pack is stable; 2. source-of-truth rules are accepted; 3. ownership boundaries are accepted; 4. canonical variables are accepted; 5. route-by-route upgrade mapping is accepted; 6. API/service contracts are accepted; 7. data/model/migration contracts are accepted; 8. Kialo-style argument mapping contract is accepted; 9. code snapshot inspection is complete; 10. first-pass OSS code reading is complete or explicitly waived. This document does **not** contain the actual implementation backlog. It defines the template that the real backlog must follow. --- ## 2. Scope This template governs backlog items for: - backend models; - backend migrations; - serializers; - DRF ViewSets; - API router registrations; - frontend services; - frontend route upgrades; - UI components; - Smart Vote readings; - EkoH snapshot/context references; - Kialo-style argument mapping; - Konsultations intake/ballots/impact; - tests; - smoke checks; - documentation updates; - migration verification; - rollback planning; - QA sequencing. This template does not authorize: - full external OSS merge; - annex/sidecar implementation in first pass; - new route families outside `/ethikos/*`; - new backend apps for Kialo, Loomio, Decidim, CONSUL, DemocracyOS, or Consider.it; - destructive changes to existing Ethikos core models; - premature implementation before contracts are stable. --- ## 3. Canonical Variables Used ```yaml id="u8hqqq" PROJECT: PLATFORM_NAME: "Konnaxion" MODULE_NAME: "ethiKos" UPDATE_NAME: "Kintsugi" BACKLOG_POLICY: THIS_FILE_IS_TEMPLATE_ONLY: true GENERATE_REAL_BACKLOG_ONLY_AFTER_DOCS_AND_CODE_READING: true BACKLOG_ITEMS_MUST_TRACE_TO_SOURCE_DOCS: true BACKLOG_ITEMS_MUST_DECLARE_ROUTE_ENDPOINT_MODEL_TESTS: true BACKLOG_ITEMS_MUST_INCLUDE_ROLLBACK_NOTES: true BACKLOG_ITEMS_MUST_PASS_DRIFT_CHECK: true IMPLEMENTATION_STYLE: MODE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_CORE_MODELS_STABLE: true PRIMARY_ROUTE_SURFACE: ETHIKOS: "/ethikos/*" DELIBERATE: "/ethikos/deliberate/*" DECIDE: "/ethikos/decide/*" IMPACT: "/ethikos/impact/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" CURRENT_ETHIKOS_CORE_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_CANONICAL_ENDPOINTS: - "/api/ethikos/topics/" - "/api/ethikos/stances/" - "/api/ethikos/arguments/" - "/api/ethikos/categories/" - "/api/kollective/votes/" OWNERSHIP: KORUM: "topics, arguments, argument graph, topic-level stances, debate moderation" KONSULTATIONS: "intake, consultations, ballots, result snapshots, impact tracking" SMART_VOTE: "readings, lens declarations, derived aggregations, result publication" EKOH: "expertise context, ethics context, cohort eligibility, snapshot context" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false READINGS_ARE_DERIVED: true ```` --- ## 4. Backlog Readiness Gate The real implementation backlog MUST NOT be generated until every readiness item is checked. ```markdown id="r7s2xb" ## Backlog Readiness Checklist - [ ] `00_KINTSUGI_START_HERE.md` is accepted. - [ ] `02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md` is accepted. - [ ] `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md` is accepted. - [ ] `04_CANONICAL_NAMING_AND_VARIABLES.md` is accepted. - [ ] `05_CURRENT_STATE_BASELINE.md` is accepted. - [ ] `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md` is accepted. - [ ] `07_API_AND_SERVICE_CONTRACTS.md` is accepted. - [ ] `08_DATA_MODEL_AND_MIGRATION_PLAN.md` is accepted. - [ ] `09_SMART_VOTE_EKOH_READING_CONTRACT.md` is accepted. - [ ] `10_FIRST_PASS_INTEGRATION_MATRIX.md` is accepted. - [ ] `11_MIMIC_VS_ANNEX_RULEBOOK.md` is accepted. - [ ] `12_CANONICAL_OBJECTS_AND_EVENTS.md` is accepted. - [ ] `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md` is accepted. - [ ] `14_FRONTEND_ALIGNMENT_CONTRACT.md` is accepted. - [ ] `15_BACKEND_ALIGNMENT_CONTRACT.md` is accepted. - [ ] `16_TEST_AND_SMOKE_CONTRACT.md` is accepted. - [ ] `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md` is accepted. - [ ] `18_ADR_REGISTER.md` is accepted. - [ ] `19_OSS_CODE_READING_PLAN.md` is accepted or explicitly waived. - [ ] `20_AI_GENERATION_GUARDRAILS.md` is accepted. - [ ] `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md` is accepted. - [ ] Current code snapshot has been inspected. - [ ] Existing frontend route reality has been confirmed. - [ ] Existing backend model/API reality has been confirmed. - [ ] First-pass OSS patterns have been classified as mimic-only. ``` If any item is unchecked, the backlog may only be drafted as a **candidate backlog**, not as an implementation-ready backlog. --- ## 5. Backlog Generation Rule All backlog items MUST be generated from accepted documentation. No task may exist without at least one source document reference. ```yaml id="wxs8ew" BACKLOG_ITEM_REQUIRES: source_doc: true source_section: true owner_domain: true route_scope: true backend_scope: true frontend_scope: true test_scope: true risk_level: true rollback_note: true drift_check: true ``` Forbidden backlog origins: ```txt id="ef3qwl" "AI intuition" "nice-to-have feature" "OSS repo has this so Ethikos should have it" "route invented during implementation" "model invented during implementation" "endpoint invented during implementation" "UI redesign unrelated to Kintsugi" ``` Valid backlog origins: ```txt id="utbl5i" "Derived from 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md" "Required by 08_DATA_MODEL_AND_MIGRATION_PLAN.md" "Required by 09_SMART_VOTE_EKOH_READING_CONTRACT.md" "Required by 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md" "Required by current code snapshot mismatch" "Required by known bug registry" ``` --- ## 6. Backlog ID Convention Every backlog item MUST use a stable ID. ```txt id="c4cqrx" KIN-EPIC-### KIN-BE-### KIN-FE-### KIN-API-### KIN-DATA-### KIN-MIG-### KIN-TEST-### KIN-DOC-### KIN-QA-### KIN-BUG-### KIN-ADR-### ``` ### 6.1 Prefix Meanings | Prefix | Meaning | | ---------- | --------------------------------------------------------------------------- | | `KIN-EPIC` | Larger workstream grouping several tasks. | | `KIN-BE` | Backend model, serializer, service, permission, or viewset task. | | `KIN-FE` | Frontend route, component, service, state, or UI task. | | `KIN-API` | API endpoint contract, router registration, payload, or compatibility task. | | `KIN-DATA` | Data model design or data-shape task. | | `KIN-MIG` | Migration task. | | `KIN-TEST` | Unit, integration, API, frontend, or smoke test task. | | `KIN-DOC` | Documentation patch task. | | `KIN-QA` | Verification, manual QA, regression, or release-readiness task. | | `KIN-BUG` | Targeted bugfix task. | | `KIN-ADR` | Architecture decision record task. | ### 6.2 ID Examples ```txt id="q3fhhn" KIN-EPIC-001 KIN-BE-001 KIN-FE-001 KIN-API-001 KIN-DATA-001 KIN-MIG-001 KIN-TEST-001 KIN-DOC-001 KIN-QA-001 KIN-BUG-001 KIN-ADR-001 ``` IDs must not be reused. --- ## 7. Backlog Status Values Every backlog item MUST use one of these statuses. ```yaml id="dwbeuw" BACKLOG_STATUS: - "candidate" - "ready_for_review" - "approved" - "blocked" - "in_progress" - "implemented" - "verified" - "deferred" - "rejected" ``` ### 7.1 Status Definitions | Status | Meaning | | ------------------ | ------------------------------------------------------------ | | `candidate` | Draft task, not yet approved for implementation. | | `ready_for_review` | Task is fully specified and ready for human review. | | `approved` | Task is approved for implementation. | | `blocked` | Task cannot proceed until dependency is resolved. | | `in_progress` | Task is actively being implemented. | | `implemented` | Code/doc change is complete but not fully verified. | | `verified` | Task passed tests and acceptance criteria. | | `deferred` | Valid task, but not in current implementation wave. | | `rejected` | Task violates scope, ownership, or architecture constraints. | --- ## 8. Backlog Priority Values ```yaml id="mofri0" PRIORITY: P0: "Required before any implementation can safely proceed." P1: "Required for first-pass Kintsugi implementation." P2: "Important but can follow first-pass implementation." P3: "Optional enhancement." P4: "Deferred future work." ``` ### Priority Rules * `P0` tasks are contract, safety, migration, or drift-control blockers. * `P1` tasks are first-pass implementation requirements. * `P2` tasks may improve completeness but are not blockers. * `P3` tasks are optional enhancements. * `P4` tasks must not be included in first-pass implementation. --- ## 9. Risk Values ```yaml id="f9dqlf" RISK_LEVEL: LOW: "Small isolated change; no schema break; easy rollback." MEDIUM: "Crosses frontend/backend or adds schema; manageable rollback." HIGH: "Touches source-of-truth data, permissions, migrations, or result publication." CRITICAL: "Should not proceed without explicit ADR and human approval." ``` Any `HIGH` or `CRITICAL` task MUST include: * explicit owner approval; * rollback plan; * migration safety note; * test plan; * drift-control check; * affected docs list. --- ## 10. Epic Template Use this template for every epic. ```markdown id="z6ewv4" ## — **Status:** candidate **Priority:** P1 **Risk:** MEDIUM **Owner Domain:** Korum | Konsultations | Smart Vote | EkoH | Drafting | Admin/Audit | External Boundary **Primary Route Family:** `/ethikos/...` **Primary Backend App:** `konnaxion.ethikos` | `konnaxion.kollective_intelligence` | `konnaxion.ekoh` **Source Docs:** - `#
` - `#
` ### Purpose Explain why this epic exists. ### Scope List what is included. ### Non-Goals List what must not be included. ### Required Tasks - `` - `` - `` - `` - `` - `` - `` ### Dependencies - `` - `` - `` ### Acceptance Criteria - [ ] All child tasks are verified. - [ ] No anti-drift rule is violated. - [ ] Existing smoke tests still pass. - [ ] New tests are added where required. - [ ] Related docs are updated. ### Rollback Strategy Describe how to disable, revert, or isolate the epic safely. ### Drift Check - [ ] Does not create full OSS merge. - [ ] Does not create new route family. - [ ] Does not rename existing models. - [ ] Does not mutate source facts through Smart Vote. - [ ] Does not turn EkoH into a voting engine. ``` --- ## 11. Task Template Use this template for every implementation task. ````markdown id="xwzvox" ## — **Status:** candidate **Priority:** P1 **Risk:** LOW | MEDIUM | HIGH | CRITICAL **Owner Domain:** Korum | Konsultations | Smart Vote | EkoH | Drafting | Admin/Audit | External Boundary **Task Type:** backend | frontend | api | data | migration | test | doc | qa | bugfix | adr **Source Docs:** - `#
` - `#
` ### 1. Intent Describe the task in one paragraph. ### 2. Scope This task includes: - `` - `` This task excludes: - `` - `` ### 3. Current Reality **Current frontend route(s):** ```txt ```` **Current backend endpoint(s):** ```txt ``` **Current backend model(s):** ```txt ``` **Current service/component/file(s):** ```txt ``` ### 4. Target Change Describe the exact desired change. ### 5. Affected Files **Frontend:** ```txt ``` **Backend:** ```txt ``` **Docs:** ```txt ``` **Tests:** ```txt ``` ### 6. Data / Schema Impact ```yaml SCHEMA_CHANGE_REQUIRED: false MIGRATION_REQUIRED: false NEW_MODEL_REQUIRED: false EXISTING_MODEL_MODIFIED: false DATA_BACKFILL_REQUIRED: false ``` If any value is `true`, describe the migration plan. ### 7. API Contract Impact ```yaml NEW_ENDPOINT_REQUIRED: false EXISTING_ENDPOINT_CHANGED: false SERIALIZER_CHANGED: false BACKWARD_COMPATIBLE: true ``` If any endpoint is added or changed, list the canonical API path. ### 8. Frontend Contract Impact ```yaml ROUTE_CHANGED: false NEW_COMPONENT_REQUIRED: false SERVICE_LAYER_CHANGE_REQUIRED: false RAW_FETCH_ALLOWED: false SHELL_LAYOUT_CHANGED: false ``` If UI is affected, list the route and component. ### 9. Acceptance Criteria * [ ] `` * [ ] `` * [ ] Existing behavior remains backward compatible. * [ ] No forbidden route/model/API drift. * [ ] Tests pass. ### 10. Tests Required * [ ] Backend unit test * [ ] Backend API test * [ ] Migration test * [ ] Frontend component test * [ ] Frontend route smoke * [ ] Playwright smoke * [ ] Manual QA ### 11. Rollback Plan Describe how to revert safely. ### 12. Risks | Risk | Severity | Mitigation | | -------- | --------------- | -------------- | | `` | LOW/MEDIUM/HIGH | `` | ### 13. Drift Check * [ ] Uses `/ethikos/*` route surface. * [ ] Uses canonical `/api/ethikos/*` or approved endpoint. * [ ] Does not expand `/api/home/*`. * [ ] Does not rename `EthikosTopic`, `EthikosStance`, `EthikosArgument`, or `EthikosCategory`. * [ ] Does not create `konnaxion.kialo`. * [ ] Does not treat `ArgumentImpactVote` as `EthikosStance`. * [ ] Does not treat `ReadingResult` as source fact. * [ ] Does not let Smart Vote mutate upstream records. * [ ] Does not let EkoH act as voting engine. * [ ] Does not directly import external OSS code. ```` --- ## 12. Backend Task Template Use this specialization for backend tasks. ```markdown id="rrtrh2" ## — **Status:** candidate **Priority:** P1 **Risk:** MEDIUM **Owner Domain:** `` **Backend App:** `konnaxion.ethikos` | `konnaxion.kollective_intelligence` | `konnaxion.ekoh` **Source Docs:** - `#
` ### Intent Describe the backend change. ### Allowed Backend Pattern ```yaml API_STYLE: "Django REST Framework ViewSet + Serializer + Router" AUTH_USER_MODEL: "users.User" ROUTER_FILE: "backend/config/api_router.py" DEFAULT_BACKEND_APP: "konnaxion.ethikos" ```` ### Affected Backend Files ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/api/serializers.py backend/konnaxion/ethikos/api/views.py backend/config/api_router.py ``` Replace paths with actual inspected paths. ### Model Impact ```yaml NEW_MODEL: "" EXISTING_MODEL: "" FIELDS_ADDED: - "" FIELDS_REMOVED: [] FIELDS_RENAMED: [] ``` ### Serializer Impact ```yaml NEW_SERIALIZER: "" EXISTING_SERIALIZER_CHANGED: "" BACKWARD_COMPATIBLE: true ``` ### ViewSet / Endpoint Impact ```yaml NEW_VIEWSET: "" EXISTING_VIEWSET_CHANGED: "" ENDPOINT: "/api/ethikos//" ``` ### Permissions Describe authentication, ownership, moderation, and admin rules. ### Acceptance Criteria * [ ] Existing endpoints still work. * [ ] New endpoint follows DRF style. * [ ] Serializer output matches contract. * [ ] Permissions are explicit. * [ ] Tests cover happy path and denied path. * [ ] No direct foreign tool writes to core tables. ```` --- ## 13. Frontend Task Template Use this specialization for frontend tasks. ```markdown id="fy8t8s" ## — **Status:** candidate **Priority:** P1 **Risk:** MEDIUM **Owner Domain:** `` **Route Family:** `/ethikos/...` **Source Docs:** - `#
` ### Intent Describe the frontend change. ### Allowed Frontend Pattern ```yaml PRIMARY_ROUTE_SURFACE: "/ethikos/*" USE_EXISTING_ETHIKOS_SHELL: true CREATE_SECOND_SHELL: false USE_SERVICE_LAYER: true RAW_FETCH_FROM_PAGE_COMPONENTS: false ```` ### Affected Frontend Files ```txt frontend/app/ethikos//page.tsx frontend/app/ethikos/EthikosPageShell.tsx frontend/services/.ts frontend/components/.tsx ``` Replace paths with actual inspected paths. ### Route Impact ```yaml EXISTING_ROUTE: "/ethikos//" NEW_ROUTE_REQUIRED: false ROUTE_RENAME_REQUIRED: false ``` ### Component Impact ```yaml NEW_COMPONENTS: - "" UPDATED_COMPONENTS: - "" REMOVED_COMPONENTS: [] ``` ### Service Impact ```yaml SERVICE_FILE: "frontend/services/.ts" NEW_SERVICE_FUNCTIONS: - "" UPDATED_SERVICE_FUNCTIONS: - "" RAW_FETCH_ALLOWED: false ``` ### Acceptance Criteria * [ ] Page remains under existing Ethikos shell. * [ ] No duplicate layout shell is introduced. * [ ] API calls go through service layer. * [ ] Route remains under `/ethikos/*`. * [ ] UI handles loading, empty, error, and success states. * [ ] Manual QA instructions are documented. ```` --- ## 14. Data / Migration Task Template Use this specialization for model and migration tasks. ```markdown id="ge2x4y" ## — **Status:** candidate **Priority:** P1 **Risk:** HIGH **Owner Domain:** `` **Source Docs:** - `08_DATA_MODEL_AND_MIGRATION_PLAN.md#
` - `12_CANONICAL_OBJECTS_AND_EVENTS.md#
` ### Intent Describe why the migration is needed. ### Migration Policy ```yaml BREAK_EXISTING_MODELS: false RENAME_EXISTING_MODELS: false DELETE_EXISTING_FIELDS: false ADD_NON_BREAKING_TABLES_ALLOWED: true ADD_NON_BREAKING_FIELDS_ALLOWED: true DATA_BACKFILL_REQUIRED: false ROLLBACK_REQUIRED: true ```` ### Current Model State ```txt ``` ### Proposed Schema Change ```yaml NEW_TABLES: - "" FIELDS_ADDED: - "" INDEXES_ADDED: - "" CONSTRAINTS_ADDED: - "" ``` ### Backward Compatibility Explain why existing data and endpoints remain valid. ### Migration Commands ```bash python manage.py makemigrations python manage.py migrate python manage.py check ``` Use project-approved local execution commands from the current development environment. ### Verification * [ ] Migration applies cleanly. * [ ] Migration rollback strategy exists. * [ ] No unexpected `makemigrations` drift. * [ ] Existing smoke tests still pass. * [ ] Existing Ethikos endpoints still work. ```` --- ## 15. API Contract Task Template Use this specialization for endpoint and payload tasks. ```markdown id="t8xjhe" ## — **Status:** candidate **Priority:** P1 **Risk:** MEDIUM **Owner Domain:** `` **Source Docs:** - `07_API_AND_SERVICE_CONTRACTS.md#
` - `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md#
` ### Intent Describe the API contract to add or stabilize. ### Endpoint ```yaml METHOD: "GET | POST | PATCH | DELETE" PATH: "/api/ethikos//" CANONICAL: true COMPAT_ALIAS: "" ```` ### Request Payload ```json { "field": "value" } ``` ### Response Payload ```json { "id": 1, "field": "value" } ``` ### Error Payload ```json { "detail": "Error message" } ``` ### Compatibility * [ ] Does not break existing consumers. * [ ] Does not rename existing endpoint. * [ ] Does not expand `/api/home/*`. * [ ] Uses DRF-compatible pagination/errors where relevant. ### Tests * [ ] Authorized request succeeds. * [ ] Unauthorized request fails correctly. * [ ] Invalid payload returns expected error. * [ ] Serializer shape matches contract. ```` --- ## 16. Test Task Template Use this specialization for test tasks. ```markdown id="p34jss" ## — **Status:** candidate **Priority:** P1 **Risk:** LOW **Owner Domain:** `` **Source Docs:** - `16_TEST_AND_SMOKE_CONTRACT.md#
` ### Intent Describe the behavior that must be tested. ### Test Type ```yaml BACKEND_UNIT: false BACKEND_API: false MIGRATION: false FRONTEND_COMPONENT: false FRONTEND_ROUTE: false PLAYWRIGHT_SMOKE: false MANUAL_QA: false ```` ### Target Behavior ```txt ``` ### Test Data ```yaml USERS: - "" TOPICS: - "" ARGUMENTS: - "" READINGS: - "" ``` ### Acceptance Criteria * [ ] Test fails before implementation if applicable. * [ ] Test passes after implementation. * [ ] Test covers success case. * [ ] Test covers failure/permission case where applicable. * [ ] Test does not rely on external OSS services. ```` --- ## 17. Bugfix Task Template Use this specialization for known bug tasks. ```markdown id="b1n4af" ## — **Status:** candidate **Priority:** P1 **Risk:** LOW | MEDIUM | HIGH **Classification:** targeted_bugfix_not_architecture **Source Docs:** - `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md#
` ### Bug Summary Describe the visible bug. ### Current Behavior ```txt ```` ### Expected Behavior ```txt ``` ### Suspected Cause ```txt ``` ### Affected Files ```txt ``` ### Fix Scope This bugfix may: * `` This bugfix must not: * redesign architecture; * change route families; * rename models; * introduce unrelated features. ### Acceptance Criteria * [ ] Bug no longer reproduces. * [ ] Existing behavior remains stable. * [ ] Regression test or manual QA step exists. * [ ] Fix does not become architecture rewrite. ```` --- ## 18. Documentation Task Template Use this specialization for documentation updates. ```markdown id="zkwwr0" ## — **Status:** candidate **Priority:** P2 **Risk:** LOW **Source Docs:** - `#
` ### Intent Describe the documentation update. ### Target Files ```txt ```` ### Required Changes * `` * `` ### Acceptance Criteria * [ ] Terminology matches `04_CANONICAL_NAMING_AND_VARIABLES.md`. * [ ] Ownership matches `03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md`. * [ ] Route references match `06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md`. * [ ] No deferred OSS source is promoted to first pass. * [ ] Related docs are cross-linked. ```` --- ## 19. QA Task Template Use this specialization for verification tasks. ```markdown id="i9tx0h" ## — **Status:** candidate **Priority:** P1 **Risk:** LOW **Source Docs:** - `16_TEST_AND_SMOKE_CONTRACT.md#
` ### Intent Describe the verification target. ### Verification Type ```yaml MANUAL_ROUTE_QA: false API_SMOKE: false FRONTEND_SMOKE: false MIGRATION_CHECK: false REGRESSION_CHECK: false DOC_CONSISTENCY_CHECK: false ```` ### Steps 1. `` 2. `` 3. `` ### Expected Result ```txt ``` ### Evidence to Capture * screenshot; * terminal output; * test result; * API response; * migration output; * linked PR/commit. ### Acceptance Criteria * [ ] Verification completed. * [ ] Evidence captured. * [ ] No new regression found. * [ ] Drift-control checklist passed. ```` --- ## 20. Required Backlog Columns When converting tasks into a spreadsheet, project board, issue tracker, or Markdown table, use these columns. | Column | Required | Description | |---|---:|---| | `id` | Yes | Stable backlog ID. | | `title` | Yes | Short task title. | | `status` | Yes | Candidate, approved, in progress, verified, etc. | | `priority` | Yes | P0–P4. | | `risk` | Yes | LOW, MEDIUM, HIGH, CRITICAL. | | `owner_domain` | Yes | Korum, Konsultations, Smart Vote, EkoH, etc. | | `task_type` | Yes | backend, frontend, api, data, migration, test, doc, qa, bugfix, adr. | | `source_docs` | Yes | Source documentation references. | | `route_scope` | Yes | Route family affected. | | `backend_scope` | Yes | Backend app/model/endpoint affected. | | `frontend_scope` | Yes | Frontend route/component/service affected. | | `schema_change` | Yes | true/false. | | `migration_required` | Yes | true/false. | | `tests_required` | Yes | Required tests. | | `dependencies` | Yes | Blocking tasks or docs. | | `acceptance_criteria` | Yes | Verification checklist. | | `rollback_note` | Yes | How to revert safely. | | `drift_check_passed` | Yes | true/false. | --- ## 21. Backlog Markdown Table Template ```markdown id="nl34yc" | ID | Title | Status | Priority | Risk | Owner Domain | Type | Route Scope | Backend Scope | Frontend Scope | Source Docs | Depends On | |---|---|---|---|---|---|---|---|---|---|---|---| | KIN-XXX-001 | | candidate | P1 | MEDIUM | Korum | backend | /ethikos/deliberate/* | konnaxion.ethikos | N/A | 12, 21 | <dependency> | ```` --- ## 22. Backlog YAML Item Template ```yaml id="dwcn66" id: "KIN-XXX-###" title: "<Task title>" status: "candidate" priority: "P1" risk: "MEDIUM" owner_domain: "Korum" task_type: "backend" source_docs: - "12_CANONICAL_OBJECTS_AND_EVENTS.md#<section>" - "21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md#<section>" route_scope: - "/ethikos/deliberate/*" backend_scope: app: "konnaxion.ethikos" models: - "<model>" endpoints: - "/api/ethikos/<resource>/" frontend_scope: routes: - "/ethikos/deliberate/[topic]" services: - "frontend/services/<service>.ts" schema: schema_change_required: false migration_required: false data_backfill_required: false tests_required: - "backend_api" - "frontend_route_smoke" dependencies: - "<KIN-... or doc>" acceptance_criteria: - "<criterion>" rollback: strategy: "<rollback strategy>" drift_check: route_drift: false model_rename_drift: false ownership_drift: false vote_semantics_drift: false oss_merge_drift: false ``` --- ## 23. Epic Categories for the Real Backlog The real backlog should be grouped into these epics after code reading. ```yaml id="a8fh3y" RECOMMENDED_EPICS: KIN-EPIC-001: title: "Drift-control and documentation alignment" owner_domain: "Admin/Audit" KIN-EPIC-002: title: "Ethikos API and service contract stabilization" owner_domain: "Korum" KIN-EPIC-003: title: "Kialo-style structured deliberation" owner_domain: "Korum" KIN-EPIC-004: title: "Konsultations intake, decisions, and ballots" owner_domain: "Konsultations" KIN-EPIC-005: title: "Smart Vote readings and EkoH snapshot references" owner_domain: "Smart Vote / EkoH" KIN-EPIC-006: title: "Drafting and rationale packets" owner_domain: "Drafting" KIN-EPIC-007: title: "Impact and accountability tracking" owner_domain: "Konsultations" KIN-EPIC-008: title: "Admin, audit, moderation, and permissions" owner_domain: "Admin/Audit" KIN-EPIC-009: title: "Frontend route-by-route Kintsugi alignment" owner_domain: "Frontend" KIN-EPIC-010: title: "Tests, smoke checks, and release verification" owner_domain: "QA" ``` These are suggested groupings, not implementation tasks. --- ## 24. Sequencing Template The real backlog SHOULD be sequenced in waves. ```markdown id="yrnzjz" # Implementation Sequence ## Wave 0 — Safety and Baseline Confirmation Purpose: confirm current system state and prevent drift. Required before Wave 1: - [ ] Current routes confirmed. - [ ] Current endpoints confirmed. - [ ] Current models confirmed. - [ ] Known bug list confirmed. - [ ] Smoke tests confirmed. - [ ] Docs accepted. ## Wave 1 — Backend Contract Foundations Purpose: add only non-breaking backend foundations. Allowed work: - serializers; - viewsets; - non-breaking models; - migrations; - permissions; - tests. Forbidden work: - frontend redesign; - full UX rebuild; - annex integrations. ## Wave 2 — Frontend Service and Route Alignment Purpose: connect existing `/ethikos/*` pages to stable services and contracts. Allowed work: - service wrappers; - route-level data loading; - empty/error/loading states; - Kintsugi panels; - bugfixes tied to known issues. ## Wave 3 — Korum / Kialo-Style Deliberation Purpose: add structured argument graph, sources, impact votes, suggestions, permissions. Allowed work: - argument tree; - source panel; - impact vote distinction; - participant roles; - visibility/anonymity controls. ## Wave 4 — Konsultations / Decision / Smart Vote Purpose: add decision records, protocols, readings, lens declarations, result publication. Allowed work: - decision records; - baseline results; - reading results; - Smart Vote/EkoH references. ## Wave 5 — Drafting and Accountability Purpose: add draft/version/amendment and impact tracking capabilities. Allowed work: - drafts; - amendments; - rationale packets; - impact tracks; - impact updates. ## Wave 6 — QA, Docs, and Release Readiness Purpose: verify and document. Allowed work: - smoke tests; - regression QA; - docs patching; - final release checklist. ``` --- ## 25. Dependency Rules Backlog tasks must express dependencies explicitly. ### 25.1 Backend Before Frontend Frontend tasks that consume new data must depend on backend/API tasks. ```txt id="frxrwe" KIN-FE-### depends on KIN-API-### and/or KIN-BE-### ``` ### 25.2 Migration Before Serializer Serializer tasks that expose new model fields must depend on migration tasks. ```txt id="oz4dce" KIN-API-### depends on KIN-MIG-### ``` ### 25.3 Payload Contract Before UI UI tasks that render new payloads must depend on payload contract tasks. ```txt id="iqwcvv" KIN-FE-### depends on KIN-API-### and 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACT.md ``` ### 25.4 Reading Before Result UI Smart Vote result UI must depend on reading contract and backend reading result support. ```txt id="uvlgyz" KIN-FE-### depends on KIN-BE-### + KIN-API-### + 09_SMART_VOTE_EKOH_READING_CONTRACT.md ``` ### 25.5 Bugfix Isolation Known bug tasks must not depend on unrelated architecture tasks unless code reading proves a direct dependency. --- ## 26. Acceptance Criteria Library Use these reusable criteria when applicable. ### 26.1 General ```markdown id="kis8ub" - [ ] Task is traceable to accepted Kintsugi docs. - [ ] Task does not conflict with source-of-truth hierarchy. - [ ] Task does not introduce route drift. - [ ] Task does not introduce model naming drift. - [ ] Task does not introduce ownership drift. - [ ] Task does not introduce vote semantics drift. - [ ] Task includes tests or explicit QA. - [ ] Task includes rollback note. ``` ### 26.2 Backend ```markdown id="v7qcon" - [ ] Uses existing backend app unless explicitly approved. - [ ] Uses DRF ViewSet/Serializer/Router pattern. - [ ] Preserves existing endpoints. - [ ] Adds only backward-compatible fields/tables. - [ ] Does not mutate upstream facts from Smart Vote. - [ ] Does not make EkoH a voting engine. ``` ### 26.3 Frontend ```markdown id="ucul9o" - [ ] Page remains under `/ethikos/*`. - [ ] Existing module/global shell is preserved. - [ ] No duplicate layout or theme system is introduced. - [ ] API access goes through service layer. - [ ] Loading, empty, error, and success states are handled. ``` ### 26.4 Kialo-Style Deliberation ```markdown id="m7dpdt" - [ ] `Claim` remains conceptual; backend model remains `EthikosArgument`. - [ ] `ArgumentImpactVote` is separate from `EthikosStance`. - [ ] Sources attach to argument/claim nodes. - [ ] Suggested claims follow role/approval rules. - [ ] Anonymous identities are protected from normal participants. ``` ### 26.5 Smart Vote / EkoH ```markdown id="v3etft" - [ ] Baseline remains visible. - [ ] Reading is derived and reproducible. - [ ] Reading stores `reading_key`, `lens_hash`, `snapshot_ref`, `computed_at`, and `results_payload`. - [ ] EkoH is used as context only. - [ ] Smart Vote does not mutate source facts. ``` --- ## 27. Drift Rejection Rules A backlog item MUST be rejected if it does any of the following. ```txt id="lq8m4d" Creates /kialo route family. Creates /kintsugi route family as implementation target. Creates konnaxion.kialo. Renames EthikosArgument to Claim. Renames EthikosStance to Opinion. Treats ArgumentImpactVote as EthikosStance. Treats ReadingResult as source fact. Uses Smart Vote to mutate Korum or Konsultations records. Uses EkoH as voting engine. Expands /api/home/*. Imports external OSS app directly. Adds Polis, LiquidFeedback, All Our Ideas, Your Priorities, or OpenSlides to first pass. Introduces implementation tasks without source docs. Introduces schema changes without migration/testing plan. ``` --- ## 28. Candidate Backlog Generation Prompt Use this prompt after all readiness gates are passed. ```text id="i85cqc" Generate the candidate implementation backlog for the ethiKos Kintsugi upgrade. Use: - 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md - 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md - 04_CANONICAL_NAMING_AND_VARIABLES.md - 05_CURRENT_STATE_BASELINE.md - 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md - 07_API_AND_SERVICE_CONTRACTS.md - 08_DATA_MODEL_AND_MIGRATION_PLAN.md - 09_SMART_VOTE_EKOH_READING_CONTRACT.md - 10_FIRST_PASS_INTEGRATION_MATRIX.md - 11_MIMIC_VS_ANNEX_RULEBOOK.md - 12_CANONICAL_OBJECTS_AND_EVENTS.md - 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md - 14_FRONTEND_ALIGNMENT_CONTRACT.md - 15_BACKEND_ALIGNMENT_CONTRACT.md - 16_TEST_AND_SMOKE_CONTRACT.md - 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md - 18_ADR_REGISTER.md - 19_OSS_CODE_READING_PLAN.md - 20_AI_GENERATION_GUARDRAILS.md - 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md - current code-reading findings Generate: 1. Epics 2. Backend tasks 3. Frontend tasks 4. API tasks 5. Data/migration tasks 6. Test tasks 7. QA tasks 8. Documentation patch tasks Use the exact template from 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md. Do not implement code. Do not invent routes, apps, models, or endpoints. Do not promote deferred OSS sources to first pass. ``` --- ## 29. Candidate Backlog Review Prompt Use this prompt after generating the candidate backlog. ```text id="f0y0e3" Review the candidate Kintsugi implementation backlog for drift. Check every task against: - source-of-truth hierarchy - ownership boundaries - canonical naming - route contracts - API contracts - data model contracts - Smart Vote/EkoH reading rules - Kialo-style argument mapping rules - anti-drift rules - first-pass/deferred OSS scope Return: 1. tasks approved as-is 2. tasks requiring revision 3. tasks that must be rejected 4. missing dependencies 5. missing tests 6. missing rollback notes 7. sequencing corrections ``` --- ## 30. Example Candidate Task This is an example of the expected format. It is not an approved task. ````markdown id="yc2ipj" ## KIN-BE-EXAMPLE — Add ArgumentSource model **Status:** candidate **Priority:** P1 **Risk:** MEDIUM **Owner Domain:** Korum **Task Type:** backend **Source Docs:** - `12_CANONICAL_OBJECTS_AND_EVENTS.md#ArgumentSource` - `21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md#Sources` ### 1. Intent Add a first-pass native Ethikos model for source links attached to `EthikosArgument`, supporting Kialo-style evidence transparency without creating a separate Kialo app. ### 2. Scope This task includes: - defining `ArgumentSource`; - linking it to `EthikosArgument`; - adding serializer support; - adding API test coverage. This task excludes: - source export UI; - custom source ranking; - external citation crawling; - importing Kialo code. ### 3. Current Reality **Current frontend route(s):** ```txt /ethikos/deliberate/[topic] ```` **Current backend endpoint(s):** ```txt /api/ethikos/arguments/ ``` **Current backend model(s):** ```txt EthikosArgument ``` ### 4. Target Change Add source attachment support for argument nodes while preserving existing argument behavior. ### 5. Affected Files **Backend:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/api/serializers.py backend/konnaxion/ethikos/api/views.py backend/config/api_router.py ``` **Tests:** ```txt backend/konnaxion/ethikos/tests/ ``` ### 6. Data / Schema Impact ```yaml SCHEMA_CHANGE_REQUIRED: true MIGRATION_REQUIRED: true NEW_MODEL_REQUIRED: true EXISTING_MODEL_MODIFIED: false DATA_BACKFILL_REQUIRED: false ``` ### 7. API Contract Impact ```yaml NEW_ENDPOINT_REQUIRED: true EXISTING_ENDPOINT_CHANGED: false SERIALIZER_CHANGED: true BACKWARD_COMPATIBLE: true ``` ### 8. Acceptance Criteria * [ ] `EthikosArgument` remains unchanged in name and core semantics. * [ ] `ArgumentSource` links to `EthikosArgument`. * [ ] Existing argument posting still works. * [ ] Source creation requires authenticated user. * [ ] Tests cover creation and retrieval. * [ ] No `/kialo` route or backend app is introduced. ### 9. Rollback Plan Drop the new endpoint and model migration before production use, or disable source UI while preserving existing argument flow. ### 10. Drift Check * [x] Uses `/ethikos/deliberate/*`. * [x] Uses `konnaxion.ethikos`. * [x] Does not rename `EthikosArgument`. * [x] Does not import Kialo code. ```` --- ## 31. Final Backlog Output Structure When the real backlog is generated, output it in this order. ```markdown id="r2p25d" # ethiKos Kintsugi Implementation Backlog ## 1. Readiness Gate Result ## 2. Epic Overview ## 3. Sequencing Plan ## 4. Dependency Graph Summary ## 5. Backend Tasks ## 6. API Tasks ## 7. Data / Migration Tasks ## 8. Frontend Tasks ## 9. Smart Vote / EkoH Tasks ## 10. Kialo-Style Deliberation Tasks ## 11. Konsultations / Impact Tasks ## 12. Test Tasks ## 13. QA Tasks ## 14. Documentation Patch Tasks ## 15. Deferred Tasks ## 16. Rejected Tasks ## 17. Risk Register ## 18. Release Checklist ```` --- ## 32. Backlog Risk Register Template ```markdown id="mk5tv0" # Risk Register | Risk ID | Related Task | Risk | Severity | Mitigation | Owner | Status | |---|---|---|---|---|---|---| | RISK-001 | KIN-XXX-### | <risk> | MEDIUM | <mitigation> | <owner> | open | ``` Required risk categories: ```yaml id="nfbrbz" RISK_CATEGORIES: - "schema_migration" - "route_drift" - "api_contract_break" - "frontend_shell_drift" - "ownership_drift" - "vote_semantics_drift" - "smart_vote_reproducibility" - "ekoh_role_confusion" - "oss_scope_drift" - "test_coverage_gap" - "rollback_gap" ``` --- ## 33. Release Checklist Template ```markdown id="g3nw71" # Kintsugi Release Checklist ## Documentation - [ ] All Kintsugi docs are accepted. - [ ] Related docs are cross-linked. - [ ] Deferred scope is clearly marked. - [ ] ADRs are complete. ## Backend - [ ] Migrations apply cleanly. - [ ] No unexpected `makemigrations` drift. - [ ] Existing Ethikos endpoints still work. - [ ] New endpoints are tested. - [ ] Permissions are verified. ## Frontend - [ ] Existing `/ethikos/*` routes render. - [ ] No duplicate shell/layout is introduced. - [ ] New UI uses service layer. - [ ] Loading/empty/error states work. - [ ] Preview drawer known bug is either fixed or explicitly tracked. ## Smart Vote / EkoH - [ ] Baseline remains visible. - [ ] Readings are reproducible. - [ ] `snapshot_ref` is handled correctly. - [ ] EkoH remains context only. ## Kialo-Style Deliberation - [ ] Claims map to `EthikosArgument`. - [ ] Impact votes remain separate from topic stances. - [ ] Sources attach correctly. - [ ] Suggested claims follow role rules. - [ ] Anonymity rules are respected. ## Tests - [ ] Backend tests pass. - [ ] Frontend smoke passes. - [ ] Playwright smoke passes where applicable. - [ ] Manual QA completed. ## Drift Control - [ ] No full OSS merge. - [ ] No new Kialo app. - [ ] No route drift. - [ ] No model rename drift. - [ ] No `/api/home/*` expansion. ``` --- ## 34. Non-Goals This document does not: * generate the actual backlog; * implement code; * define final migrations; * write serializers; * write frontend components; * write API payloads; * resolve the preview drawer bug; * inspect OSS repositories; * approve annex architecture; * authorize full external merges. --- ## 35. Anti-Drift Rules The implementation backlog must obey these rules. ```txt id="k8pd4v" Do not generate implementation tasks before docs and code-reading are complete. Do not create tasks without source document references. Do not create tasks without affected route/API/model/file scope. Do not create tasks without tests or QA. Do not create tasks without rollback notes. Do not create tasks that rename current Ethikos core models. Do not create tasks that bypass current Ethikos route families. Do not create tasks that import full OSS applications. Do not create tasks that confuse Kialo impact votes with Ethikos stances. Do not create tasks that treat Smart Vote readings as source facts. Do not create tasks that make EkoH the voting engine. Do not create tasks that expand `/api/home/*`. ``` --- ## 36. Related Docs This template depends on: ```txt id="q409w2" 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md ``` This template is used after those documents are accepted. --- ## 37. Final Binding Rule The real Kintsugi implementation backlog is invalid unless it follows this template. ```yaml id="kvrksw" FINAL_RULE: IF_BACKLOG_ITEM_HAS_NO_SOURCE_DOC: RESULT: "invalid" IF_BACKLOG_ITEM_HAS_NO_ROUTE_API_MODEL_SCOPE: RESULT: "invalid" IF_BACKLOG_ITEM_HAS_NO_TEST_OR_QA_PLAN: RESULT: "invalid" IF_BACKLOG_ITEM_HAS_NO_ROLLBACK_NOTE: RESULT: "invalid" IF_BACKLOG_ITEM_VIOLATES_SOURCE_OF_TRUTH: RESULT: "invalid" IF_BACKLOG_ITEM_EXPANDS_FIRST_PASS_SCOPE: RESULT: "invalid" IF_BACKLOG_ITEM_IMPORTS_FULL_OSS_APP: RESULT: "invalid" IF_BACKLOG_ITEM_RENAMES_EXISTING_CORE_MODEL: RESULT: "invalid" ``` This document is the canonical template for converting the ethiKos Kintsugi documentation pack into implementation work. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3980fbe85df409e89d98b3190fae8dc5038b04078e145ebeef4170a3b0f906f2 CONTENT_BYTES: 39133 ================================================================================================ # 23 — Wave 1 Implementation Backlog **Document ID:** `23_WAVE1_IMPLEMENTATION_BACKLOG.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Target repo path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md` **Generated for local path:** `C:\mycode\Konnaxion\Konnaxion\docs\Technical-Reference\Kintsugi_Kompendio\ethiKos_Kintsugi_Update\23_WAVE1_IMPLEMENTATION_BACKLOG.md` **Status:** Implementation backlog draft **Last aligned:** 2026-04-27 **Primary scope:** Existing `/ethikos/*` route family **Implementation mode:** Partial native mimic, no full external merge **Execution strategy:** Slice-by-slice, with a thin shared foundation first --- ## 1. Purpose This document converts the ethiKos Kintsugi documentation pack into an implementation backlog for Wave 1. Wave 1 is defined as **all work included in `DocKintsugi_Kompendio.txt`**, landed inside the current Konnaxion codebase without creating a new Kintsugi app, new Kialo app, parallel route family, or foreign OSS import. The backlog is intentionally organized into vertical slices so implementation can be split across multiple focused coding sessions. The Korum slice is expected to be the first full vertical slice after the shared foundation, because it exercises the canonical backend/frontend patterns without crossing too deeply into Smart Vote or EkoH ownership. --- ## 2. Canonical Variables ```yaml DOCUMENT_ID: "23_WAVE1_IMPLEMENTATION_BACKLOG.md" KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial_native_mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_CORE_MODELS_STABLE: true BACKLOG_AFTER_DOCS_AND_CODE_READING: true ``` ```yaml PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_ROUTE_FAMILIES: DECIDE: "/ethikos/decide/*" DELIBERATE: "/ethikos/deliberate/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" IMPACT: "/ethikos/impact/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" ``` ```yaml CURRENT_ETHIKOS_CORE_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_CANONICAL_ENDPOINTS: ETHIKOS_TOPICS: "/api/ethikos/topics/" ETHIKOS_STANCES: "/api/ethikos/stances/" ETHIKOS_ARGUMENTS: "/api/ethikos/arguments/" ETHIKOS_CATEGORIES: "/api/ethikos/categories/" KOLLECTIVE_VOTES: "/api/kollective/votes/" ``` ```yaml OWNERSHIP: KORUM: - "topics" - "arguments" - "argument graph" - "topic-level stances" - "debate moderation" KONSULTATIONS: - "intake" - "consultations" - "ballots" - "result snapshots" - "impact tracking" SMART_VOTE: - "readings" - "lens declarations" - "derived aggregations" - "result publication" EKOH: - "expertise context" - "ethics context" - "cohort eligibility" - "snapshot context" ``` ```yaml WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false READINGS_ARE_DERIVED: true ``` ```yaml KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ``` --- ## 3. Source-of-Truth Priority When the implementation session encounters conflicting information, use this priority order: ```yaml SOURCE_PRIORITY_ORDER: 1_CODE_SNAPSHOT_REALITY: description: "Routes, files, endpoints, current models, current serializers, current frontend services, current tests." 2_BOUNDARIES_AND_OWNERSHIP: description: "Korum/Konsultations/Smart Vote/EkoH ownership, write rules, and pipeline boundaries." 3_KINTSUGI_KOMPENDIO: description: "Wave 1 scope, route-by-route plan, API contracts, payload contracts, backend/frontend alignment." 4_KIALO_STYLE_MAPPING: description: "Structured deliberation inspiration only for /ethikos/deliberate/*." 5_OSS_REFERENCE_DOCS: description: "Pattern inspiration only; no first-pass merge or import." ``` --- ## 4. Readiness Gate The backlog is generated because the planning session has access to: - the Kintsugi Kompendio documentation pack; - the current repo snapshot volumes for backend, frontend, docs, endpoint graph, PlantUML, scripts, and miscellaneous files; - OSS reference documentation uploads for Kialo-style mapping, Loomio, Citizen OS, Consider.it, Decidim, CONSUL Democracy, and DemocracyOS. Local repository execution has not been performed inside the planning session. Therefore, implementation tasks MUST still be validated in the developer checkout. ```yaml READINESS_STATUS: DOCS_PACK_AVAILABLE: true REPO_SNAPSHOT_AVAILABLE: true BACKEND_SNAPSHOT_AVAILABLE: true FRONTEND_SNAPSHOT_AVAILABLE: true ENDPOINT_GRAPH_AVAILABLE: true OSS_REFERENCE_DOCS_AVAILABLE: true LOCAL_TESTS_EXECUTED_BY_AI_SESSION: false MIGRATIONS_GENERATED_IN_LIVE_CHECKOUT: false FINAL_BACKLOG_CAN_BE_USED_FOR_SLICE_PLANNING: true ``` --- ## 5. Wave 1 Execution Strategy Use a hybrid strategy: 1. code a thin shared foundation first; 2. build vertical slices one at a time; 3. consolidate common files after real slice pressure appears; 4. run validation and no-drift checks after every slice; 5. only merge a slice when it leaves the repo runnable. Do not pre-build every model, endpoint, service, and component up front. Do not leave all shared files until the end. Seed the reference pattern, then let slices expand it. --- ## 6. Slice Register | Slice | Name | Primary ownership | Primary route/API surface | Status | |---:|---|---|---|---| | 0 | Foundation / no-drift baseline | Shared | all `/ethikos/*`, `/api/ethikos/*` | Ready | | 1 | Korum / Deliberate | Korum | `/ethikos/deliberate/*`, `/api/ethikos/*` | Ready next | | 2 | Konsultations / Decide | Konsultations | `/ethikos/decide/*`, `/api/ethikos/*` | Planned | | 3 | Smart Vote readings | Smart Vote | `/ethikos/decide/*`, `/ethikos/insights`, `/api/kollective/*` | Planned | | 4 | EkoH trust/context | EkoH | `/ethikos/trust/*`, `/ethikos/insights`, EkoH APIs | Planned | | 5 | Drafting / rationale | ethiKos bounded capability | `/ethikos/decide/*`, `/ethikos/deliberate/*` | Planned | | 6 | Impact / accountability | Konsultations | `/ethikos/impact/*` | Planned | | 7 | Pulse / civic health | ethiKos read model | `/ethikos/pulse/*` | Planned | | 8 | Insights / interpretation | Smart Vote + EkoH + Impact | `/ethikos/insights` | Planned | | 9 | Admin / governance | Admin + moderation | `/ethikos/admin/*` | Planned | | 10 | Learn / public explanation | Documentation/UI | `/ethikos/learn/*`, `/ethikos/decide/methodology` | Planned | | 11 | Test/smoke hardening | QA | backend + frontend tests | Planned | | 12 | Documentation/ADR/release notes | Docs | Kintsugi docs | Planned | --- ## 7. Shared Files Strategy ### 7.1 Code now as foundation These files form the initial reference pattern and may be touched before Slice 1: ```txt backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/urls.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/tests.py backend/config/api_router.py frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/index.ts frontend/api.ts docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md ``` Foundation edits should introduce conventions, constants, safe helper patterns, route stability checks, and minimal service normalization. They should not add every future Wave 1 model. ### 7.2 Shared files that must be conflict-managed These files are common across multiple slices and should be patched carefully: ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/admin.ts frontend/services/index.ts frontend/api.ts frontend/app/ethikos/EthikosPageShell.tsx frontend/app/ethikos/layout.tsx ``` ### 7.3 Do not code in foundation Delay these until their vertical slices: ```txt backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/kollective_intelligence/admin.py backend/konnaxion/ekoh/models/* backend/konnaxion/ekoh/serializers/* backend/konnaxion/ekoh/services/* backend/konnaxion/ekoh/views/* frontend/app/ethikos/decide/* frontend/app/ethikos/impact/* frontend/app/ethikos/pulse/* frontend/app/ethikos/trust/* frontend/app/ethikos/insights/page.tsx frontend/app/ethikos/admin/* ``` --- ## 8. Backlog Items Each backlog item must declare route, endpoint, model, tests, source trace, and rollback notes. ### W1-000 — Foundation / no-drift baseline **Goal:** Establish the shared implementation guardrails before vertical slices begin. **Scope:** - create `backend/konnaxion/ethikos/constants.py`; - create `backend/konnaxion/ethikos/permissions.py`; - define allowed stance and impact-vote ranges as separate constants; - define shared visibility, role, moderation, and publication choices only where they are stable; - normalize `/api/ethikos/*` path helpers in frontend service layer; - add no-drift tests for forbidden route/app creation; - document slice order and shared-file conflict policy in this backlog. **Files:** ```txt backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/serializers.py backend/config/api_router.py backend/konnaxion/ethikos/tests.py frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/index.ts frontend/api.ts docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md ``` **Endpoints:** - preserve `/api/ethikos/topics/`; - preserve `/api/ethikos/stances/`; - preserve `/api/ethikos/arguments/`; - preserve `/api/ethikos/categories/`; - preserve `/api/kollective/votes/`; - do not add `/api/kialo/*`; - do not add `/api/kintsugi/*`; - do not expand `/api/home/*`. **Tests:** - current ethiKos models still import; - current ethiKos routes still reverse; - forbidden Kialo/Kintsugi routes are absent; - `/api/home/*` is not expanded for Wave 1; - frontend services import without circular dependency. **Rollback:** - remove newly created helper files if unused; - revert service helper imports; - keep existing model and router definitions intact. --- ### W1-010 — Korum / Deliberate structured argument slice **Goal:** Upgrade `/ethikos/deliberate/*` into the first full Kintsugi slice and use it as the reference implementation pattern. **Scope:** - fix the Deliberate preview drawer `Preview / No data` bug; - add source metadata for arguments; - add argument-level impact vote distinct from topic stance and Smart Vote reading; - add argument suggestion workflow; - add participant role and discussion visibility models; - expose new serializers/viewsets/actions under `/api/ethikos/*`; - update the deliberate topic UI to display sources, impact votes, suggestions, roles, and visibility state; - preserve `EthikosTopic`, `EthikosArgument`, `EthikosStance`, and `EthikosCategory` names. **Candidate models:** ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0003_kintsugi_wave1_korum.py backend/konnaxion/ethikos/tests.py frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/app/ethikos/deliberate/[topic]/page.tsx frontend/app/ethikos/deliberate/elite/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/topics/{id}/preview/ GET /api/ethikos/arguments/?topic=<id> POST /api/ethikos/arguments/ GET /api/ethikos/argument-sources/?argument=<id> POST /api/ethikos/argument-sources/ GET /api/ethikos/argument-impact-votes/?argument=<id> POST /api/ethikos/argument-impact-votes/ GET /api/ethikos/argument-suggestions/?topic=<id> POST /api/ethikos/argument-suggestions/ PATCH /api/ethikos/argument-suggestions/{id}/ GET /api/ethikos/discussion-roles/?topic=<id> GET /api/ethikos/discussion-visibility/?topic=<id> ``` **Tests:** - preview returns topic metadata when topic exists even if arguments are empty; - `EthikosStance.value` remains `-3..3`; - `ArgumentImpactVote.value` is separate from stance and uses the Kialo-style impact scale; - suggestions do not create arguments until accepted; - hidden arguments are excluded from public reads unless requester is allowed; - no `/kialo` or `/kintsugi` routes are introduced. **Rollback:** - reverse Korum migration; - unregister Korum-specific ViewSets; - remove frontend rendering of Korum-specific panels; - leave existing topics, stances, arguments, and categories intact. --- ### W1-020 — Konsultations / Decide slice **Goal:** Upgrade `/ethikos/decide/*` for intake, consultation participation, public/elite ballot capture, and result snapshots while remaining inside ethiKos route and model boundaries. **Scope:** - formalize consultation lifecycle using existing ethiKos topics as the source object where appropriate; - add intake/suggestion workflow if not covered by Korum suggestion model; - add ballot capture distinct from topic stance when needed; - add result snapshot model for published consultation outcomes; - align public and elite decide pages with service layer; - preserve current stance endpoints during migration. **Candidate models:** ```txt ConsultationIntake ConsultationBallot ConsultationResultSnapshot DecisionProtocol DecisionRecord ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0004_kintsugi_wave1_konsultations.py backend/konnaxion/ethikos/tests.py frontend/services/decide.ts frontend/services/ethikos.ts frontend/app/ethikos/decide/public/page.tsx frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/decide/methodology/page.tsx frontend/modules/konsultations/hooks/useConsultationResults.ts frontend/modules/konsultations/hooks/useConsultationVote.ts ``` **Endpoints:** ```txt GET /api/ethikos/consultation-intakes/ POST /api/ethikos/consultation-intakes/ GET /api/ethikos/consultation-ballots/?topic=<id> POST /api/ethikos/consultation-ballots/ GET /api/ethikos/consultation-results/?topic=<id> POST /api/ethikos/consultation-results/ GET /api/ethikos/decision-protocols/?topic=<id> POST /api/ethikos/decision-protocols/ GET /api/ethikos/decision-records/?topic=<id> POST /api/ethikos/decision-records/ ``` **Tests:** - public vote/ballot capture succeeds for valid topic; - duplicate ballot policy is explicit; - result snapshot is immutable after publication unless admin action records an audit event; - `EthikosStance` compatibility remains available; - public/elite decide routes do not call unmapped legacy placeholders. **Rollback:** - reverse Konsultations migration; - remove decide service methods and UI calls; - preserve existing topic/stance state. --- ### W1-030 — Smart Vote readings slice **Goal:** Add Smart Vote reading artifacts as derived outputs without allowing Smart Vote to mutate Korum or Konsultations source facts. **Scope:** - create lens declaration and reading result structures; - connect readings to consultation/topic/result snapshots; - keep `/api/kollective/*` as the Smart Vote-compatible API surface; - expose reading summaries to decide results and insights; - do not write to Korum arguments, topic stances, or consultation ballots from Smart Vote processing. **Candidate models:** ```txt LensDeclaration ReadingResult ReadingPublication ReadingInputSnapshot ``` **Files:** ```txt backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/kollective_intelligence/admin.py backend/konnaxion/kollective_intelligence/migrations/0002_kintsugi_wave1_readings.py backend/konnaxion/kollective_intelligence/tests/test_kintsugi_wave1_readings.py backend/config/api_router.py frontend/services/readings.ts frontend/services/decide.ts frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/insights/page.tsx ``` **Endpoints:** ```txt GET /api/kollective/lens-declarations/ POST /api/kollective/lens-declarations/ GET /api/kollective/reading-results/?topic=<id> POST /api/kollective/reading-results/ GET /api/kollective/reading-publications/?topic=<id> POST /api/kollective/reading-publications/ ``` **Tests:** - reading result can reference source topic/consultation snapshot; - reading creation does not modify `EthikosTopic`, `EthikosStance`, `EthikosArgument`, consultation ballot, or result snapshot rows; - publication status changes are auditable; - decide results page can display reading output. **Rollback:** - reverse Kollective reading migration; - unregister reading ViewSets; - remove frontend reading panels; - preserve existing `/api/kollective/votes/` behavior. --- ### W1-040 — EkoH trust/context slice **Goal:** Expose EkoH expertise, ethics, cohort, and snapshot context to ethiKos without turning EkoH into a voting engine. **Scope:** - add or expose EkoH context snapshots relevant to ethiKos; - show trust/profile/context information under `/ethikos/trust/*`; - allow Smart Vote readings to reference EkoH context snapshots as read-only inputs; - add admin-visible controls for context/eligibility review only where supported by current EkoH models. **Candidate models or read models:** ```txt EkohContextSnapshot EkohCohortEligibilitySnapshot EkohEthicsContextSnapshot EkohExpertiseContextSnapshot ``` **Files:** ```txt backend/konnaxion/ekoh/models/* backend/konnaxion/ekoh/serializers/* backend/konnaxion/ekoh/services/* backend/konnaxion/ekoh/views/* backend/konnaxion/ekoh/urls.py backend/konnaxion/ekoh/admin.py backend/konnaxion/ekoh/migrations/0003_kintsugi_wave1_context.py backend/konnaxion/ekoh/tests/test_kintsugi_wave1_context.py frontend/services/trust.ts frontend/app/ethikos/trust/profile/page.tsx frontend/app/ethikos/trust/badges/page.tsx frontend/app/ethikos/trust/credentials/page.tsx frontend/app/ethikos/insights/page.tsx ``` **Endpoints:** ```txt GET /api/ekoh/context-snapshots/?topic=<id> GET /api/ekoh/cohort-eligibility/?topic=<id> GET /api/ekoh/expertise-context/?user=<id> GET /api/ekoh/ethics-context/?user=<id> ``` **Tests:** - EkoH context reads do not create or mutate votes; - Smart Vote can reference EkoH snapshot IDs read-only; - trust pages load with fallback if no EkoH context exists; - visibility and privacy restrictions are enforced. **Rollback:** - remove ethiKos-facing EkoH views and serializers; - reverse context migration if added; - leave existing EkoH profile/scoring state intact. --- ### W1-050 — Drafting / rationale slice **Goal:** Add bounded drafting and rationale support without replacing deliberation, consultation, or Smart Vote ownership. **Scope:** - create draft/version/amendment/rationale packet workflow; - connect drafts to topics, argument sources, consultation snapshots, and decision records; - keep drafting inside ethiKos, not external document editing sidecars; - ensure rationale packets are traceable to argument/decision sources. **Candidate models:** ```txt Draft DraftVersion Amendment RationalePacket RationaleSourceLink ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/migrations/0005_kintsugi_wave1_drafting.py backend/konnaxion/ethikos/tests.py frontend/services/decide.ts frontend/services/deliberate.ts frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/deliberate/[topic]/page.tsx frontend/app/ethikos/admin/audit/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/drafts/?topic=<id> POST /api/ethikos/drafts/ GET /api/ethikos/draft-versions/?draft=<id> POST /api/ethikos/draft-versions/ GET /api/ethikos/amendments/?draft=<id> POST /api/ethikos/amendments/ GET /api/ethikos/rationale-packets/?topic=<id> POST /api/ethikos/rationale-packets/ ``` **Tests:** - draft versioning preserves history; - amendment state transitions are explicit; - rationale packet references are valid; - draft publication does not mutate Smart Vote readings. **Rollback:** - reverse drafting migration; - remove draft panels and service methods; - preserve existing deliberation and decision records. --- ### W1-060 — Impact / accountability slice **Goal:** Implement impact tracking and accountability views under `/ethikos/impact/*` using Kintsugi ownership rules. **Scope:** - add impact tracks linked to decisions/result snapshots; - support outcome updates and feedback loops; - avoid relying on unrelated KeenKonnect project endpoints as long-term backing; - show feedback, outcomes, and tracker pages from ethiKos/Konsultations-owned records. **Candidate models:** ```txt ImpactTrack ImpactMilestone ImpactFeedback ImpactOutcomeSnapshot ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/migrations/0006_kintsugi_wave1_impact.py backend/konnaxion/ethikos/tests.py frontend/services/impact.ts frontend/app/ethikos/impact/feedback/page.tsx frontend/app/ethikos/impact/outcomes/page.tsx frontend/app/ethikos/impact/tracker/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/impact-tracks/ POST /api/ethikos/impact-tracks/ PATCH /api/ethikos/impact-tracks/{id}/ GET /api/ethikos/impact-feedback/?track=<id> POST /api/ethikos/impact-feedback/ GET /api/ethikos/impact-outcomes/?track=<id> POST /api/ethikos/impact-outcomes/ ``` **Tests:** - impact track can link to decision/result snapshot; - status changes are auditable; - public feedback does not overwrite official outcome snapshots; - impact pages stop depending on loose non-ethiKos placeholder mappings. **Rollback:** - reverse impact migration; - revert impact service to prior placeholder behavior only if necessary; - preserve decision records and result snapshots. --- ### W1-070 — Pulse / civic health slice **Goal:** Implement civic-health and live-signal read models under `/ethikos/pulse/*` without turning Pulse into a write owner for core records. **Scope:** - expose overview, live, health, and trends pages from derived signals; - compute or store snapshot records if needed; - keep Pulse as read model / analytics, not mutation surface for Korum/Konsultations facts. **Candidate models:** ```txt PulseSignalSnapshot PulseHealthMetric PulseTrendSnapshot ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/migrations/0007_kintsugi_wave1_pulse.py backend/konnaxion/ethikos/tests.py frontend/services/pulse.ts frontend/app/ethikos/pulse/overview/page.tsx frontend/app/ethikos/pulse/live/page.tsx frontend/app/ethikos/pulse/health/page.tsx frontend/app/ethikos/pulse/trends/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/pulse/overview/ GET /api/ethikos/pulse/live/ GET /api/ethikos/pulse/health/ GET /api/ethikos/pulse/trends/ ``` **Tests:** - pulse endpoints are read-only unless snapshot generation is admin-only; - pulse calculations tolerate empty datasets; - pulse pages render fallback states. **Rollback:** - unregister pulse endpoints; - remove pulse service methods; - preserve source records. --- ### W1-080 — Insights / interpretation slice **Goal:** Make `/ethikos/insights` the comparison and interpretation surface for deliberation, decision, Smart Vote, EkoH, Pulse, and Impact outputs. **Scope:** - aggregate read-only summaries; - compare reading results, stance distributions, argument impact votes, EkoH context, pulse signals, and impact progress; - keep writes out of insights except explicit admin annotations if later approved. **Files:** ```txt backend/konnaxion/ethikos/api_views.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/ekoh/views/* frontend/services/ethikos.ts frontend/services/readings.ts frontend/services/trust.ts frontend/services/pulse.ts frontend/services/impact.ts frontend/app/ethikos/insights/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/insights/overview/ GET /api/ethikos/insights/topic/{id}/ ``` **Tests:** - insights endpoint tolerates missing Smart Vote/EkoH/Pulse/Impact data; - insights does not mutate source records; - frontend renders partial states clearly. **Rollback:** - remove insights aggregate endpoint and service calls; - keep source slice endpoints intact. --- ### W1-090 — Admin / governance slice **Goal:** Align `/ethikos/admin/*` with Kintsugi audit, moderation, and roles requirements. **Scope:** - moderate arguments, suggestions, and consultation records; - review roles and visibility; - expose audit trail entries for publications, status changes, and admin decisions; - do not create a separate admin backend outside existing Konnaxion conventions. **Candidate models:** ```txt EthikosAuditEvent ModerationAction GovernanceRoleAssignment ``` **Files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/migrations/0008_kintsugi_wave1_admin.py backend/konnaxion/ethikos/tests.py frontend/services/admin.ts frontend/app/ethikos/admin/audit/page.tsx frontend/app/ethikos/admin/moderation/page.tsx frontend/app/ethikos/admin/roles/page.tsx ``` **Endpoints:** ```txt GET /api/ethikos/admin/audit/ GET /api/ethikos/admin/moderation/ POST /api/ethikos/admin/moderation/{id}/act/ GET /api/ethikos/admin/roles/ POST /api/ethikos/admin/roles/ PATCH /api/ethikos/admin/roles/{id}/ ``` **Tests:** - moderation actions require staff/admin permission; - audit entries are append-only; - role changes are explicit and auditable; - admin pages stop relying on unmapped placeholder endpoints. **Rollback:** - remove admin Kintsugi endpoints and UI panels; - preserve historical moderation state if records exist. --- ### W1-100 — Learn / public explanation slice **Goal:** Align `/ethikos/learn/*` and methodology pages with the Kintsugi public explanation model. **Scope:** - explain Korum, Konsultations, Smart Vote, EkoH, Impact, Pulse, and Insights in user-facing language; - expose glossary, guides, changelog, and methodology content; - avoid hard-coding facts that should come from docs/services if a content source exists. **Files:** ```txt frontend/services/learn.ts frontend/app/ethikos/learn/changelog/page.tsx frontend/app/ethikos/learn/glossary/page.tsx frontend/app/ethikos/learn/guides/page.tsx frontend/app/ethikos/decide/methodology/page.tsx docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/* ``` **Endpoints:** ```txt GET /api/ethikos/learn/glossary/ GET /api/ethikos/learn/guides/ GET /api/ethikos/learn/changelog/ ``` If no backend content source is implemented in Wave 1, these pages may remain static frontend pages with clear Kintsugi wording and no misleading API calls. **Tests:** - learn pages render; - glossary includes canonical names; - no external OSS-branded route is exposed. **Rollback:** - revert wording/components; - preserve route existence. --- ### W1-110 — Test and smoke hardening slice **Goal:** Add enough backend and frontend verification to prevent Wave 1 drift. **Scope:** - backend API tests for every added ViewSet/action; - migration checks; - route reverse checks; - frontend smoke for every `/ethikos/*` route family; - anti-drift checks for forbidden routes/apps; - service import tests where supported. **Files:** ```txt backend/konnaxion/ethikos/tests.py backend/konnaxion/ethikos/tests/test_kintsugi_wave1_models.py backend/konnaxion/ethikos/tests/test_kintsugi_wave1_api.py backend/konnaxion/kollective_intelligence/tests/test_kintsugi_wave1_readings.py backend/konnaxion/ekoh/tests/test_kintsugi_wave1_context.py backend/tests/test_smoke_platform.py frontend/_e2e/ethikos-kintsugi-wave1.spec.ts frontend/_e2e/ethikos-deliberate.spec.ts frontend/_e2e/ethikos-decide.spec.ts frontend/_e2e/ethikos-impact.spec.ts frontend/services/__tests__/*.test.ts ``` **Required local commands:** ```bash cd C:\mycode\Konnaxion\Konnaxion\backend uv run python manage.py makemigrations --check --dry-run uv run python manage.py migrate --plan uv run pytest ``` ```bash cd C:\mycode\Konnaxion\Konnaxion\frontend npm run lint npm run build npm run test -- --runInBand npm run smoke ``` Use the project’s actual package manager and test commands if these differ from the repo scripts. --- ### W1-120 — Documentation, ADR, and release notes slice **Goal:** Keep the Kintsugi docs synchronized with the actual implementation. **Scope:** - update route/API contract docs after endpoints are finalized; - update data model/migration docs after migrations are created; - update payload contracts after serializers stabilize; - update frontend/backend alignment docs after services and ViewSets are complete; - add ADR entries for any tradeoff or deviation; - add final QA checklist and patch notes. **Files:** ```txt docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md ``` **Tests:** - docs reflect actual endpoint names and model names; - docs do not claim tests passed unless local output exists; - docs do not introduce forbidden routes/apps. --- ## 9. Dependency Order Recommended implementation order: ```txt 0. Foundation / no-drift baseline 1. Korum / Deliberate 2. Common-pattern cleanup after Korum 3. Konsultations / Decide 4. Smart Vote readings 5. Common-pattern cleanup after Decide + Smart Vote 6. EkoH trust/context 7. Drafting / rationale 8. Impact / accountability 9. Pulse / civic health 10. Insights / interpretation 11. Admin / governance 12. Learn / public explanation 13. Test/smoke hardening 14. Documentation/ADR/release notes ``` Korum should be first because it exercises models, migrations, serializers, ViewSets, router registration, frontend service normalization, page rendering, and no-drift rules while remaining mostly inside `konnaxion.ethikos`. --- ## 10. Common-File Conflict Notes ### 10.1 Backend common files `backend/konnaxion/ethikos/models.py` is the highest-conflict file. Each slice that adds models should use one contiguous section and avoid unrelated reordering. Recommended section order: ```txt 1. Current core models 2. Foundation constants/helpers if kept in file 3. Korum models 4. Konsultations models 5. Drafting/rationale models 6. Impact models 7. Pulse/read-model snapshot models 8. Admin/audit models ``` `backend/konnaxion/ethikos/serializers.py` should mirror model section order. `backend/konnaxion/ethikos/api_views.py` should group ViewSets by slice and keep helper methods near the top. `backend/config/api_router.py` should add registrations in a stable order and never rename existing basenames. ### 10.2 Frontend common files `frontend/services/ethikos.ts` should host only generic ethiKos API helpers. Slice-specific logic should remain in: ```txt frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/trust.ts frontend/services/admin.ts frontend/services/readings.ts ``` `frontend/app/ethikos/layout.tsx` and `frontend/app/ethikos/EthikosPageShell.tsx` should only be touched for navigation/route-label consistency. Do not introduce a second shell. --- ## 11. Anti-Drift Rules Every implementation slice MUST pass these checks: ```txt [ ] No /kialo route was created. [ ] No /kintsugi route was created. [ ] No backend/konnaxion/kialo app was created. [ ] No backend/konnaxion/kintsugi app was created. [ ] No external OSS code was imported. [ ] Existing EthikosTopic, EthikosStance, EthikosArgument, and EthikosCategory names are preserved. [ ] Existing /api/ethikos/topics/ remains stable. [ ] Existing /api/ethikos/stances/ remains stable. [ ] Existing /api/ethikos/arguments/ remains stable. [ ] Existing /api/ethikos/categories/ remains stable if currently registered. [ ] /api/home/* was not expanded for Kintsugi. [ ] Smart Vote readings are derived and do not mutate source facts. [ ] EkoH context is not treated as a voting engine. [ ] Kialo-style argument impact votes are not treated as topic stances. [ ] Kialo-style argument impact votes are not treated as Smart Vote ballots. ``` --- ## 12. Migration Policy - Use additive migrations only for Wave 1 unless a later ADR explicitly approves a breaking change. - Do not rename current ethiKos core models. - Do not remove existing fields required by current pages/tests. - Prefer nullable foreign keys and safe defaults when introducing bridge records. - Each migration should belong to a slice and be named accordingly. - Do not create all migrations before implementation slices prove the real field needs. Recommended migration sequence: ```txt 0003_kintsugi_wave1_korum.py 0004_kintsugi_wave1_konsultations.py 0005_kintsugi_wave1_drafting.py 0006_kintsugi_wave1_impact.py 0007_kintsugi_wave1_pulse.py 0008_kintsugi_wave1_admin.py ``` Kollective and EkoH migrations should use their own app migration sequences. --- ## 13. Validation Checklist ### Backend ```txt [ ] makemigrations --check --dry-run passes. [ ] migrate --plan is reviewed. [ ] pytest passes. [ ] Existing smoke platform test still passes. [ ] Existing ethiKos endpoints remain stable. [ ] New endpoints have API tests. [ ] Admin registrations import. [ ] Router basenames are stable. ``` ### Frontend ```txt [ ] TypeScript build passes. [ ] lint passes. [ ] all /ethikos/* route pages render. [ ] service imports resolve. [ ] Deliberate preview drawer no longer shows "Preview / No data" for existing topics. [ ] Decide public/elite/results pages load with canonical service calls. [ ] Trust/Pulse/Impact/Insights/Admin pages tolerate empty backend states. ``` ### Documentation ```txt [ ] Route docs match actual routes. [ ] API docs match actual endpoints. [ ] Payload docs match serializers. [ ] Migration docs match migrations. [ ] Test docs match local test output. [ ] ADR register records deviations. ``` --- ## 14. Rollback Strategy Rollback should be possible by slice. For each slice: 1. revert frontend page/service changes for that slice; 2. unregister that slice’s ViewSets from router; 3. remove or disable slice serializers/viewsets; 4. reverse that slice migration if not deployed or if data can be safely discarded; 5. if deployed with data, add a reversible deprecation migration instead of destructive deletion; 6. leave earlier slices intact. Never rollback by deleting or renaming current core ethiKos models. --- ## 15. Open Decisions These must be resolved during implementation or recorded as ADRs: ```txt [ ] Whether ConsultationBallot is separate from EthikosStance or a typed wrapper around stance. [ ] Whether DecisionProtocol belongs in ethikos or should be split after Wave 1. [ ] Whether Draft/Rationale records land before or after Smart Vote readings. [ ] Whether Insights aggregate endpoint is backend-computed or frontend-composed from slice endpoints. [ ] Whether Pulse snapshots are stored models or read-only computed endpoint responses. [ ] Whether Learn content is static frontend content or backend-managed content. [ ] Whether Admin audit uses an ethiKos-specific model or central audit infrastructure. ``` --- ## 16. Related Docs ```txt 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md ``` --- ## 17. Final Contract Wave 1 is the route-by-route strengthening of ethiKos under the existing Konnaxion architecture. ```txt Kintsugi is not a new app. Kintsugi is not a new route family. Kialo is not imported. OSS systems are inspiration sources only. Smart Vote readings are derived. EkoH provides context, not votes. Korum owns deliberation source facts. Konsultations owns consultation and accountability source facts. The implementation must land inside existing /ethikos/* and approved /api/* surfaces. ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 4c389f3135100a6fc2ff84d3a535052a3f61bdc9f4ef8ce5e0b30687bc3eead9 CONTENT_BYTES: 36049 ================================================================================================ # 24 — Wave 1 Slice Register **Document ID:** `24_WAVE1_SLICE_REGISTER.md` **Pack:** ethiKos Kintsugi Update Documentation Pack **Status:** Working implementation coordination document **Last aligned:** 2026-04-27 **Primary scope:** Existing `/ethikos/*` route family **Implementation mode:** Partial native mimic, no full external merge **Target repository path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md` --- ## 1. Purpose This document splits **ethiKos Kintsugi Wave 1** into implementation slices so that work can be generated, reviewed, tested, and merged in focused units. The slice register exists to prevent: - route drift; - API drift; - ownership drift; - repeated edits to shared files without coordination; - speculative common abstractions; - duplicate models/endpoints across slices; - accidental creation of parallel Kialo/Kintsugi applications; - accidental expansion of legacy `/api/home/*` usage. This document is **not** the implementation backlog. It is a coordination map used by the implementation backlog, patch notes, and QA checklist. --- ## 2. Canonical Variables ```yaml KINTSUGI_UPDATE_TYPE: "documentation-first architecture upgrade" IMPLEMENTATION_STYLE: "partial native mimic" FULL_EXTERNAL_MERGE_ALLOWED: false ANNEX_FIRST_PASS_ALLOWED: false EXISTING_ROUTE_FAMILIES_STABLE: true EXISTING_CORE_MODELS_STABLE: true PRIMARY_ROUTE_SURFACE: "/ethikos/*" ETHIKOS_ROUTE_FAMILIES: DECIDE: "/ethikos/decide/*" DELIBERATE: "/ethikos/deliberate/*" TRUST: "/ethikos/trust/*" PULSE: "/ethikos/pulse/*" IMPACT: "/ethikos/impact/*" LEARN: "/ethikos/learn/*" INSIGHTS: "/ethikos/insights" ADMIN: "/ethikos/admin/*" CURRENT_ETHIKOS_CORE_MODELS: - "EthikosCategory" - "EthikosTopic" - "EthikosStance" - "EthikosArgument" CURRENT_CANONICAL_ENDPOINTS: - "/api/ethikos/topics/" - "/api/ethikos/stances/" - "/api/ethikos/arguments/" - "/api/ethikos/categories/" - "/api/kollective/votes/" OWNERSHIP: KORUM: "topics, arguments, argument graph, topic-level stances, debate moderation" KONSULTATIONS: "intake, consultations, ballots, result snapshots, impact tracking" SMART_VOTE: "readings, lens declarations, derived aggregations, result publication" EKOH: "expertise context, ethics context, cohort eligibility, snapshot context" WRITE_RULES: FOREIGN_TOOLS_WRITE_CORE_TABLES: false SMART_VOTE_MUTATES_SOURCE_FACTS: false EKOH_IS_VOTING_ENGINE: false READINGS_ARE_DERIVED: true KIALO: STRATEGY: "native_mimic" ROUTE_SCOPE: "/ethikos/deliberate/*" BACKEND_SCOPE: "konnaxion.ethikos" CREATE_KIALO_BACKEND_APP: false CREATE_KIALO_FRONTEND_ROUTE: false IMPORT_KIALO_CODE: false ``` --- ## 3. Slice Strategy Wave 1 should be implemented as vertical slices plus a small number of cross-cutting coordination slices. The preferred strategy is: ```txt 1. Seed only a thin common foundation. 2. Implement vertical slices one at a time. 3. Let Korum / Deliberate become the first real reference slice. 4. Consolidate shared helpers after real slice pressure appears. 5. Keep every slice runnable and reviewable. 6. Do not prebuild the full common layer speculatively. ``` ### 3.1 Slice Types ```txt Foundation slices: - establish shared conventions and no-drift tests. Vertical product slices: - implement one route/domain owner at a time. Cross-cutting slices: - harden shared services, shared tests, shared documentation, and final QA. ``` ### 3.2 Slice Completion Rule A slice is complete only when it declares: - touched backend files; - touched frontend files; - models or migrations added; - endpoints added or changed; - frontend services added or changed; - tests added or changed; - drift checks performed; - rollback notes; - deferred items. --- ## 4. Wave 1 Slice Register | ID | Slice | Primary Owner | Primary Routes | Primary Backend Area | Status | Recommended Order | |---:|---|---|---|---|---|---:| | 00 | Foundation / No-Drift Baseline | Shared | all `/ethikos/*` | `ethikos`, router, tests, services | planned | 1 | | 01 | Korum / Deliberate | Korum | `/ethikos/deliberate/*` | `konnaxion.ethikos` | planned | 2 | | 02 | Konsultations / Decide | Konsultations | `/ethikos/decide/*` | `konnaxion.ethikos` | planned | 3 | | 03 | Smart Vote Readings | Smart Vote | `/ethikos/decide/*`, `/ethikos/insights` | `kollective_intelligence`, `ethikos` read-side | planned | 4 | | 04 | EkoH Trust / Context | EkoH | `/ethikos/trust/*`, `/ethikos/insights` | `ekoh`, read-side bridges | planned | 5 | | 05 | Drafting / Rationale | Shared: Korum + Konsultations | `/ethikos/decide/*`, `/ethikos/deliberate/*` | `konnaxion.ethikos` | planned | 6 | | 06 | Impact / Accountability | Konsultations | `/ethikos/impact/*` | `konnaxion.ethikos` | planned | 7 | | 07 | Pulse / Civic Health | Shared | `/ethikos/pulse/*` | read-side services | planned | 8 | | 08 | Insights / Interpretation | Shared | `/ethikos/insights` | `ethikos`, `kollective_intelligence`, `ekoh` read-side | planned | 9 | | 09 | Admin / Governance | Shared | `/ethikos/admin/*` | admin, permissions, audit-facing APIs | planned | 10 | | 10 | Learn / Public Explanation | Shared | `/ethikos/learn/*`, `/ethikos/decide/methodology` | docs/service-backed content where needed | planned | 11 | | 11 | Frontend Service Alignment | Shared | all frontend route families | `frontend/services/*` | planned | after 01–03 | | 12 | Backend API / Schema Alignment | Shared | all API families | serializers, viewsets, router, migrations | planned | after 01–04 | | 13 | Test / Smoke / QA Hardening | Shared | all | backend tests, frontend smoke, e2e | planned | continuous + final | | 14 | Docs / ADR / Release Notes | Shared | all | implementation docs | planned | continuous + final | --- ## 5. Slice Details ### 5.1 Slice 00 — Foundation / No-Drift Baseline **Purpose:** Establish the minimum shared foundation before any feature slice. **Primary goal:** Create reference conventions without prebuilding the full Wave 1 architecture. **Files likely touched now:** ```txt backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/serializers.py backend/config/api_router.py frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/index.ts backend/konnaxion/ethikos/tests.py docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md ``` **Do now:** - define shared constants; - define reusable permission conventions; - add no-drift tests; - normalize ethiKos service helper names; - document shared file ownership; - keep router conventions stable. **Do not do now:** - create all migrations; - add all Wave 1 models; - build Smart Vote/EkoH bridges; - rewrite shell/layout files; - create new `/kialo` or `/kintsugi` routes. **Exit criteria:** - existing `EthikosCategory`, `EthikosTopic`, `EthikosStance`, and `EthikosArgument` are preserved; - existing canonical endpoints remain registered; - no forbidden routes are registered; - shared service helper compiles conceptually with current service style; - Korum slice can use the foundation without inventing parallel patterns. --- ### 5.2 Slice 01 — Korum / Deliberate **Purpose:** Upgrade structured deliberation while staying inside existing ethiKos/Korum ownership. **Primary routes:** ```txt /ethikos/deliberate/* ``` **Primary backend APIs:** ```txt /api/ethikos/topics/ /api/ethikos/arguments/ /api/ethikos/stances/ /api/ethikos/categories/ ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0003_kintsugi_wave1_korum.py backend/konnaxion/ethikos/tests.py ``` **Likely frontend files:** ```txt frontend/services/deliberate.ts frontend/services/ethikos.ts frontend/app/ethikos/deliberate/[topic]/page.tsx frontend/app/ethikos/deliberate/elite/page.tsx frontend/app/ethikos/deliberate/guidelines/page.tsx ``` **Likely model additions:** ```txt ArgumentSource ArgumentImpactVote ArgumentSuggestion DiscussionParticipantRole DiscussionVisibilitySetting ``` **Special known issue:** ```txt Deliberate preview drawer shows "Preview / No data". ``` This should be treated as a targeted runtime/UI bug, not as a reason to redesign ethiKos architecture. **Exit criteria:** - argument tree remains based on `EthikosArgument`; - topic-level stance remains `EthikosStance`; - Kialo-style impact vote is not confused with Smart Vote ballot; - no `/kialo/*` frontend route exists; - no `konnaxion.kialo` backend app exists; - `/api/ethikos/topics/{id}/preview/` returns useful topic metadata even when argument rows are empty. --- ### 5.3 Slice 02 — Konsultations / Decide **Purpose:** Upgrade decision and consultation flows without moving ownership away from ethiKos/Konsultations. **Primary routes:** ```txt /ethikos/decide/elite /ethikos/decide/public /ethikos/decide/results /ethikos/decide/methodology ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0004_kintsugi_wave1_konsultations.py backend/konnaxion/ethikos/tests.py ``` **Likely frontend files:** ```txt frontend/services/decide.ts frontend/services/ethikos.ts frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/decide/public/page.tsx frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/decide/methodology/page.tsx ``` **Likely model areas:** ```txt consultation intake consultation status ballot capture result snapshot citizen suggestion ``` **Exit criteria:** - decide routes read/write through canonical ethiKos services; - consultation results do not bypass documented ownership; - Smart Vote derived readings remain separate from consultation source facts; - current topic/stance models are preserved. --- ### 5.4 Slice 03 — Smart Vote Readings **Purpose:** Add or align derived reading surfaces without allowing Smart Vote to mutate Korum or Konsultations source records. **Primary routes:** ```txt /ethikos/decide/results /ethikos/decide/methodology /ethikos/insights ``` **Primary backend API areas:** ```txt /api/kollective/* /api/ethikos/* read-side references ``` **Likely backend files:** ```txt backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/kollective_intelligence/admin.py backend/konnaxion/kollective_intelligence/migrations/0002_kintsugi_wave1_readings.py backend/config/api_router.py backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py ``` **Likely frontend files:** ```txt frontend/services/decide.ts frontend/services/ethikos.ts frontend/services/readings.ts frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/decide/methodology/page.tsx frontend/app/ethikos/insights/page.tsx ``` **Likely model additions:** ```txt LensDeclaration ReadingResult DecisionRecord ``` **Exit criteria:** - readings are derived artifacts; - Smart Vote does not mutate `EthikosTopic`, `EthikosArgument`, `EthikosStance`, consultation source records, or EkoH source context; - result publication is auditable; - `/api/kollective/votes/` remains stable. --- ### 5.5 Slice 04 — EkoH Trust / Context **Purpose:** Surface expertise, ethics, cohort, and snapshot context without making EkoH the voting engine. **Primary routes:** ```txt /ethikos/trust/profile /ethikos/trust/badges /ethikos/trust/credentials /ethikos/insights ``` **Likely backend files:** ```txt backend/konnaxion/ekoh/models/__init__.py backend/konnaxion/ekoh/models/audit.py backend/konnaxion/ekoh/models/config.py backend/konnaxion/ekoh/models/privacy.py backend/konnaxion/ekoh/models/scores.py backend/konnaxion/ekoh/models/taxonomy.py backend/konnaxion/ekoh/serializers/__init__.py backend/konnaxion/ekoh/serializers/profile.py backend/konnaxion/ekoh/services/contextual_analysis.py backend/konnaxion/ekoh/services/multidimensional_scoring.py backend/konnaxion/ekoh/views/__init__.py backend/konnaxion/ekoh/views/profile.py backend/konnaxion/ekoh/urls.py backend/konnaxion/ekoh/admin.py backend/config/api_router.py ``` **Likely frontend files:** ```txt frontend/services/trust.ts frontend/services/ethikos.ts frontend/app/ethikos/trust/profile/page.tsx frontend/app/ethikos/trust/badges/page.tsx frontend/app/ethikos/trust/credentials/page.tsx frontend/app/ethikos/insights/page.tsx ``` **Exit criteria:** - EkoH is shown as context, not voting authority; - privacy and visibility rules are respected; - Smart Vote may reference EkoH snapshots only through approved read-side linkage; - no EkoH write path is introduced from Korum or Konsultations flows. --- ### 5.6 Slice 05 — Drafting / Rationale **Purpose:** Add bounded drafting and rationale support after deliberation and consultation basics are stable. **Primary routes:** ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/admin/* ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0005_kintsugi_wave1_drafting.py ``` **Likely frontend files:** ```txt frontend/services/decide.ts frontend/services/deliberate.ts frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/decide/public/page.tsx frontend/app/ethikos/deliberate/[topic]/page.tsx frontend/app/ethikos/admin/moderation/page.tsx ``` **Likely model additions:** ```txt Draft DraftVersion Amendment RationalePacket ``` **Exit criteria:** - rationale traces to source objects; - draft state transitions are explicit; - draft records do not replace consultation result snapshots; - moderation/admin handling is reviewable. --- ### 5.7 Slice 06 — Impact / Accountability **Purpose:** Add accountability and impact tracking after consultation/decision state exists. **Primary routes:** ```txt /ethikos/impact/feedback /ethikos/impact/outcomes /ethikos/impact/tracker ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/config/api_router.py backend/konnaxion/ethikos/migrations/0006_kintsugi_wave1_impact.py ``` **Likely frontend files:** ```txt frontend/services/impact.ts frontend/services/ethikos.ts frontend/app/ethikos/impact/feedback/page.tsx frontend/app/ethikos/impact/outcomes/page.tsx frontend/app/ethikos/impact/tracker/page.tsx ``` **Likely model additions:** ```txt ImpactTrack OutcomeSnapshot FeedbackEntry ``` **Exit criteria:** - impact state links to decisions/consultations without rewriting them; - feedback is distinct from ballots and argument impact votes; - tracker status is auditable. --- ### 5.8 Slice 07 — Pulse / Civic Health **Purpose:** Add civic health, live signal, and trend surfaces based on existing source records and derived metrics. **Primary routes:** ```txt /ethikos/pulse/overview /ethikos/pulse/live /ethikos/pulse/health /ethikos/pulse/trends ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/serializers.py backend/config/api_router.py ``` **Likely frontend files:** ```txt frontend/services/pulse.ts frontend/services/ethikos.ts frontend/app/ethikos/pulse/overview/page.tsx frontend/app/ethikos/pulse/live/page.tsx frontend/app/ethikos/pulse/health/page.tsx frontend/app/ethikos/pulse/trends/page.tsx ``` **Exit criteria:** - pulse metrics are read-side summaries; - no pulse endpoint mutates source deliberation/decision facts; - route family remains under `/ethikos/pulse/*`. --- ### 5.9 Slice 08 — Insights / Interpretation **Purpose:** Provide cross-domain interpretation and comparison of deliberation, decision, Smart Vote, EkoH, pulse, and impact signals. **Primary route:** ```txt /ethikos/insights ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/ekoh/views/profile.py backend/config/api_router.py ``` **Likely frontend files:** ```txt frontend/services/ethikos.ts frontend/services/readings.ts frontend/services/trust.ts frontend/services/pulse.ts frontend/services/impact.ts frontend/app/ethikos/insights/page.tsx ``` **Exit criteria:** - insights are read-side and explanatory; - Smart Vote readings are labelled as derived; - EkoH context is labelled as contextual; - source routes remain canonical. --- ### 5.10 Slice 09 — Admin / Governance **Purpose:** Align audit, moderation, and roles pages with Kintsugi governance boundaries. **Primary routes:** ```txt /ethikos/admin/audit /ethikos/admin/moderation /ethikos/admin/roles ``` **Likely backend files:** ```txt backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/serializers.py backend/config/api_router.py ``` **Likely frontend files:** ```txt frontend/services/admin.ts frontend/services/ethikos.ts frontend/app/ethikos/admin/audit/page.tsx frontend/app/ethikos/admin/moderation/page.tsx frontend/app/ethikos/admin/roles/page.tsx ``` **Exit criteria:** - moderation controls do not bypass ownership rules; - role changes are auditable; - admin endpoints do not become broad generic backdoors; - admin service calls do not remain unmapped if backend support is added. --- ### 5.11 Slice 10 — Learn / Public Explanation **Purpose:** Explain methodology, glossary, guides, and changelog for the upgraded system. **Primary routes:** ```txt /ethikos/learn/changelog /ethikos/learn/glossary /ethikos/learn/guides /ethikos/decide/methodology ``` **Likely frontend files:** ```txt frontend/services/learn.ts frontend/app/ethikos/learn/changelog/page.tsx frontend/app/ethikos/learn/glossary/page.tsx frontend/app/ethikos/learn/guides/page.tsx frontend/app/ethikos/decide/methodology/page.tsx ``` **Likely docs files:** ```txt docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/26_WAVE1_PATCH_NOTES.md ``` **Exit criteria:** - public explanation matches actual implemented behavior; - methodology text distinguishes Korum, Konsultations, Smart Vote, and EkoH; - no route or endpoint promise is documented unless implemented or clearly marked deferred. --- ### 5.12 Slice 11 — Frontend Service Alignment **Purpose:** Align the frontend service layer after initial vertical slices reveal real shared patterns. **Likely files:** ```txt frontend/api.ts frontend/services/index.ts frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/learn.ts frontend/services/admin.ts frontend/services/readings.ts frontend/services/trust.ts ``` **Exit criteria:** - services own API access; - page files do not duplicate raw fetch logic unnecessarily; - `/api/home/*` is not expanded; - service methods map to canonical backend endpoints; - frontend types match serializer payloads. --- ### 5.13 Slice 12 — Backend API / Schema Alignment **Purpose:** Consolidate backend models, serializers, viewsets, routers, permissions, admin, and migrations after several slices have produced real code. **Likely files:** ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/urls.py backend/konnaxion/ethikos/admin.py backend/config/api_router.py backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/ekoh/views/profile.py ``` **Exit criteria:** - model names remain canonical; - serializer fields match payload contracts; - router basenames are stable; - migration history is linear and reviewable; - app boundaries remain intact. --- ### 5.14 Slice 13 — Test / Smoke / QA Hardening **Purpose:** Make the whole Wave 1 patch set verifiable. **Likely backend files:** ```txt backend/konnaxion/ethikos/tests.py backend/konnaxion/ethikos/tests/ backend/konnaxion/kollective_intelligence/tests/ backend/konnaxion/ekoh/tests/ ``` **Likely frontend files:** ```txt frontend/_e2e/ethikos-kintsugi-wave1.spec.ts frontend/_e2e/ethikos-deliberate.spec.ts frontend/_e2e/ethikos-decide.spec.ts frontend/_e2e/ethikos-impact.spec.ts frontend/_e2e/ethikos-admin.spec.ts ``` **Minimum checks:** ```txt backend model preservation backend endpoint availability forbidden route absence forbidden app absence frontend route smoke service endpoint mapping migration sanity Smart Vote source mutation prohibition EkoH voting-engine prohibition Kialo native-mimic boundary ``` **Exit criteria:** - all backend tests pass locally; - frontend build succeeds locally; - e2e/smoke tests pass locally or are explicitly marked pending with reason; - QA checklist is updated. --- ### 5.15 Slice 14 — Docs / ADR / Release Notes **Purpose:** Keep implementation documentation aligned with actual code. **Likely docs files:** ```txt docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/26_WAVE1_PATCH_NOTES.md ``` **Exit criteria:** - every implemented endpoint is documented; - every schema change is documented; - every deferred item is visible; - rollback notes are present; - ADRs capture decisions that affect multiple slices. --- ## 6. Files Common to More Than One Slice ### 6.1 Highest-Conflict Shared Backend Files These files are common to many slices and must be edited deliberately. ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py ``` Used by: ```txt Slice 00 — Foundation / No-Drift Baseline Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 05 — Drafting / Rationale Slice 06 — Impact / Accountability Slice 07 — Pulse / Civic Health Slice 08 — Insights / Interpretation Slice 09 — Admin / Governance Slice 12 — Backend API / Schema Alignment Slice 13 — Test / Smoke / QA Hardening ``` **Rule:** avoid speculative generalization. Add only what the active slice needs, then consolidate after real duplication appears. --- ### 6.2 Shared Backend Foundation Files ```txt backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py ``` Used by: ```txt Slice 00 — Foundation / No-Drift Baseline Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 05 — Drafting / Rationale Slice 06 — Impact / Accountability Slice 09 — Admin / Governance Slice 12 — Backend API / Schema Alignment Slice 13 — Test / Smoke / QA Hardening ``` **Rule:** keep these small. Prefer simple constants and permissions. Do not turn them into a hidden framework. --- ### 6.3 Shared Migration Files Likely migration files: ```txt backend/konnaxion/ethikos/migrations/0003_kintsugi_wave1_korum.py backend/konnaxion/ethikos/migrations/0004_kintsugi_wave1_konsultations.py backend/konnaxion/ethikos/migrations/0005_kintsugi_wave1_drafting.py backend/konnaxion/ethikos/migrations/0006_kintsugi_wave1_impact.py backend/konnaxion/kollective_intelligence/migrations/0002_kintsugi_wave1_readings.py backend/konnaxion/ekoh/migrations/0003_kintsugi_wave1_context.py ``` Used by: ```txt Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 04 — EkoH Trust / Context Slice 05 — Drafting / Rationale Slice 06 — Impact / Accountability Slice 12 — Backend API / Schema Alignment Slice 13 — Test / Smoke / QA Hardening ``` **Rule:** migrations should be created only when the slice introduces real schema changes. Do not create all migrations during foundation. --- ### 6.4 Shared Frontend Service Files ```txt frontend/api.ts frontend/services/index.ts frontend/services/ethikos.ts frontend/services/deliberate.ts frontend/services/decide.ts frontend/services/impact.ts frontend/services/pulse.ts frontend/services/learn.ts frontend/services/admin.ts frontend/services/readings.ts frontend/services/trust.ts ``` Used by: ```txt Slice 00 — Foundation / No-Drift Baseline Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 04 — EkoH Trust / Context Slice 06 — Impact / Accountability Slice 07 — Pulse / Civic Health Slice 08 — Insights / Interpretation Slice 09 — Admin / Governance Slice 10 — Learn / Public Explanation Slice 11 — Frontend Service Alignment Slice 13 — Test / Smoke / QA Hardening ``` **Rule:** services are the API access boundary. Route pages should not each invent their own backend mapping. --- ### 6.5 Shared ethiKos Shell Files Usually avoid modifying these unless navigation or route-shell consistency blocks multiple slices. ```txt frontend/app/ethikos/layout.tsx frontend/app/ethikos/EthikosPageShell.tsx ``` Used by: ```txt all frontend slices ``` **Rule:** do not create a second shell, theme system, `/kialo`, or `/kintsugi` shell. --- ### 6.6 Shared Cross-Slice Frontend Pages ```txt frontend/app/ethikos/deliberate/[topic]/page.tsx ``` Used by: ```txt Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 05 — Drafting / Rationale Slice 09 — Admin / Governance ``` ```txt frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/decide/public/page.tsx frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/decide/methodology/page.tsx ``` Used by: ```txt Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 04 — EkoH Trust / Context Slice 05 — Drafting / Rationale Slice 08 — Insights / Interpretation Slice 10 — Learn / Public Explanation ``` ```txt frontend/app/ethikos/insights/page.tsx ``` Used by: ```txt Slice 03 — Smart Vote Readings Slice 04 — EkoH Trust / Context Slice 07 — Pulse / Civic Health Slice 08 — Insights / Interpretation Slice 06 — Impact / Accountability ``` ```txt frontend/app/ethikos/admin/audit/page.tsx frontend/app/ethikos/admin/moderation/page.tsx frontend/app/ethikos/admin/roles/page.tsx ``` Used by: ```txt Slice 01 — Korum / Deliberate Slice 02 — Konsultations / Decide Slice 03 — Smart Vote Readings Slice 04 — EkoH Trust / Context Slice 06 — Impact / Accountability Slice 09 — Admin / Governance ``` --- ### 6.7 Shared Smart Vote Files ```txt backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/kollective_intelligence/admin.py ``` Used by: ```txt Slice 03 — Smart Vote Readings Slice 08 — Insights / Interpretation Slice 13 — Test / Smoke / QA Hardening ``` Possible read-side coordination with: ```txt Slice 02 — Konsultations / Decide Slice 04 — EkoH Trust / Context ``` **Rule:** Smart Vote owns derived readings and result publication. It must not mutate source facts. --- ### 6.8 Shared EkoH Files ```txt backend/konnaxion/ekoh/models/* backend/konnaxion/ekoh/serializers/* backend/konnaxion/ekoh/services/* backend/konnaxion/ekoh/views/* backend/konnaxion/ekoh/urls.py backend/konnaxion/ekoh/admin.py ``` Used by: ```txt Slice 04 — EkoH Trust / Context Slice 08 — Insights / Interpretation Slice 13 — Test / Smoke / QA Hardening ``` Possible read-side coordination with: ```txt Slice 03 — Smart Vote Readings Slice 02 — Konsultations / Decide Slice 09 — Admin / Governance ``` **Rule:** EkoH supplies expertise, ethics, cohort, and snapshot context. It is not the voting engine. --- ### 6.9 Shared Test Files ```txt backend/konnaxion/ethikos/tests.py backend/konnaxion/ethikos/tests/ backend/konnaxion/kollective_intelligence/tests/ backend/konnaxion/ekoh/tests/ frontend/_e2e/ethikos-kintsugi-wave1.spec.ts frontend/_e2e/ethikos-deliberate.spec.ts frontend/_e2e/ethikos-decide.spec.ts frontend/_e2e/ethikos-impact.spec.ts frontend/_e2e/ethikos-admin.spec.ts ``` Used by: ```txt all slices ``` **Rule:** test names should declare the slice and invariant under test. --- ### 6.10 Shared Documentation Files ```txt docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/07_API_AND_SERVICE_CONTRACTS.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/08_DATA_MODEL_AND_MIGRATION_PLAN.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/09_SMART_VOTE_EKOH_READING_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/14_FRONTEND_ALIGNMENT_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/15_BACKEND_ALIGNMENT_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/16_TEST_AND_SMOKE_CONTRACT.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/18_ADR_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/23_WAVE1_IMPLEMENTATION_BACKLOG.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/24_WAVE1_SLICE_REGISTER.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/26_WAVE1_PATCH_NOTES.md ``` Used by: ```txt all slices that add endpoints, models, payloads, services, tests, route behavior, or ADR-worthy decisions ``` --- ## 7. Recommended Implementation Order ```txt 00. Foundation / No-Drift Baseline 01. Korum / Deliberate 11. Frontend Service Alignment, light pass 12. Backend API / Schema Alignment, light pass 02. Konsultations / Decide 03. Smart Vote Readings 12. Backend API / Schema Alignment, second pass 04. EkoH Trust / Context 05. Drafting / Rationale 06. Impact / Accountability 07. Pulse / Civic Health 08. Insights / Interpretation 09. Admin / Governance 10. Learn / Public Explanation 13. Test / Smoke / QA Hardening 14. Docs / ADR / Release Notes ``` ### 7.1 Why Korum Comes First Korum / Deliberate is the best first vertical reference slice because it exercises: - current ethiKos models; - current ethiKos API routes; - serializer/viewset/router conventions; - frontend service conventions; - route-page integration; - moderation boundaries; - native-mimic rules; - Kialo-style mapping without importing Kialo code. It also contains the known preview bug and therefore provides an immediate test of the foundation layer. --- ## 8. Shared-File Editing Protocol Before modifying a shared file, the active slice must record: ```yaml shared_file_edit: slice_id: "" file: "" reason: "" adds_model: false adds_endpoint: false adds_serializer: false adds_frontend_service: false affects_existing_route: false affects_existing_payload: false migration_required: false tests_required: - "" rollback_note: "" ``` ### 8.1 Shared-File Rules ```txt 1. Do not rename existing ethiKos core models. 2. Do not move ethiKos functionality to a new backend app. 3. Do not create Kialo or Kintsugi routes. 4. Do not expand /api/home/*. 5. Do not let Smart Vote mutate source facts. 6. Do not treat EkoH as a voting engine. 7. Do not mix argument impact votes with topic-level stances. 8. Do not add frontend raw fetches when a service wrapper exists or should exist. 9. Do not add migrations without tests and rollback notes. 10. Do not create generic abstractions before two slices prove the same need. ``` --- ## 9. Slice Handoff Template Each slice handoff should use this template. ```markdown # Slice Handoff — <ID> <Name> ## Scope ## Files Modified ## Files Created ## Models Added or Changed ## Endpoints Added or Changed ## Frontend Services Added or Changed ## Frontend Routes Added or Changed ## Tests Added or Changed ## Shared Files Touched ## Drift Checks - [ ] no `/kialo/*` - [ ] no `/kintsugi/*` - [ ] no `konnaxion.kialo` - [ ] no `/api/home/*` expansion - [ ] existing ethiKos models preserved - [ ] existing canonical endpoints preserved - [ ] Smart Vote source mutation prohibition preserved - [ ] EkoH voting-engine prohibition preserved ## Rollback Notes ## Deferred Items ``` --- ## 10. Drift-Control Checklist for This Register ```txt [ ] Targets /ethikos/* only. [ ] Maps work to Decide, Deliberate, Trust, Pulse, Impact, Learn, Insights, and Admin. [ ] Preserves konnaxion.ethikos as primary ethiKos backend app. [ ] Avoids creating konnaxion.kialo. [ ] Avoids creating /kialo or /kintsugi frontend routes. [ ] Preserves EthikosCategory, EthikosTopic, EthikosStance, and EthikosArgument. [ ] Preserves /api/ethikos/topics/, /stances/, /arguments/, /categories/. [ ] Preserves /api/kollective/votes/. [ ] Keeps Smart Vote readings derived. [ ] Keeps EkoH contextual. [ ] Separates Kialo-style argument impact votes from topic-level stances. [ ] Treats this document as a slice coordination register, not a full task backlog. ``` --- ## 11. Related Docs ```txt 00_KINTSUGI_START_HERE.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md 23_WAVE1_IMPLEMENTATION_BACKLOG.md 25_WAVE1_QA_CHECKLIST.md ``` --- ## 12. Final Contract ```txt Wave 1 is all implementation work included by DocKintsugi_Kompendio.txt. Wave 1 must be split into focused slices. The Korum slice is the preferred first vertical reference slice. Common files should be seeded lightly, expanded only when a slice needs them, and consolidated after real code exists. Kintsugi is not a new app. Kintsugi is not a new route family. Kintsugi is the route-by-route strengthening of ethiKos. ``` ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: ec3cc9296943ce7ebfb4cffc17f92206d1dda4cea7340f52064ed910602e3020 CONTENT_BYTES: 30121 ================================================================================================ # 25 — Wave 1 QA Checklist **Project:** Konnaxion **Module:** ethiKos **Upgrade:** Kintsugi **Document ID:** `25_WAVE1_QA_CHECKLIST.md` **Target path:** `docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/25_WAVE1_QA_CHECKLIST.md` **Status:** Working QA checklist **Generated:** 2026-04-27 **Audience:** maintainers, QA reviewers, backend/frontend developers, AI coding agents --- ## 1. Purpose This document defines the QA gates for the **ethiKos Kintsugi Wave 1** implementation. Wave 1 QA must confirm that the implementation: - preserves the existing `/ethikos/*` route family; - preserves the existing `/api/ethikos/*` and `/api/kollective/*` API center of gravity; - does not introduce `/api/kialo/*`, `/api/kintsugi/*`, `/api/deliberation/*`, or expanded `/api/home/*` behavior; - keeps current ethiKos model names intact; - separates source facts from derived readings; - keeps Kialo-style work inside Korum / Deliberate; - keeps Smart Vote as derived readings, not source mutation; - keeps EkoH as context, not the voting engine; - validates every slice with backend, frontend, no-drift, smoke, and documentation checks. This checklist is not an implementation backlog. It is the acceptance and verification companion for Wave 1 work. --- ## 2. Source documents to check before QA sign-off QA reviewers must verify the implementation against these contracts: ```txt 00_KINTSUGI_START_HERE.md 01_ETHIKOS_KINTSUGI_EXECUTION_STRATEGY.md 02_SOURCE_OF_TRUTH_AND_DRIFT_CONTROL.md 03_BOUNDARIES_AND_OWNERSHIP_CONTRACTS.md 04_CANONICAL_NAMING_AND_VARIABLES.md 05_CURRENT_STATE_BASELINE.md 06_ROUTE_BY_ROUTE_ETHIKOS_UPGRADE_PLAN.md 07_API_AND_SERVICE_CONTRACTS.md 08_DATA_MODEL_AND_MIGRATION_PLAN.md 09_SMART_VOTE_EKOH_READING_CONTRACT.md 10_FIRST_PASS_INTEGRATION_MATRIX.md 11_MIMIC_VS_ANNEX_RULEBOOK.md 12_CANONICAL_OBJECTS_AND_EVENTS.md 13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md 14_FRONTEND_ALIGNMENT_CONTRACT.md 15_BACKEND_ALIGNMENT_CONTRACT.md 16_TEST_AND_SMOKE_CONTRACT.md 17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md 18_ADR_REGISTER.md 19_OSS_CODE_READING_PLAN.md 20_AI_GENERATION_GUARDRAILS.md 21_KIALO_STYLE_ARGUMENT_MAPPING_CONTRACT.md 22_IMPLEMENTATION_BACKLOG_TEMPLATE.md 23_WAVE1_IMPLEMENTATION_BACKLOG.md 24_WAVE1_SLICE_REGISTER.md 25_WAVE1_QA_CHECKLIST.md ``` If any QA question conflicts with the current code snapshot, use the code snapshot for implementation reality and the boundary contracts for ownership/write-rule validation. --- ## 3. Status legend Use these markers in review notes: ```txt [ ] Not checked [x] Passed [~] Partially passed / needs follow-up [!] Failed / blocks merge [-] Not applicable to this slice ``` Every `[~]` or `[!]` item must include: ```txt owner: file(s): failure: required fix: retest command: ``` --- ## 4. Global Wave 1 release gates ### G0 — Scope gate - [ ] Wave 1 work maps to `DocKintsugi_Kompendio.txt`. - [ ] Each change maps to an approved slice in `24_WAVE1_SLICE_REGISTER.md`. - [ ] No work creates a foreign OSS app. - [ ] No work introduces an annex/sidecar implementation. - [ ] No work creates `/kialo`, `/kintsugi`, or external civic-tech route families. - [ ] No work expands `/api/home/*` as a future ethiKos API. - [ ] No work replaces existing ethiKos routes. - [ ] No work replaces existing ethiKos models. - [ ] No work treats first-pass OSS docs as importable source code. - [ ] Any waived OSS code-reading requirement is documented. ### G1 — Source-of-truth gate - [ ] `EthikosTopic` remains the topic/debate/consultation container. - [ ] `EthikosStance` remains topic-level stance. - [ ] `EthikosArgument` remains argument/thread/claim-equivalent object. - [ ] `ArgumentImpactVote` is not treated as `EthikosStance`. - [ ] `ReadingResult` is not treated as a source fact. - [ ] Weighted values are stored/displayed as derived artifacts only. - [ ] Baseline/raw results remain visible when readings are displayed. - [ ] Smart Vote does not mutate Korum records. - [ ] Smart Vote does not mutate Konsultations records. - [ ] EkoH does not mutate votes, stances, ballots, or arguments. - [ ] EkoH is never presented as the voting engine. ### G2 — Route/API gate - [ ] Existing `/ethikos/*` frontend route family remains intact. - [ ] Existing `/api/ethikos/topics/` remains intact. - [ ] Existing `/api/ethikos/stances/` remains intact. - [ ] Existing `/api/ethikos/arguments/` remains intact. - [ ] Existing `/api/ethikos/categories/` remains intact where available. - [ ] Existing `/api/kollective/votes/` remains intact. - [ ] Existing `/api/kollective/vote-results/` remains intact where available. - [ ] New Kintsugi endpoints, if any, are registered under approved namespaces only. - [ ] No `/api/kialo/*` endpoint exists. - [ ] No `/api/kintsugi/*` endpoint exists. - [ ] No `/api/deliberation/*` endpoint exists. - [ ] No new page-level raw fetch is introduced for Kintsugi work when a service wrapper should own the call. - [ ] Router basenames are stable and documented. ### G3 — Migration gate - [ ] All schema changes have migrations. - [ ] No destructive rename of existing ethiKos core models. - [ ] No destructive migration of existing topic/stance/argument data. - [ ] New models are additive. - [ ] New nullable fields are safe for existing data. - [ ] New indexes/constraints are justified. - [ ] Migration names are slice-specific and ordered. - [ ] Rollback implications are documented. - [ ] `makemigrations --check --dry-run` passes after migration files are committed. - [ ] `migrate --plan` is reviewed. ### G4 — Backend API/test gate - [ ] All new serializers define read-only fields correctly. - [ ] User/owner fields are injected from request context where appropriate. - [ ] Normal users cannot set moderation fields. - [ ] Normal users cannot assign roles. - [ ] Normal users cannot publish readings. - [ ] Admin/moderator-only actions are protected. - [ ] System/compute-only actions are protected or explicitly internal. - [ ] API list responses handle both empty and populated states. - [ ] Detail endpoints return stable payload shapes. - [ ] Validation errors are explicit. - [ ] Not-found responses are handled. - [ ] Permission-denied responses are handled. - [ ] Backend tests cover happy path. - [ ] Backend tests cover invalid payloads. - [ ] Backend tests cover permissions. - [ ] Backend tests cover no-drift invariants. ### G5 — Frontend service/UI gate - [ ] Frontend service wrappers exist for every new API call. - [ ] Services normalize paginated and non-paginated responses where needed. - [ ] Services expose typed payloads. - [ ] Pages do not duplicate service-layer URL construction. - [ ] Pages show loading states. - [ ] Pages show empty states. - [ ] Pages show error states. - [ ] Pages do not crash on partial backend data. - [ ] Pages do not assume unbuilt endpoints are present. - [ ] Route pages remain inside existing `/ethikos/*` shell. - [ ] No second ethiKos shell is introduced. - [ ] No second theme system is introduced. ### G6 — Smoke gate - [ ] Frontend app starts locally. - [ ] Backend app starts locally. - [ ] Existing ethiKos pages load. - [ ] Existing Korum/Deliberate pages load. - [ ] Existing Decide pages load. - [ ] Existing Trust pages load. - [ ] Existing Impact pages load. - [ ] Existing Pulse pages load. - [ ] Existing Learn pages load. - [ ] Existing Insights page loads. - [ ] Existing Admin pages load. - [ ] New Wave 1 UI controls do not block page render when backend data is empty. - [ ] Browser console has no new fatal runtime error on primary QA routes. ### G7 — Documentation gate - [ ] `23_WAVE1_IMPLEMENTATION_BACKLOG.md` is updated with final task status. - [ ] `24_WAVE1_SLICE_REGISTER.md` is updated with final slice status. - [ ] `25_WAVE1_QA_CHECKLIST.md` is updated with QA results. - [ ] Any ADR-relevant decision is reflected in `18_ADR_REGISTER.md`. - [ ] Any payload change is reflected in `13_PAYLOAD_SHAPES_AND_SERIALIZER_CONTRACTS.md`. - [ ] Any API change is reflected in `07_API_AND_SERVICE_CONTRACTS.md`. - [ ] Any frontend service pattern change is reflected in `14_FRONTEND_ALIGNMENT_CONTRACT.md`. - [ ] Any backend alignment decision is reflected in `15_BACKEND_ALIGNMENT_CONTRACT.md`. - [ ] Any known unresolved issue is reflected in `17_KNOWN_BUGS_AND_NON_KINTSUGI_ITEMS.md`. ### G8 — Rollback gate - [ ] Backend rollback plan exists. - [ ] Frontend rollback plan exists. - [ ] Migration rollback risk is documented. - [ ] Feature toggles or safe fallbacks exist where needed. - [ ] Existing routes continue to function if new data is absent. - [ ] Existing API consumers remain compatible. - [ ] No irreversible data migration is included without explicit approval. ### G9 — Final sign-off gate - [ ] All blocking QA failures are closed. - [ ] All accepted partial failures have owners and follow-up tasks. - [ ] All required tests are run or explicitly marked not runnable in current environment. - [ ] Manual smoke notes are attached. - [ ] Reviewer confirms no ownership drift. - [ ] Reviewer confirms no route drift. - [ ] Reviewer confirms no source-fact/derived-reading confusion. - [ ] Reviewer confirms no direct OSS import. - [ ] Maintainer approves Wave 1 release. --- ## 5. Slice QA matrix ### 5.1 Foundation / no-drift baseline Files typically involved: ```txt backend/konnaxion/ethikos/constants.py backend/konnaxion/ethikos/permissions.py backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/urls.py backend/config/api_router.py frontend/services/ethikos.ts frontend/services/index.ts frontend/api.ts ``` Checklist: - [ ] Shared constants do not rename canonical models. - [ ] Shared permission helpers do not weaken existing permissions. - [ ] Router style remains DRF-compatible. - [ ] Service helpers use the existing frontend request pattern. - [ ] No new feature behavior is introduced outside slice needs. - [ ] Existing API route tests still pass. - [ ] Existing frontend services still import correctly. ### 5.2 Korum / Deliberate Routes/API: ```txt /ethikos/deliberate/* /api/ethikos/topics/ /api/ethikos/arguments/ /api/ethikos/stances/ /api/ethikos/categories/ ``` Likely files: ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/migrations/* backend/konnaxion/ethikos/tests.py frontend/services/deliberate.ts frontend/services/ethikos.ts frontend/app/ethikos/deliberate/[topic]/page.tsx frontend/app/ethikos/deliberate/elite/page.tsx frontend/app/ethikos/deliberate/guidelines/page.tsx ``` Checklist: - [ ] Argument tree renders with root and child arguments. - [ ] Argument source data is stored/displayed only as argument metadata. - [ ] Argument impact votes are argument-level only. - [ ] Argument impact votes do not change topic stance. - [ ] Argument suggestions have clear pending/accepted/rejected states. - [ ] Participant roles do not reveal anonymous/private identities. - [ ] Visibility settings do not expose hidden arguments to unauthorized users. - [ ] Preview endpoint returns topic metadata when topic exists. - [ ] Preview endpoint handles empty argument lists. - [ ] Preview drawer no longer shows `Preview / No data` for valid topics. - [ ] Hidden arguments are excluded or marked according to permission. - [ ] Normal users cannot moderate arguments. - [ ] Admin/moderator can hide/unhide where authorized. - [ ] Kialo-style labels remain conceptual; no model rename to `Claim`. - [ ] No `/kialo` route or backend app is created. ### 5.3 Konsultations / Decide Routes/API: ```txt /ethikos/decide/* /api/ethikos/topics/ /api/ethikos/stances/ ``` Likely files: ```txt backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/ethikos/migrations/* frontend/services/decide.ts frontend/app/ethikos/decide/public/page.tsx frontend/app/ethikos/decide/elite/page.tsx frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/decide/methodology/page.tsx ``` Checklist: - [ ] Public participation flow uses existing ethiKos topic/stance semantics. - [ ] Elite participation flow uses existing ethiKos topic/stance semantics. - [ ] Ballot-like behavior does not rename `EthikosStance`. - [ ] Results distinguish raw baseline counts from derived readings. - [ ] Empty consultation result state is handled. - [ ] Invalid consultation id is handled. - [ ] Duplicate user stance behavior is defined and tested. - [ ] Public and elite result views do not leak restricted context. - [ ] Methodology page explains baseline vs weighted/derived readings. - [ ] Decide pages do not call `/api/home/*` for new Kintsugi decision data. ### 5.4 Smart Vote readings Routes/API: ```txt /ethikos/decide/results /ethikos/insights /api/kollective/* /api/ethikos/* ``` Likely files: ```txt backend/konnaxion/kollective_intelligence/models.py backend/konnaxion/kollective_intelligence/serializers.py backend/konnaxion/kollective_intelligence/api_views.py backend/konnaxion/kollective_intelligence/admin.py backend/konnaxion/kollective_intelligence/migrations/* backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py frontend/services/decide.ts frontend/services/ethikos.ts frontend/app/ethikos/decide/results/page.tsx frontend/app/ethikos/insights/page.tsx ``` Checklist: - [ ] Baseline result exists or is explicitly unavailable. - [ ] Baseline result is raw and unweighted. - [ ] Baseline remains visible when readings are shown. - [ ] Every non-baseline reading has a lens declaration. - [ ] Every non-baseline reading has a stable `lens_hash`. - [ ] Every EkoH-derived reading has a `snapshot_ref`. - [ ] Reading payload stores `computed_at`. - [ ] Reading payload stores source event counts. - [ ] Reading payload stores result payload. - [ ] Reading payload stores audit payload. - [ ] Published readings are not silently recomputed in place. - [ ] Smart Vote does not mutate Korum records. - [ ] Smart Vote does not mutate Konsultations records. - [ ] Weighted values are clearly displayed as derived. - [ ] Individual private EkoH scores are not exposed publicly. - [ ] Tests prove `ReadingResult` is not treated as a source fact. ### 5.5 EkoH trust/context Routes/API: ```txt /ethikos/trust/* /ethikos/insights EkoH context APIs ``` Likely files: ```txt backend/konnaxion/ekoh/models/* backend/konnaxion/ekoh/serializers/* backend/konnaxion/ekoh/services/* backend/konnaxion/ekoh/views/* backend/konnaxion/ekoh/urls.py backend/konnaxion/ekoh/admin.py frontend/app/ethikos/trust/profile/page.tsx frontend/app/ethikos/trust/badges/page.tsx frontend/app/ethikos/trust/credentials/page.tsx frontend/app/ethikos/insights/page.tsx frontend/services/trust.ts frontend/services/ethikos.ts ``` Checklist: - [ ] EkoH is used as context only. - [ ] EkoH does not mutate votes. - [ ] EkoH does not mutate stances. - [ ] EkoH does not mutate ballots. - [ ] EkoH does not mutate arguments. - [ ] EkoH is not presented as the voting engine. - [ ] Public pages do not expose private EkoH scores. - [ ] Trust badges/credentials are clearly contextual signals. - [ ] Any EkoH snapshot reference used in readings is auditable. - [ ] Empty trust/context state is handled. - [ ] Restricted trust/context data is permission-checked. ### 5.6 Drafting / rationale Routes/API: ```txt /ethikos/decide/* /ethikos/deliberate/* /ethikos/admin/* /api/ethikos/* ``` Checklist: - [ ] Draft entities are not treated as final decisions. - [ ] Draft versions preserve history. - [ ] Amendments are linked to the correct draft/version. - [ ] Rationale packets cite source facts/readings without mutating them. - [ ] Drafting does not overwrite Korum argument source facts. - [ ] Drafting does not overwrite Konsultations results. - [ ] Admin controls are permission-checked. - [ ] Frontend distinguishes draft, proposed, accepted, published, archived states. ### 5.7 Impact / accountability Routes/API: ```txt /ethikos/impact/* /api/ethikos/* ``` Likely files: ```txt frontend/services/impact.ts frontend/app/ethikos/impact/feedback/page.tsx frontend/app/ethikos/impact/outcomes/page.tsx frontend/app/ethikos/impact/tracker/page.tsx backend/konnaxion/ethikos/models.py backend/konnaxion/ethikos/serializers.py backend/konnaxion/ethikos/api_views.py ``` Checklist: - [ ] Impact records do not make KeenKonnect projects the source of civic truth. - [ ] Impact tracker links to approved decision/consultation records. - [ ] Feedback submission uses approved ethiKos endpoints. - [ ] Outcomes distinguish claimed, observed, verified, and archived states. - [ ] Empty impact state is handled. - [ ] Unauthorized users cannot change impact verification state. - [ ] Rollback preserves existing feedback behavior. ### 5.8 Pulse / civic health Routes/API: ```txt /ethikos/pulse/* /api/ethikos/* /api/kollective/* ``` Likely files: ```txt frontend/services/pulse.ts frontend/app/ethikos/pulse/overview/page.tsx frontend/app/ethikos/pulse/live/page.tsx frontend/app/ethikos/pulse/health/page.tsx frontend/app/ethikos/pulse/trends/page.tsx ``` Checklist: - [ ] Pulse indicators are projections, not source facts. - [ ] Pulse does not mutate topics, stances, arguments, ballots, or readings. - [ ] Live view degrades safely without realtime support. - [ ] Health view explains metric source. - [ ] Trends view handles empty history. - [ ] No WebSocket/realtime rewrite is introduced without later contract. - [ ] No GraphQL rewrite is introduced. ### 5.9 Learn / public explanation Routes/API: ```txt /ethikos/learn/* /ethikos/decide/methodology ``` Likely files: ```txt frontend/services/learn.ts frontend/app/ethikos/learn/changelog/page.tsx frontend/app/ethikos/learn/glossary/page.tsx frontend/app/ethikos/learn/guides/page.tsx frontend/app/ethikos/decide/methodology/page.tsx ``` Checklist: - [ ] Glossary preserves canonical current model names. - [ ] Guides explain Kialo terms as conceptual mappings only. - [ ] Guides explain baseline vs derived Smart Vote readings. - [ ] Guides explain EkoH as context only. - [ ] Changelog records Wave 1 changes. - [ ] Learn pages do not claim unbuilt features are live. - [ ] Learn pages do not introduce unsupported route names. ### 5.10 Insights / interpretation Routes/API: ```txt /ethikos/insights /api/ethikos/* /api/kollective/* EkoH context APIs ``` Checklist: - [ ] Insights distinguish facts, projections, and readings. - [ ] Insights shows baseline where weighted readings are displayed. - [ ] Insights does not expose private EkoH scores. - [ ] Insights handles unavailable readings. - [ ] Insights handles unavailable EkoH context. - [ ] Insights does not recompute published readings client-side. - [ ] Insights links each derived result to its lens/snapshot/audit context when available. ### 5.11 Admin / governance Routes/API: ```txt /ethikos/admin/* /api/ethikos/* /api/kollective/* EkoH context APIs ``` Likely files: ```txt frontend/services/admin.ts frontend/app/ethikos/admin/audit/page.tsx frontend/app/ethikos/admin/moderation/page.tsx frontend/app/ethikos/admin/roles/page.tsx backend/konnaxion/ethikos/admin.py backend/konnaxion/ethikos/api_views.py backend/konnaxion/kollective_intelligence/admin.py backend/konnaxion/ekoh/admin.py ``` Checklist: - [ ] Audit page distinguishes source events from derived reading events. - [ ] Moderation page can review/hide/unhide only authorized entities. - [ ] Role page cannot be used by normal users. - [ ] Role changes are auditable. - [ ] Reading publication/invalidation is restricted. - [ ] EkoH context controls do not mutate votes/stances/ballots. - [ ] Admin services do not use unmapped placeholder endpoints without fallback. - [ ] Admin UI handles empty audit/moderation/role data safely. --- ## 6. Required automated checks Record the exact command and result. ### 6.1 Backend ```bash cd backend python manage.py check python manage.py makemigrations --check --dry-run python manage.py migrate --plan python manage.py test konnaxion.ethikos python manage.py test konnaxion.kollective_intelligence python manage.py test konnaxion.ekoh ``` If the project uses `pytest`: ```bash cd backend pytest pytest backend/konnaxion/ethikos pytest backend/konnaxion/kollective_intelligence pytest backend/konnaxion/ekoh ``` Results: ```txt python manage.py check: python manage.py makemigrations --check --dry-run: python manage.py migrate --plan: backend tests: known failures: ``` ### 6.2 Frontend ```bash cd frontend npm install npm run lint npm run typecheck npm run build ``` If Playwright/smoke tests are configured: ```bash cd frontend npm run test:e2e npm run smoke ``` Results: ```txt npm run lint: npm run typecheck: npm run build: npm run test:e2e: npm run smoke: known failures: ``` ### 6.3 Static no-drift grep checks Run from repository root. ```bash grep -R "api/kialo\|/api/kialo\|ethikos/kialo\|app/kialo" -n backend frontend docs || true grep -R "api/kintsugi\|/api/kintsugi\|app/kintsugi" -n backend frontend docs || true grep -R "api/deliberation\|/api/deliberation" -n backend frontend docs || true grep -R "api/home" -n backend frontend docs || true grep -R "class Claim\|ClaimViewSet\|ClaimSerializer" -n backend frontend docs || true ``` Expected: - No new `/api/kialo/*`. - No new `/api/kintsugi/*`. - No new `/api/deliberation/*`. - No expanded `/api/home/*` Kintsugi behavior. - No replacement of `EthikosArgument` with `Claim`. Results: ```txt /api/kialo grep: api/kintsugi grep: /api/deliberation grep: /api/home grep: Claim rename grep: ``` --- ## 7. Required manual smoke paths Use local frontend and backend URLs. ### 7.1 Deliberate - [ ] `/ethikos/deliberate/elite` loads. - [ ] Topic preview drawer opens. - [ ] Valid topic preview does not show `Preview / No data`. - [ ] `/ethikos/deliberate/[topic]` loads for a valid topic. - [ ] Argument list/tree renders. - [ ] Empty argument state renders. - [ ] Add argument flow works or fails with clear validation. - [ ] Add stance flow works or fails with clear validation. - [ ] Argument impact vote control is not confused with topic stance. ### 7.2 Decide - [ ] `/ethikos/decide/public` loads. - [ ] `/ethikos/decide/elite` loads. - [ ] `/ethikos/decide/results` loads. - [ ] `/ethikos/decide/methodology` loads. - [ ] Baseline/raw results are visible. - [ ] Derived readings, if present, are labelled as derived. - [ ] Empty consultation state renders. ### 7.3 Trust - [ ] `/ethikos/trust/profile` loads. - [ ] `/ethikos/trust/badges` loads. - [ ] `/ethikos/trust/credentials` loads. - [ ] EkoH context is displayed as context only. - [ ] Private scores are not exposed publicly. ### 7.4 Impact - [ ] `/ethikos/impact/feedback` loads. - [ ] `/ethikos/impact/outcomes` loads. - [ ] `/ethikos/impact/tracker` loads. - [ ] Impact records link to approved source objects. - [ ] Empty impact state renders. ### 7.5 Pulse - [ ] `/ethikos/pulse/overview` loads. - [ ] `/ethikos/pulse/live` loads. - [ ] `/ethikos/pulse/health` loads. - [ ] `/ethikos/pulse/trends` loads. - [ ] Pulse projections are labelled as projections. - [ ] Empty signal state renders. ### 7.6 Learn - [ ] `/ethikos/learn/changelog` loads. - [ ] `/ethikos/learn/glossary` loads. - [ ] `/ethikos/learn/guides` loads. - [ ] Learn pages do not advertise unbuilt features as live. - [ ] Glossary preserves canonical model names. ### 7.7 Insights - [ ] `/ethikos/insights` loads. - [ ] Baseline results are visible where readings are shown. - [ ] Lens/snapshot/audit metadata is visible where available. - [ ] Empty insights state renders. - [ ] Private EkoH data is not exposed. ### 7.8 Admin - [ ] `/ethikos/admin/audit` loads for authorized users. - [ ] `/ethikos/admin/moderation` loads for authorized users. - [ ] `/ethikos/admin/roles` loads for authorized users. - [ ] Unauthorized users are denied. - [ ] Moderation actions are permission-checked. - [ ] Role changes are permission-checked. - [ ] Reading publication/invalidation is permission-checked. --- ## 8. Data invariant checklist These invariants must hold in tests or review evidence. ```txt EthikosTopic = canonical topic/debate/consultation container. EthikosStance = topic-level stance. EthikosArgument = argument/thread/claim-equivalent object. ArgumentImpactVote = argument-level impact signal. ReadingResult = Smart Vote derived reading artifact. LensDeclaration = declared rules for a non-baseline reading. EkoH snapshot_ref = context/audit reference, not vote mutation. Baseline result = raw/unweighted source-derived result. ``` Checklist: - [ ] `EthikosStance != ArgumentImpactVote`. - [ ] `EthikosStance != ReadingResult`. - [ ] `ArgumentImpactVote != ReadingResult`. - [ ] `ReadingResult` cannot overwrite baseline result. - [ ] `ReadingResult` cannot overwrite source topic/stance/argument records. - [ ] EkoH context cannot overwrite source votes/stances/ballots. - [ ] Weighted results cannot be stored as canonical consultation result. - [ ] Kialo-style concepts do not rename ethiKos core models. --- ## 9. Permission matrix checklist | Actor | May create stance | May create argument | May create argument impact vote | May suggest argument | May moderate | May assign roles | May publish reading | May compute reading | |---|---:|---:|---:|---:|---:|---:|---:|---:| | Anonymous public | TBD | TBD | TBD | TBD | No | No | No | No | | Authenticated user | Yes | Yes | Yes | Yes, if enabled | No | No | No | No | | Moderator | Yes | Yes | Yes | Yes | Yes | Limited/TBD | No/TBD | No | | Admin | Yes | Yes | Yes | Yes | Yes | Yes | Yes, if authorized | No/TBD | | System/compute actor | No | No | No | No | No | No | No/TBD | Yes | QA checks: - [ ] Matrix is confirmed against actual implementation. - [ ] Any `TBD` is resolved before release or explicitly deferred. - [ ] Tests cover normal user restrictions. - [ ] Tests cover moderator/admin privileges. - [ ] Tests cover system/compute separation where applicable. --- ## 10. Regression checklist - [ ] Existing `EthikosTopic` creation still works. - [ ] Existing `EthikosStance` creation still works. - [ ] Existing `EthikosArgument` creation still works. - [ ] Existing category behavior still works where enabled. - [ ] Existing Kollective vote behavior still works. - [ ] Existing Decide result aggregation still works. - [ ] Existing Learn glossary/changelog/guides still render. - [ ] Existing ethiKos shell/sidebar/navigation still render. - [ ] Existing admin pages still render. - [ ] Existing tests unrelated to Kintsugi are not broken. - [ ] No unrelated module behavior is changed. --- ## 11. Known bug validation ### Preview drawer bug Known issue: ```txt Deliberate preview drawer shows "Preview / No data" for valid topic previews. ``` Acceptance: - [ ] Valid topic with no arguments shows topic metadata and empty argument state. - [ ] Valid topic with arguments shows topic metadata and argument preview. - [ ] Invalid topic shows not-found/error state. - [ ] Network failure shows clear error state. - [ ] Fix does not create new architecture or new route family. - [ ] Fix does not bypass frontend service layer. --- ## 12. Rollback checklist For each merged slice: ```txt slice: migration files: backend files: frontend files: docs files: rollback command: data risk: fallback UI: owner: ``` Checks: - [ ] Slice can be reverted without deleting existing source facts. - [ ] Migration rollback is understood. - [ ] Existing routes still work without new records. - [ ] Frontend handles missing new fields. - [ ] Rollback notes are included in patch/release notes. - [ ] Any non-reversible migration has explicit maintainer approval. --- ## 13. QA evidence record Use this table for the final review. | Gate | Status | Evidence | Owner | Notes | |---|---|---|---|---| | G0 Scope | [ ] | | | | | G1 Source-of-truth | [ ] | | | | | G2 Route/API | [ ] | | | | | G3 Migration | [ ] | | | | | G4 Backend API/test | [ ] | | | | | G5 Frontend service/UI | [ ] | | | | | G6 Smoke | [ ] | | | | | G7 Documentation | [ ] | | | | | G8 Rollback | [ ] | | | | | G9 Final sign-off | [ ] | | | | --- ## 14. Final Wave 1 sign-off ```txt QA reviewer: Backend reviewer: Frontend reviewer: Architecture/boundary reviewer: Product/module owner: Date: Commit/branch: Release candidate: ``` Final acceptance: - [ ] All global gates are passed or explicitly waived. - [ ] All slice checklists are passed or explicitly deferred. - [ ] All automated checks are passed or failures are documented. - [ ] All manual smoke paths are checked. - [ ] All rollback notes are complete. - [ ] All documentation updates are complete. - [ ] No route drift. - [ ] No model rename drift. - [ ] No source-fact/reading confusion. - [ ] No unauthorized OSS import. - [ ] Wave 1 is approved for merge/release. --- ## 15. Final rejection triggers Reject the release if any of these are true: ```txt Creates /kialo route family. Creates /kintsugi route family as implementation target. Creates konnaxion.kialo. Creates konnaxion.kintsugi. Renames EthikosArgument to Claim. Renames EthikosStance to Vote or Opinion. Treats ArgumentImpactVote as EthikosStance. Treats ReadingResult as source fact. Uses Smart Vote to mutate Korum records. Uses Smart Vote to mutate Konsultations records. Uses EkoH as voting engine. Expands /api/home/* for Kintsugi decision data. Imports external OSS app directly. Introduces schema changes without migration/testing plan. Introduces unreviewed route families. Breaks existing ethiKos route rendering. Breaks existing ethiKos API endpoints. Publishes weighted results as canonical baseline facts. Leaks private EkoH scores in public payloads. ``` Any rejection trigger requires either: 1. code change before merge; or 2. explicit ADR superseding the current Kintsugi contracts. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/ethiKos_Kintsugi_Update/27_EKOH_RATING_VISIBILITY_AND_ACCESS_CONTRACT.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c7df0e8bc0735da99e97b1b309b9703cb1e81c8d84b6e5e865fc920e0519c3ba CONTENT_BYTES: 9136 ================================================================================================ # 27 — EkoH Rating Visibility and Access Contract **Status:** Canonical V4.1 extension **Approved direction:** 2026-08-20 **Owner:** EkoH **Purpose:** define how individual EkoH ratings may be disclosed without turning EkoH into a second identity/RBAC system. --- ## 1. Decision EkoH owns three things that must remain distinct: 1. **rating truth** — the current expertise/ethics ratings and their history; 2. **rating disclosure** — whether a viewer may see those EkoH-owned ratings; 3. **rating audit context** — provenance/history attached to the EkoH rating ledger. EkoH does **not** own civic votes, source stances, Smart Vote readings, organisation HR truth, or platform-wide business roles. The canonical separation is: ```text Identity visibility -> ConfidentialitySetting Rating visibility -> RatingVisibilitySetting + scoped grants Contextual influence -> Smart Vote declared reading/lens ``` An individual score is not automatically private merely because it is individual. A rating may be intentionally public when governance policy requires public scrutiny, including public/demo roles whose decision-support influence depends on publicly reviewable competence. A **private** rating remains private. A **public** rating is intentionally disclosed. A **scoped** rating is disclosed only to viewers whose EkoH access grant covers the rated subject. --- ## 2. Non-goals V4.1 MUST NOT introduce: - a second Konnaxion identity system; - a second global RBAC engine; - EkoH business roles such as `CEO`, `Supervisor`, `Manager`, `Minister`, or `HR`; - EkoH-owned organisation/department truth; - a Smart Vote weight stored as a global EkoH profile field; - direct EkoH writes into Ethikos/Korum/Konsultations source facts. Calling modules may map their own organisation/team/project concepts to a generic EkoH scope, but EkoH only evaluates disclosure grants. --- ## 3. Canonical models ### 3.1 `RatingVisibilitySetting` Per-rated-subject publication policy. ```yaml user: OneToOne(settings.AUTH_USER_MODEL) visibility: public | scoped | private publication_basis: string updated_at: datetime ``` Compatibility rule: if no row exists, current ratings retain the pre-V4.1 behavior and are treated as `public` until an explicit policy is created. ### 3.2 `RatingAccessScope` Generic reusable hierarchical scope. ```yaml key: stable slug name: display label parent: optional self FK scope_type: optional semantic hint external_namespace: optional adapter namespace external_key: optional external object key active: boolean ``` No foreign key to Ethikos, Team Builder, KeenKonnect, Kontrol, or any external organisation model is required. ### 3.3 `RatingScopeSubject` Assigns a rated user to a disclosure scope. ```yaml scope: FK RatingAccessScope user: FK settings.AUTH_USER_MODEL active: boolean unique: [scope, user] ``` ### 3.4 `RatingAccessGrant` Grants a viewer access to ratings in one scope. ```yaml viewer: FK settings.AUTH_USER_MODEL scope: FK RatingAccessScope include_descendants: boolean access_level: ratings | history active: boolean unique: [viewer, scope] ``` `ratings` exposes current domain ratings and ethics/reliability context. `history` additionally exposes the governed `ScoreHistory` projection. --- ## 4. Access resolver All consuming modules MUST use the EkoH access decision, not reimplement it. Canonical service: ```python resolve_rating_access(viewer=viewer, subject=subject) ``` Canonical decision order: ```text 1. self -> history 2. staff compatibility override -> history 3. explicit matching scope grant -> ratings/history 4. public rating policy -> ratings 5. deny ``` `private` is stricter than `scoped`: scope grants do not override a private policy. An ancestor grant applies to a descendant scope only when `include_descendants=true`. Example: ```text ACME ├── Department A │ ├── Alice │ └── Bob └── Department B └── Eve Boss grant -> ACME, descendants=true, history Supervisor A -> Department A, descendants=true, ratings ``` Result: ```text Boss -> Alice, Bob, Eve Supervisor A -> Alice, Bob only ordinary employee -> self + public profiles ``` EkoH does not need to know that one viewer is a boss and another is a supervisor. --- ## 5. Identity visibility is separate `ConfidentialitySetting` continues to control identity presentation: ```text public pseudonym anonymous ``` `RatingVisibilitySetting` controls rating disclosure: ```text public scoped private ``` These settings MUST NOT be collapsed into one enum. An anonymous identity remains non-discoverable to ordinary callers even if a rating policy is otherwise public, because rating disclosure must not defeat the stronger identity-protection decision. --- ## 6. Public figures and public roles A public individual rating is permitted when its publication policy explicitly declares it. The public-policy rule is: > If EkoH-derived competence materially supports public decision-making influence, the governance basis for that influence may itself be made public and auditable. This does not create a universal rank. EkoH remains domain-specific. A high software-architecture rating does not imply authority in diplomacy, law, education, Indigenous governance, or another unrelated domain. `publication_basis` SHOULD explain why the rating is public. --- ## 7. API contract Canonical endpoint remains: ```text GET /api/v1/ekoh/profile/{user_id}/ ``` Allowed response: ```json { "user_id": 42, "display_name": "Example Person", "confidentiality_level": "public", "rating_visibility": "scoped", "rating_publication_basis": "", "rating_access": { "allowed": true, "level": "ratings", "reason": "scope_grant", "scope": { "key": "acme-department-a", "name": "Department A" } }, "ethics_score": 0.97, "expertise": [ { "domain_code": "0613", "domain_name": "Software and applications", "weighted_score": 0.91 } ], "score_history": null } ``` Denied rating access is represented without leaking the ratings: ```json { "rating_access": { "allowed": false, "level": null, "reason": "outside_authorized_scope", "scope": null }, "ethics_score": null, "expertise": null, "score_history": null } ``` The backend is authoritative. Frontend code MUST NOT infer access from role labels or hide data that the backend already exposed as an authorization substitute. --- ## 8. Smart Vote boundary Smart Vote may compute a declared reading from EkoH context, but EkoH does not become the vote engine. Smart Vote MUST preserve: - raw baseline source facts; - declared lens/snapshot context; - reproducibility; - separation between rating and contextual advisory influence. Participant-level reading details derived from EkoH MUST respect EkoH disclosure before being returned to the caller. Aggregate Smart Vote results may still be computed from the declared lens without disclosing private individual ratings. The following are distinct values: ```text EkoH domain rating EkoH ethics/reliability context question-specific expertise alignment Smart Vote advisory weight ``` They MUST NOT be presented as synonyms. --- ## 9. Frontend contract Reusable EkoH UI belongs under: ```text frontend/services/ekoh.ts frontend/modules/ekoh/components/ ``` Ethikos may compose EkoH UI with Smart Vote context, but the reusable EkoH components MUST NOT import Smart Vote. Canonical reusable components in V4.1: ```text EkohRatingDrawer EkohDomainRatings EkohAccessNotice ``` A consuming module may add context-specific content after the generic rating display. --- ## 10. Migration contract V4.1 uses one additive EkoH migration. It MUST: - create only EkoH-owned access/disclosure tables; - preserve existing `UserExpertiseScore`, `UserEthicsScore`, `ScoreHistory`, and `ConfidentialitySetting` rows; - preserve existing profile URLs; - preserve pre-V4.1 readable-profile behavior when no explicit rating policy exists; - use the existing `ekoh_smartvote` schema/search-path contract. It MUST NOT rename or move existing score tables. --- ## 11. Minimum test matrix Required automated cases: ```text public profile + anonymous viewer -> ratings visible private profile + self -> history visible private profile + other viewer -> denied scoped Department A + Supervisor A -> visible scoped Department B + Supervisor A -> denied company root + descendant grant -> all child departments visible history grant -> ScoreHistory visible ratings grant -> ScoreHistory hidden Smart Vote participant detail -> filtered through EkoH disclosure aggregate baseline/reading -> unchanged by display permission ``` --- ## 12. Final contract statement ```text EkoH owns the rating. EkoH owns disclosure of the rating. The consuming application owns the context in which the rating is requested. Smart Vote alone owns the derived influence of that rating on a declared reading. ``` This contract extends the existing Kintsugi ownership rules; it does not replace them. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kintsugi-upgrade-v1.md.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 56dc6c857b13327770310f358b14b4b1b6a640db564a9a57e9869025877f84ed CONTENT_BYTES: 10084 ================================================================================================ # **keenKonnect — Kintsugi v1 (Hybrid)** **An accessible technical spec for an “open builder stack under one roof”** **Scope:** Kintsugi track (toolchain integration). *(Kompendio \= reference repertory; separate spec.)* **Deployment posture:** Hybrid (SaaS \+ self-host / on-prem) --- ## **1\) What is keenKonnect** keenKonnect is a **builder execution environment**: a place to run real-world projects with a tight link between: * **work coordination** (plans, tasks, decisions, accountability) * **artifacts** (CAD exports, docs, BOMs, test notes, photos, releases) * **reproducibility** (what was built, with what sources, by whom, and in what version) If “GitHub” made software collaboration and release reproducible, keenKonnect is aiming at the same property for **physical builds**. ## **2\) What is Kintsugi (in keenKonnect)** Kintsugi is the approach for **bringing open-source building blocks under one coherent roof**—without merging everything into a monolith. It is: * a curated set of **open-source primitives** (inventory/BOM, docs, search, storage, forge) * a strict set of **integration contracts** so these primitives behave like one product * a hybrid-safe packaging posture so the same experience works in SaaS and self-host It is not: * a full CAD platform replacement * a giant proprietary-catalog mirror * “connect everything” in v1 ## ## **3\) The problem Kintsugi solves** Builders typically have: * docs in one system * BOM/inventory elsewhere * files scattered across drives * no unified permissions * weak provenance (what is the source of truth?) * no reliable release bundle that can be recreated later Kintsugi solves this by turning those scattered tools into **lanes** that share: * one identity layer * one permission model * one event/audit surface * one artifact/release packaging model ## ## ## **4\) Core principles** ### **4.1 Annex vs Mimic** * **Annex**: integrate an open-source service as a sidecar when it’s modular, isolable, and worth it. * **Mimic**: implement the pattern natively when annexing would create licensing risk, UX fragmentation, or dual-truth issues. ### **4.2 One roof experience** Kintsugi must feel like a single product: unified login, consistent permissions, stable project links, consistent “where is the file / BOM / doc?” answers. ### **4.3 No dual truth** Every object that matters must have a canonical identity and lifecycle inside keenKonnect, even if it is authored in a sidecar. ### **4.4 Reproducible releases** A build is not “done” unless it can produce a **Release Pack**: manifests \+ artifacts \+ pinned references (and optionally checksums/signatures). ### **4.5 Hybrid by default** Everything must work for: * hosted SaaS * self-host/on-prem * “restricted” environments (policy, sovereignty, intermittent connectivity) ## ## **5\) The integration contract (what makes it “one roof”)** Any annexed component must satisfy these contracts: 1. **Identity & access** * OIDC/SSO integration * role/group mapping to keenKonnect permissions 2. **Canonical IDs** * every external object maps to a keenKonnect canonical ID * no “two sources of truth” for the same thing 3. **Events** * changes produce events that land in the project timeline (who/what/when) 4. **Artifact contract** * important outputs must be capturable as artifacts in Stockage (with version semantics) 5. **Portability** * export path exists (pack/dataset/manifest) for migrations, audits, offline use If a tool cannot meet these contracts, it stays “external reference” (Kompendio) or is mimicked. ## **6\) The Kintsugi lanes (what is gathered in open source)** Kintsugi v1 is a small set of lanes with default choices \+ optional alternatives. ### **Lane A — Parts / BOM / inventory (the open backbone)** **Default:** **InvenTree** * Why: API-friendly inventory \+ BOM backbone, easy to integrate into build workflows. **Optional:** **Part-DB** * Why: component inventory workflows that some teams prefer. * Note: treat as opt-in lane where licensing and deployment policy allow it. **Loud credit:** InvenTree and Part-DB communities have already solved years of practical inventory/BOM edge cases. Kintsugi is explicitly built to *not reinvent that wheel*, but to integrate it into a reproducible build lifecycle. --- ### **Lane B — Search & indexing (find anything across projects)** **Default:** **OpenSearch** * Why: a search/index foundation to unify discovery across projects, docs, BOM, artifacts, and later Kompendio references. **Loud credit:** OpenSearch makes it realistic to give builders one search bar across “everything that matters,” without forcing a single storage format. --- ### **Lane C — Collaborative docs (specs, build logs, checklists)** **Default:** **Etherpad** * Why: lightweight real-time collaboration for specs/logs that become build evidence. **Optional:** **HedgeDoc** * Why: Markdown-first collaborative notes, preferred by some teams. **Loud credit:** Etherpad/HedgeDoc are battle-tested “human collaboration primitives.” Kintsugi treats them as the authoring surface, while keenKonnect owns the lifecycle (permissions, snapshots, release inclusion). --- ### **Lane D — Storage substrate (artifacts, exports, evidence)** **Default:** **SeaweedFS** * Why: practical storage for large artifacts and object-like workflows. **Optional:** **Ceph** * Why: heavy-duty storage for larger or stricter deployments. **Optional:** **MinIO** * Why: S3-centric deployments or teams already standardized on MinIO. **Loud credit:** Storage projects like SeaweedFS/Ceph/MinIO represent huge operational maturity. Kintsugi’s job is to standardize artifact semantics and packaging—not rebuild storage. --- ### **Lane E — Forge (scripts, templates, internal tooling)** **Default:** **Gitea** * Why: a forge for “code around building”: templates, automation scripts, test harnesses, build recipes, CI for artifacts. **Optional:** **Forgejo** * Why: teams that prefer that governance and ecosystem posture. **Loud credit:** Gitea/Forgejo make it feasible to treat “how you build” as versioned knowledge, tied to releases—without forcing full enterprise ALM. --- ### **Lane F — CAD/BIM toolchain (export lanes, not UI takeovers)** **v1 position:** CAD/BIM tools remain toolchains. Kintsugi standardizes: * export formats * artifact capture * traceability (which export belongs to which release/task) Kintsugi does not attempt to become a CAD frontend in v1. **Loud credit:** Open CAD/BIM ecosystems have deep complexity. Kintsugi’s value is a stable “export → artifact → release” lifecycle that works no matter which authoring tool a team uses. ## ## **7\) How a project flows end-to-end (user-facing behavior)** 1. Create a project in keenKonnect (Konstruct workspace). 2. Draft specs and logs in the docs lane; snapshots are captured as project artifacts. 3. Create/maintain the BOM in the inventory lane; BOM snapshots are captured. 4. Store CAD exports and build evidence in the storage lane. 5. Search across everything (metadata \+ content where allowed) via the search lane. 6. Produce a **Release Pack**: * release manifest (what’s included) * artifact list (with versions/checksums) * pinned references (Kompendio links, if applicable) ## **8\) Boundary with Kompendio (to avoid confusion)** * **Kintsugi** \= integrated open-source toolchain lanes that power building and reproducibility. * **Kompendio** \= repertory of external reference websites \+ curated charts \+ trust signals. A project uses both: * Kintsugi to *execute and package* the build * Kompendio to *anchor reference-grade external sources* without mirroring them ## **9\) Hybrid deployment policy** ### **Default bundle (lowest friction)** A hybrid-safe default set should prioritize permissive licensing and operational simplicity: * InvenTree (inventory/BOM) * OpenSearch (search) * Etherpad (collab docs) * SeaweedFS (storage) * Gitea (forge) ### **Optional components (policy-dependent)** * Part-DB, HedgeDoc, MinIO, Forgejo can be enabled per deployment depending on governance/licensing preferences. Key requirement: all options still satisfy the **integration contract** so the UX remains unified. ## **10\) Risks and mitigations** 1. **UX fragmentation (too many tools)** * Mitigation: strict integration contract \+ single navigation \+ project-native linking. 2. **Dual-truth drift** * Mitigation: canonical IDs \+ snapshots \+ “release pack” as the final truth. 3. **License complexity in hybrid** * Mitigation: permissive-by-default; copyleft components are opt-in and isolated. 4. **Operational complexity** * Mitigation: keep v1 lane set small; document “known good” deployment profiles. ## **11\) What I’m asking from maintainers and builders** * Which integration surfaces matter most? (webhooks, exports, auth patterns, APIs) * What lane is missing for real-world builds? * What breaks most often in hybrid SaaS \+ self-host environments? * What must a “Release Pack” contain to be truly reproducible for your workflow? ## **12\) Credits (loud, explicit)** Kintsugi v1 stands on the shoulders of these open-source projects and the people maintaining them: * **InvenTree** — inventory & BOM backbone * **Part-DB** — component inventory workflows (optional lane) * **OpenSearch** — unified search/index foundation * **Etherpad** — real-time collaborative notes/logs * **HedgeDoc** — Markdown-first collaborative notes (optional lane) * **SeaweedFS** — practical artifact/object storage * **Ceph** — durable storage for larger deployments (optional lane) * **MinIO** — S3-centric storage option (optional lane) * **Gitea** — forge for build scripts/templates/workflows * **Forgejo** — forge alternative (optional lane) ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/keenKonnect-kompendio-v1.md.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 1b375d93d2d1c8012a62ef2e539699505bed3201a197bc44f847be697efd3027 CONTENT_BYTES: 16056 ================================================================================================ # keenKonnect — Kompendio (v1) **The builder reference layer:** a curated repertory of **reference platforms** plus **versioned reference charts**, connected to projects and preserved as reproducible artifacts. Kompendio is the third submodule of **keenKonnect**, alongside: - **Konstruct** — run the build (projects, tasks, coordination) - **Stockage** — preserve the build (files, releases, bundles) - **Kompendio** — guide the build (reference stack, charts, trust) Kompendio does not replace external tools. It makes them **legible, comparable, auditable, and reusable** in a build workflow. --- ## 0) Where Kompendio fits keenKonnect has three submodules: 1. **Konstruct** — project collaboration and execution 2. **Stockage** — secure repository and artifact preservation 3. **Kompendio** — reference repertory, builder charts, and trust Kompendio solves a practical builder problem: **Which websites and platforms are actually the reference stack for this build, and can we trust them?** It turns that answer into something reusable, versioned, and project-attachable. --- ## 1) What Kompendio is (in one sentence) Kompendio is a **reference platform repertory** at the **website/platform level** that produces **builder charts**, **trusted reference stacks**, and **exportable reference packs** that can be pinned to projects. Key point: Kompendio deals with **widescale reference sites** as reference objects, not random internal pages. --- ## 2) Purpose Kompendio provides: - a directory of reference platforms - a trust and rating system backed by evidence - **Reference Charts** (curated cheat sheets and summaries) that are versioned and publish-gated - project attachment so references become part of execution, not bookmarks - exportable packs for reproducibility, offline use, and deployment portability --- ## 3) What Kompendio is — and is not ### Is - A curated repertory of **reference platforms** at the website/platform level - A publishing pipeline for **charts** and **trusted reference sets** - A decision-support layer with **raw scoring** and a future-ready **advisory scoring** path - A reproducibility layer that preserves what was relied on for a build ### Is not (v1) - A crawler of entire sites - A mirror of proprietary catalogs or datasets - A replacement CAD tool - A universal connector platform for every external site - A full-blown BOM ingestion engine for every source --- ## 4) Design principles (non-negotiable) 1. **Website-level objects** - Kompendio stores platforms and a small set of canonical entrypoints, not millions of internal pages. 2. **Mimic vs Annex** - By default, Kompendio mimics useful patterns from reference ecosystems (indexing, matrices, curation) without ingesting proprietary datasets. - Optional open-source systems may be **annexed as sidecars** only when they are worth isolating cleanly. 3. **Evidence-first** - Every rating and chart claim must be backed by explicit evidence: links, docs, screenshots, exports, or equivalent artifacts. 4. **Fail-closed publishing** - If verification or review fails, it does not publish. 5. **Portability** - Outputs are exportable as versioned packs so projects can reproduce decisions later. 6. **Trust over vibes** - If it cannot be checked, it cannot be published as Trusted. --- ## 5) What Kompendio integrates with Kompendio has three integration layers: 1. **Core Konnaxion integrations** (always-on inside keenKonnect) 2. **Annexable open-source sidecars** (optional but first-class) 3. **External reference ecosystem** (usually link plus metadata, not data mirroring) ### 5.1 Core Konnaxion integrations (always-on) These are built-in dependencies that make Kompendio operationally useful: - **Konstruct (Projects / Tasks)** - Attach **Reference Stacks** and chart versions to projects - Link tasks to charts or platforms (for example, “use chart X” or “order from catalog Y”) - **Stockage (Repository / Artifacts)** - Store chart exports (PDF, MD, CSV), evidence snapshots, and versioned packs - Preserve **what was relied on** for a build so it stays reproducible - **Identity + Permissions (RBAC)** - Control who can publish, review, or mark something as Trusted - Support moderation and credibility - **Search** - Make Kompendio usable at scale across platforms, stacks, and charts - **Optional later: EkoH / Smart Vote** - Add an advisory score layer with expert weighting while keeping raw scoring visible ### 5.2 Annexable open-source sidecars (optional, explicit, supported) These do not replace Kompendio. They extend it as isolated sidecars. **Identity & access** - **Keycloak (OIDC)** — unified login for sidecars when self-hosting **Storage** - **MinIO** or **SeaweedFS** — S3-compatible artifact storage for packs, evidence, and exports **Search** - **OpenSearch** — indexing and retrieval across Kompendio entities and chart content **Real-time docs (optional collaborative editing)** - **HedgeDoc** - **Etherpad** - **OnlyOffice** - **Collabora** These can support collaborative editing, with outputs preserved back into Stockage. **Inventory / BOM sidecars** - **InvenTree** - **Part-DB** - **PartKeepr** (legacy / optional) Kompendio does not need to ingest full inventories in v1. It can reference these tools as platforms and optionally sync summaries later without becoming the system of record. **CAD / geometry helpers (not CAD replacements)** - **FreeCAD** (headless / CLI workflows) - **OpenSCAD** - **SolveSpace** - **Three.js-based viewers** for STEP/STL preview - **IFC.js** or equivalent for BIM previews ### 5.3 External reference ecosystem (explicit coverage) These are reference platforms Kompendio inventories and rates. Integration is generally: - link plus structured metadata - evidence snapshots - export / format notes - no mirroring of proprietary datasets Examples include: **CAD / design platforms** - cloud CAD ecosystems - desktop CAD ecosystems - open CAD ecosystems **Parts catalogs / procurement** - industrial catalogs - electronics distributors - fastener, bearing, pneumatics, and hydraulics suppliers **CAD content libraries** - manufacturer libraries - aggregators - community libraries, with IP risk flagged where appropriate **EDA symbol / footprint sources** - open library ecosystems - aggregator references, usually link-only **BIM object libraries** - commercial BIM object platforms - national or institutional BIM libraries **Materials databases** - commercial materials databases - manufacturer datasheets - institutional and handbook sources **Standards and handbooks** - standards bodies - engineering handbook sites - institutional references --- ## 6) Integration modes Every platform or sidecar in Kompendio is assigned an **Integration Mode** so coverage stays explicit. - **Link-only** - Store the platform as a reference with canonical entrypoints and notes - No data mirroring - **Evidence capture** - Store screenshots, doc links, exports, and other supporting artifacts for ratings and chart claims - **Artifact pinning** - Attach a platform, stack, or chart version to a project and preserve it in Stockage - **Connector (sidecar)** - Integrate selectively with an OSS system while keeping boundaries explicit and isolated This keeps Kompendio from drifting into crawler or mirror behavior. --- ## 7) Scope (v1) ### Must-have deliverables 1. **ReferencePlatform Registry** - create and edit platforms, tags, domains, types, and entrypoints 2. **Capability Matrix** - track formats, APIs, auth, exports, stability notes, and known limitations 3. **Multi-dimensional ratings** - vector ratings backed by evidence and reviewer context 4. **Trust states** - Draft → Reviewed → Trusted, with explicit promotion gates 5. **Reference Charts** - curated, cited, versioned charts with review and publish workflow 6. **Project pinning** - attach a Reference Stack and chart versions to a Konstruct project 7. **Export / Import** - bundle platforms, charts, evidence pointers, and manifests into a **Reference Pack** with integrity checks ### Explicit non-goals - automated crawling of internal pages or SKUs - copying proprietary datasets - universal connectors for every external service - complete BOM ingestion from every source --- ## 8) Core objects (data model) ### A) ReferencePlatform A website/platform-level reference object. Fields: - `id` - `name` - `canonical_url` - `type` — CAD, Catalog, Standards, Materials, Reference, BIM, EDA, Library, Community - `domains[]` — mechanical, electronics, building, fabrication, etc. - `tags[]` — fasteners, bearings, sheet metal, welding, PCB, etc. - `access_model` — public, account, paid, API - `openness_class` — open-source, open-data, proprietary, mixed, unknown - `ip_risk_flag` — low, medium, high - `entrypoints[]` — 2 to 10 URLs that matter at widescale - `capability_matrix` - formats - exports - API availability - auth type - known limitations - `trust_state` — Draft, Reviewed, Trusted - `last_verified_at` ### B) Assessment An evidence-backed review of a platform or chart. Fields: - `id` - `platform_id` or `chart_id` - `reviewer_id` - `reviewer_context` — domain tags, role, optionally “used in project” - `scores{}` — per-dimension scores - `evidence_links[]` - `verification_state` — unverified, peer, expert - `timestamp` ### C) ReferenceChart A builder-facing reference chart. Fields: - `id` - `title` - `scope` - `content` - `source_platform_ids[]` - `claims[]` with citations - `version` - `validation_state` — Draft, Reviewed, Published - `change_log` ### D) ReferenceStack A curated set of platforms and chart versions for a build context. Fields: - `id` - `name` — for example, “Metal Fab Starter Stack” - `platform_ids[]` - `chart_ids[]` - `intended_context` - `version` ### E) Dispute / Revalidation Quality-control structures for maintaining trust. Fields: - `dispute_id` - `target_id` - `reason` - `counter_evidence[]` - `status` - `revalidation_schedule` - staleness signals --- ## 9) Ratings model (v1) ### Recommended dimensions - **Reliability / correctness** - **Coverage / completeness** - **Practical usefulness** - **UX / findability** - **Interoperability** — formats, APIs, exports - **Openness** — license clarity, portability - **Stability** — longevity, predictable URLs ### Outputs - **Raw score** — simple aggregate or transparent baseline - **Advisory score** — reserved for weighted or expert-informed scoring later In v1, the advisory score can use equal weights while the schema remains future-ready. --- ## 10) Trust and publishing workflow ### 10.1 Platform onboarding 1. Create platform → **Draft** 2. Run auto-checks: - required fields present - canonical URL present - duplicate checks - minimum capability matrix complete - openness class filled 3. Submit for review 4. Reviewer actions: - accept → **Reviewed** - reject → back to **Draft** with required fixes 5. Promote to **Trusted** only if evidence threshold is met ### 10.2 Chart publishing 1. Create chart → **Draft** 2. Attach sources, claims, and citations 3. Peer review for accuracy, completeness, and licensing constraints 4. Publish → **Published**, or fail-closed back to Draft / Reviewed 5. Versioning rules: - never silently edit a published chart - new versions create new immutable releases ### 10.3 Disputes and revalidation - Any Trusted platform or Published chart may be challenged with counter-evidence - A challenge triggers re-review - Re-review may result in: - a new version - a downgrade in trust state - confirmation with no change ### 10.4 Trust states - **Draft** — proposed, incomplete, or unverified - **Reviewed** — checked and acceptable - **Trusted / Published** — safe for reuse in builds Rule: **If it cannot be checked, it cannot be published as Trusted.** --- ## 11) What Kompendio produces ### 11.1 Reference Platforms (directory) For each platform, Kompendio makes explicit: - what it is for - what it covers - how it plugs into workflows - what formats and exports it supports - how open or stable it is - what its trust state is ### 11.2 Reference Charts (builder charts) Charts are the primary leverage layer: - curated cheat sheets and comparisons - sourced and review-gated - versioned so builds remain reproducible Examples: - fastener reference charts - tolerance charts - materials comparison charts - procurement or sourcing references ### 11.3 Reference Stacks (context packs) A **Reference Stack** is a curated set of platforms and chart versions for a build context, such as: - metal fabrication - CNC build - PCB plus enclosure build - timber build - robotics build ### 11.4 Reference Packs (export bundles) A **Reference Pack** contains: - selected platforms - selected charts and versions - evidence pointers or snapshots - manifest for integrity validation --- ## 12) Integration with keenKonnect ### With Konstruct (projects) Kompendio adds a **References** layer inside project execution: - attach a **Reference Stack** to a project - pin specific chart versions - link tasks to charts or platforms - preserve which references were actually used ### With Stockage (artifacts) Stockage stores: - chart exports (PDF, CSV, MD) - evidence snapshots (screenshots, documents, exports) - release bundles and Reference Packs Published charts and stacks are treated as versioned artifacts that can be referenced by builds and releases. --- ## 13) Reference Packs (offline / export) A **ReferencePack** bundle may contain: - ReferencePlatforms — metadata, entrypoints, capability matrices - Assessments — evidence links and scores - ReferenceCharts — content, citations, versions - Manifest — hashes and signature-ready structure Rules: - import validates integrity before activation - packs are versioned - old packs remain usable for reproducibility --- ## 14) UI surface (v1) ### 1. Directory - filters by domain, type, openness, trust state, access model - sorts by raw score, advisory score, stability, interoperability ### 2. Platform page - summary and entrypoints - capability matrix - ratings breakdown plus evidence - trust badge, last verified, audit trail - attach-to-project action ### 3. Chart page - chart content - sources and citations - version history and validation state - attach-to-project action ### 4. ReferenceStack builder - create stacks - publish stacks - attach stacks to projects ### 5. Review queue - items awaiting review - disputes - revalidation tasks --- ## 15) Acceptance criteria (definition of done for v1) Kompendio v1 is done when: - you can add a reference platform with proper entrypoints and tags - you can rate it with evidence, not vibes - you can publish a versioned chart through review gates - a Konstruct project can pin a Reference Stack and specific chart versions - Stockage preserves the charts and evidence used for the build - Reference Packs export and import with integrity validation - the system clearly distinguishes **link-only** from **annexable sidecar** resources --- ## 16) Roadmap - **v1** — registry, ratings, charts, trust workflow, project pinning, export packs - **v1.1** — revalidation cadence, dispute UX, “used in project” attestations - **v2** — selected OSS sidecars, search and storage enhancements, limited summary sync where appropriate, never proprietary mirroring --- ## 17) Summary Kompendio is the **reference intelligence layer** of keenKonnect. It inventories and evaluates the websites and platforms builders actually rely on, turns that knowledge into **versioned charts** and **trusted stacks**, ties those references into project execution, and preserves them as **reproducible artifacts**. Its core rule is simple: **If it cannot be checked, it cannot be trusted for reuse.** ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/Konnaxion-kintsugi-and-kompendio-open-source-integration-map-v1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 6bf94a0e689fce381fbcf9f0842218247add1c2cb6cc0024fefbb7f7ab74ee46 CONTENT_BYTES: 4284 ================================================================================================ # **Konnaxion: Kintsugi \+ Kompendio Open-Source Integration Map** ## **Konnaxion is already the backbone** **Konnaxion already exists** as the coordination “spine” of the kOA ecosystem: a public shell that links education, building, and governance modules into one coherent loop—without creating new silos. It’s not optimized for “just shipping features,” but for **governability under real constraints** (offline/local capability, auditability, modularity, and resistance to capture). ## **How to read the open-source list** This inventory is structured in two layers that sit **on top of Konnaxion**: * **Kintsugi** \= the “open-source under one roof” layer: a curated set of primitives integrated as lanes, held together by shared contracts (identity, permissions, event/audit surface, artifact/release packaging) so they behave like one product across SaaS and self-host deployments. * **Kompendio** \= the “reference \+ integration map” layer: not a link list, but an **integration repertory** that makes dependencies explicit (what we **Annex** as sidecars vs what we **Mimic** as native patterns), and publishes versioned charts/fiches you can pin to projects. ## KonnectED (upgrade track) | Area | Standards / protocols | Annexed (integrated sidecars) | Mimicked (pattern sources; not annexed by default) | Core stack that stays stable | | :---- | :---- | :---- | :---- | :---- | | **Kintsugi** | OIDC (SSO), LTI 1.3 (tool launch), xAPI (event capture), Open Badges; S3 API for object storage; OIDC/SAML \+ JWT coexistence via Keycloak-style SSO | **H5P**, **SQL LRS (xAPI)**, **Safe Exam Browser (SEB)**, **Kolibri**, **Keycloak**, **OpenSearch**, **SeaweedFS** (and allow MinIO-style) | **Moodle** (default mimic; optional annex as separate service), **TAO CE** (default mimic; optional annex as separate service), **Open Badges model** (default mimic; optional annex issuer like Badgr/EduBadges), **LimeSurvey** (baseline questionnaires) | Next.js, Django, Postgres, Celery, unified auth \+ RBAC, Insights | | **Kompendio** | **OIDC**, **LTI 1.3 (+ Advantage)**, **xAPI**, **cmi5**, **Open Badges 3.0**; comparison refs: **QTI**, Common Cartridge/Thin CC, OneRoster, Caliper, SCORM | Activity engines: Moodle, H5P, TAO, SEB, LimeSurvey, LRS (Learning Locker / SQL LRS), Open Badges issuers (Badgr / EduBadges) | (Kompendio’s job is to map Mimic vs Annex explicitly per entry) | Sovereign infra shelf: Keycloak, OpenSearch, SeaweedFS/MinIO | ## keenKonnect (upgrade track) | Area | Integrated tech | Standards / contracts | Reference ecosystem (tracked as references, not sidecars) | | :---- | :---- | :---- | :---- | | **Kintsugi** | Lanes: **InvenTree** (default) / Part-DB (opt); **OpenSearch**; **Etherpad** (default) / HedgeDoc (opt); **SeaweedFS** (default) / Ceph (opt) / MinIO (opt); **Gitea** (default) / Forgejo (opt); CAD/BIM lane \= export→artifact→release standardization | Integration contract: OIDC/SSO, canonical IDs, event surface, artifact capture, portability/export; Release Pack can include checksums/signatures | — | | **Kompendio** | Annexable sidecars: **Keycloak (OIDC)**; **MinIO or SeaweedFS**; **OpenSearch**; **HedgeDoc / Etherpad / OnlyOffice / Collabora**; **InvenTree / Part-DB / PartKeepr**; **FreeCAD (headless/CLI)**, **OpenSCAD**, **SolveSpace**; web viewers (**Three.js-based**, **IFC.js**) | Integration modes: link-only, evidence capture, artifact pinning, connector (sidecar) | Catalogs/libs/dbs tracked as references (examples): TraceParts-like, PARTcommunity (CADENAS)-like, 3D ContentCentral-like, GrabCAD-like; KiCad libs, SnapEDA-like, Octopart-like; BIMobject-like, NBS-like; MatWeb-like; ISO/ASME/DIN-like; NIST/USDA-like | ## ethiKos (upgrade track) | Area | Annexed (integrated sidecars) | Mimicked (pattern sources) | Core stack \+ binding protocols | | :---- | :---- | :---- | :---- | | **Kintsugi** | **OpenSlides** (optional), **Your Priorities** (optional), **All Our Ideas** (optional) | Polis (incl. PCA \+ clusters), Consider.it (+ Kialo patterns), CitizenOS patterns, Loomio (+ Smart Vote), Decidim \+ CONSUL, LiquidFeedback, DemocracyOS | Django monolith \+ Insights; **Celery \+ Redis**; **API \+ JWT SSO**; **Smart Vote** as voting truth source | **Kompendio (TBD)** ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kintsugi-upgrade-plan-v1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: bebcd4a16c40907bb0c9816973e07f9718ee0e416b46248550479391f6ecda91 CONTENT_BYTES: 18352 ================================================================================================ # Konnaxion v14 — KonnectED Upgrade \- Kintsugi ## **KonnectED as a Unified Learning, Evaluation & Credentialing Engine** **(Mimicking & Integrating Best-in-Class Open Learning Platforms)** **\#kinstugi edition — harmonizing the best open learning & credentialing patterns into one orchestrated flow** **Author:** Réjean McCormick **Date:** 2026-01-28 **Status:** Public plan v1 (pre-code) **Purpose:** explain what’s being built, why it matters, and exactly what is **mimicked vs annexed** from leading open-source learning platforms—before implementation. --- ## **1\. Executive Summary** This update transforms **Konnaxion’s KonnectED** from a learning library \+ certification area into a **full-spectrum competence engine**—combining: * **Content delivery** * **Structured practice** * **Formal evaluation** * **Credential issuance** * **Post-training performance measurement** Instead of merging external platforms directly, Konnaxion adopts a **“Mimic vs Annex” strategy**: * **Mimic** when codebases are heavy, strongly copyleft, or architecturally dominating * **Annex** when components are modular, standards-based, and safely isolated as sidecars The result: **Konnaxion becomes a meta-learning platform that orchestrates the best open learning patterns without inheriting technical debt, UI fragmentation, or uncontrolled licensing spillover.** ## **2\) Why this upgrade exists** Training platforms fail for structural reasons: * Learning content is fragmented across tools and formats. * “Completion” is treated as success, while real performance change is not measured. * Assessments are either too weak (MCQ-only) or too heavy (proctoring-only), with no middle path. * Credentials are issued as PDFs with no portable verification layer. * Organizations end up trapped in vendor ecosystems, unable to move their learning records. **KonnectED vNext** upgrades the platform into a closed loop: 1. **Learn** (content \+ practice) 2. **Measure** (assessment \+ feedback \+ telemetry) 3. **Validate** (peer/expert review where needed) 4. **Certify** (verifiable credentials) 5. **Follow-up** (does performance actually improve?) The goal is not “more features.” It is to make learning **accountable and portable**—without surrendering sovereignty to proprietary stacks. ## **3\. Strategic Principle: Mimic vs Annex** ### **Mimic (Native Re-Implementation)** Used when: * License is **GPL/AGPL** and the component cannot be cleanly isolated * Stack is mismatched or introduces a second “platform shell” * Feature scope is broad (full LMS / full assessment suite) and would subsume KonnectED ### **Annex (Sidecar / Optional Integration)** Used when: * License is **MIT / BSD / Apache** (or weak copyleft with clean isolation) * Component is standards-based (**OIDC, LTI 1.3, xAPI, Open Badges**) * Integration accelerates delivery while Konnaxion remains the orchestrator ## **4\) The core architecture principle: many learning tools, one common “evidence layer”** KonnectED already has two strong pillars: * **Knowledge** (collaborative learning library \+ course player) * **CertifiKation** (paths \+ evaluation \+ peer validation \+ certificates \+ portfolios) The upgrade principle is to integrate best-in-class open-source tools as bounded sidecars, while keeping one stable internal truth: ### **The Competence Evidence Layer (CEL)** Everything (courses, quizzes, rubrics, surveys, peer reviews, attendance, artifacts) is normalized into a consistent internal record so it can be: * audited, * compared across courses, * reused for credential verification, * exported to external ecosystems (LMS/HR, registries), * analyzed for actual post-training impact. This avoids the trap of “one tool per problem” and instead creates **one reading layer for many inputs**. ## **5\) The Competence Evidence Layer (explained simply)** Each learning signal becomes an **Evidence Item** with a predictable structure: * **who:** learner (and optionally assessor/mentor) * **what:** resource / activity / skill / assessment * **when:** timestamp \+ session context * **result:** score, rubric outcome, pass/fail, confidence * **artifact:** file or link (essay, video, project, code, portfolio object) * **provenance:** which tool produced it (native KonnectED / external sidecar) * **verification:** automated, peer-approved, or expert-approved This enables two critical guarantees: * **Portability:** exportable learning records (xAPI / Open Badges profiles) * **Legitimacy:** auditable proof of how a certificate was earned ## **6\) Cohort lenses: results that can be “read” responsibly** KonnectED should support cohort filters that clarify outcomes without distorting them: * Organization / program cohort * Region / language * Role (learner / mentor / assessor) * Skill level bands (beginner → advanced) * Verified cohorts (credentialed assessors, approved trainers) This makes it possible to ask: * “Did cohort A improve more than cohort B?” * “Which skills remain weak after the training?” * “Where is training working, and where is it performative?” ## **7\. Source Platforms & How Konnaxion Uses Them** ### ### **A. Moodle — Course & Program Scaffolding (LMS patterns)** **Status:** MIMICKED (default) / ANNEX (optional if GPL is acceptable as a separate service) **What we copy:** * Course → module → activity structure * Gradebook semantics (attempts, partial credit, completion rules) * Cohort \+ role patterns (learner, instructor, reviewer) **What Konnaxion adds:** * Keep the authoritative learning graph in KonnectED (KnowledgeResource \+ LearningProgress) * Route all external identifiers through **InteropMapping** to avoid dual-truth * Normalize outputs into **Evaluation.metadata** (single evidence format) **Result:** KonnectED gains mature LMS ergonomics without becoming “another LMS.” ### ### **B. H5P — Interactive Learning Objects** **Status:** ANNEX (recommended) **What we copy:** * Interactive content types (interactive video, branching scenarios, drag/drop, quizzes) * Reusable content object lifecycle (author → publish → embed → version) **What Konnaxion adds:** * Treat each H5P object as a KnowledgeResource (type=lesson/quiz) * Track completion in LearningProgress * Capture events into Evaluation.metadata and/or xAPI for unified analytics * Moderation \+ co-creation governance around content objects **Result:** Fast authoring of high-quality interactive learning units inside /course/\[slug\]. ### ### **C. TAO Community Edition — High-Stakes Assessment Patterns** **Status:** MIMICKED (default) / ANNEX (optional if AGPL is acceptable as a separate service) **What we copy:** * Item bank → test assembly → delivery → scoring pipeline * Exam session patterns (time windows, attempt rules, audit trails) * Rubric-driven scoring \+ structured result export **What Konnaxion adds:** * Unify scoring into Evaluation.raw\_score \+ Evaluation.metadata * Keep certification rules in CertificationPath (thresholds, cooldowns, peer validation) * Expose exams through /certs while keeping one identity/RBAC model **Result:** KonnectED gets certification-grade assessment architecture (not just MCQs). ### **D. SQL LRS (xAPI) — Learning Record Store & Evidence Ledger** **Status:** ANNEX (recommended) **What we copy:** * xAPI statement storage for fine-grained learning/evaluation events * Standard event vocabulary across tools (course player, authoring, assessment) **What Konnaxion adds:** * A **KonnectED Evidence Gateway** emitting xAPI during: progress, quizzes, peer validations, certificate issuance * Roll-up analytics into Insights dashboards (growth, retention, practice-to-performance) * Keep minimal OLTP mirrors (Evaluation \+ LearningProgress) for core UX; LRS is the detailed ledger **Result:** A standards-based event backbone enabling performance measurement after training. ### ### **E. Open Badges (1EdTech) \+ Badgr-style issuance — Verifiable Credentials** **Status:** MIMICKED (default) / ANNEX (optional sidecar issuer if acceptable) **What we copy:** * Badge classes \+ assertions (issuer, criteria, evidence links) * Public verification and portable credential sharing **What Konnaxion adds:** * Map Certificate records to Open Badges exports (JSON) * Attach Portfolio artifacts \+ Evaluation evidence as badge evidence URLs * InteropMapping entries for external registries and verification endpoints **Result:** Credentials become portable and verifiable outside Konnaxion, without rewriting the core credential model. ### **F. Safe Exam Browser (SEB) — Secure Exam Delivery** **Status:** ANNEX (recommended) **What we copy:** * Locked-down exam client patterns (restrict apps/web, enforce environment constraints) * Exam configuration \+ session monitoring patterns (SEB-style) **What Konnaxion adds:** * Tie SEB session identifiers to ExamAttempt/Evaluation metadata for audit trails * Policy-controlled activation only for high-stakes CertificationPath steps * Optional proctor workflow hooks (human review → PeerValidation) **Result:** Secure-mode certification exams without building a browser. ### ### **G. Kolibri — Offline-First Learning Distribution** **Status:** ANNEX (recommended) **What we copy:** * Offline channels and device-friendly content sync patterns * Local-first distribution model (portable bundles, low-connectivity deployments) **What Konnaxion adds:** * Reuse KonnectED’s offline packaging schedule and map selections to Kolibri channels * InteropMapping for content IDs so offline completions reconcile back into LearningProgress/Evaluation * Localized catalogs (language \+ cohort filters) **Result:** KonnectED becomes deployable in low-connectivity environments with a single source of truth. ### **H. Keycloak — Identity, SSO, and Cohort/Roles** **Status:** ANNEX (recommended) **What we copy:** * OIDC/SAML SSO patterns for institutions * Group/role management aligned with cohorts and evaluators **What Konnaxion adds:** * Map Keycloak groups → Konnaxion RBAC roles (learner/instructor/peer validator) * Use Keycloak for enterprise SSO while preserving Konnaxion JWT/RBAC enforcement * Cohort claims feed analytics filters (program, region, org, role) **Result:** Institutional onboarding without a parallel identity system. ### ### **I. OpenSearch — Unified Search Across Learning Assets** **Status:** ANNEX (recommended) **What we copy:** * Search indexing for heterogeneous content (lessons, resources, programs, badges) * Faceted discovery (tags, type, language, cohort) **What Konnaxion adds:** * Index KnowledgeResource \+ CertificationPath \+ Certificate metadata for cross-module discovery * Keep Postgres search as fallback; use OpenSearch for scale and relevance tuning * Expose search in /learn with cohort/language filters **Result:** Discoverability scales as the library becomes large. ### **J. SeaweedFS (S3-compatible object storage) — Evidence & Media Storage** **Status:** ANNEX (recommended) **What we copy:** * Object-store semantics for large evidence artifacts (S3 API) * Separation of binary evidence from relational records **What Konnaxion adds:** * Store artifacts referenced by Portfolio items and Evaluation.metadata (submissions, rubrics, media) * Immutable-by-default evidence links for auditability (versioned objects) * Pluggable deployments (SeaweedFS default; allow MinIO-style installs if desired) **Result:** Serious certification workflows get a clean evidence storage backbone. ## ## ## **8\) The KonnectED pipeline (Merged Plan v1)** ### **Stage 0 — Capability Intake & Path Selection** **Job:** turn “I want to learn X” into a guided path that produces evidence. **What happens** * select a Certification Path (program) * define baseline self-assessment (optional) * set intended outcomes (skills \+ performance indicators) **Inspired by / optionally integrated** * Moodle program/course structure patterns * LimeSurvey (baseline questionnaires) --- ### **Stage 1 — Course Assembly (Library → Learning Path)** **Job:** assemble coherent learning experiences from the Knowledge Library. **Mechanics** * Knowledge resources become lessons (curated sequences) * contributors can co-create updates and improvements * course player tracks progress and completion **Integrated (best open-source options)** * H5P (interactive learning objects embedded inside lessons) * Moodle (optional authoring \+ gradebook sidecar when needed) **Notes** * KonnectED remains the canonical catalog (/learn) and player (/course/\[slug\]) * External tools act as activity engines, not the truth store --- ### **Stage 2 — Practice & Formative Checks (low-stakes measurement)** **Job:** ensure learners get feedback early, before high-stakes evaluation. **Mechanics** * micro-quizzes * interactive exercises * reflection prompts * practice submissions (artifacts) **Integrated (best open-source options)** * H5P * TAO Community Edition (when stronger item types are needed) --- ### **Stage 3 — Summative Evaluation (high-stakes when required)** **Job:** generate defensible assessment outcomes. **Mechanics** * timed exams, item banks, rubrics * secure exam mode when needed * capture results into Evaluation \+ metadata **Integrated (best open-source options)** * TAO Community Edition * Safe Exam Browser (optional lockdown mode) --- ### ### **Stage 4 — Validation & Certification (from score → credential)** **Job:** convert evidence into a credential that is portable and verifiable. **Mechanics** * automated evaluation pass/fail (threshold \+ retry policies) * peer/expert validation for artifact-based competencies * certificate issuance \+ portfolio attachment **Integrated (best open-source options)** * Open Badges (standard for verifiable digital credentials) * Badgr Server / EduBadges Server (optional issuer sidecar) **Notes** * KonnectED keeps its internal Certificate model as operational truth * Open Badges becomes the interoperability/export format --- ### **Stage 5 — Post-Training Performance Follow-Up (the missing piece)** **Job:** measure whether learning transfers into real performance. **Mechanics** * scheduled follow-up surveys * re-assessment after a delay * evidence of application (work samples, outcomes, peer endorsements) * cohort dashboards: before vs after **Integrated (best open-source options)** * LimeSurvey (follow-up instruments \+ longitudinal surveys) * Learning Locker / SQL LRS (xAPI LRS for standardized telemetry) **Output** * “Learning Impact” dashboards per program, cohort, and skill * visible proof that training was effective (or wasn’t) --- ## ## **9\) Mimicked vs Annexed: what comes from where** ### **MIMICKED (native inside KonnectED)** * Course/player patterns: progress tracking, resume, completion * Certification lifecycle: paths → evaluations → peer validation → certificates * Portfolio logic: achievements \+ artifacts attached to skills * Interoperability mapping model: one canonical mapping layer (InteropMapping) * Competence Evidence Layer normalization (Evidence Items → Evaluation/Portfolio/LRS) ### **ANNEXED (bounded sidecars, API-first)** * Moodle: LMS authoring \+ gradebook workflows (optional) * H5P: interactive lesson objects * TAO Community Edition: assessment lifecycle \+ item banks (optional) * xAPI LRS: Learning Locker or SQL LRS (evidence ledger) * LimeSurvey: baseline \+ follow-up evaluation instruments * Safe Exam Browser: secure exam mode (optional) * Open Badges issuer: Badgr/EduBadges (optional) * Keycloak: enterprise identity/SSO (recommended) * OpenSearch: large-scale discovery (recommended) * SeaweedFS/MinIO: artifact/evidence storage (recommended) ## ## ## ## **10\) What stays stable (Konnaxion integrity)** This upgrade does **not** require merging foreign codebases into the core stack. **Core Konnaxion remains:** * Next.js frontend * Django backend (KonnectED app namespace) * Postgres operational store * Celery for jobs (packaging, scoring, exports, analytics refresh) * unified auth \+ RBAC * Insights as read-optimized dashboard layer **External apps are:** * never merged into core * mimicked or isolated as sidecars * bound via standards: **OIDC (SSO), LTI 1.3 (tool launch), xAPI (event capture), Open Badges (credential export)** \+ InteropMapping for identifiers ## **11\) Why publish Plan v1 before coding** Because education platforms fail most often at the architecture level, not the UI level. This plan is published early so builders and partners can: * challenge missing evaluation edge cases * propose better evidence standards * suggest interoperability targets (registries/LMS/HR) * catch design debt before it ships ## ## ## ## **12\) Public Credit & Positioning** KonnectED will explicitly credit inspirations and integrated projects, for example: *“KonnectED builds on open learning innovations from Moodle (LMS patterns), H5P (interactive learning objects), TAO (assessment architecture), xAPI/LRS tooling, Open Badges ecosystems, Kolibri (offline learning), Keycloak (identity), OpenSearch (discovery), and open object storage for evidence portability.”* This frames Konnaxion as: **An orchestrator of the best open learning innovations — not a clone.** ## **13\) Outcome: What KonnectED Becomes** KonnectED evolves into: * A **Learning Engine** (library \+ course player \+ interactive authoring) * An **Assessment Engine** (formative \+ summative, rubric-based, secure-mode optional) * A **Credential Engine** (certificates \+ portable verifiable exports) * A **Competence Evidence Engine** (xAPI ledger \+ portfolio artifacts \+ audit trails) * An **Offline-Capable Deployment** (packaging \+ sync patterns for low-connectivity contexts) **In short:** **KonnectED becomes a full-stack platform for learning accountability, measurable competence, and verifiable certification.** ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/KonnectED-kompendio-upgrade-plan-v1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: a0aa14b54d11363de282743f327ddfbb02d8ab37daea760f9a1df66fa6ae6621 CONTENT_BYTES: 8254 ================================================================================================ # **KonnectED Upgrade \- Kompendio (Plan v1)** **Status:** Draft **Module:** KonnectED **Submodule:** Kompendio (3rd submodule alongside Knowledge \+ CertifiKation) **Purpose:** Make the KonnectED loop **portable, governable, and reproducible** by explicitly mapping the *reference standards, tools, libraries, and infrastructures* KonnectED uses (or mimics), and by publishing **versioned Reference Charts** and **integration fiches**. --- ## ## **1\) Role (why it exists)** KonnectED vNext targets a full learning loop: **Learn → Measure → Validate → Certify → Follow-up** Kompendio is the layer that makes this loop **explicit and reusable**: * It documents the **reference tech stack** (standards \+ OSS sidecars \+ reference ecosystems). * It states clearly **how** KonnectED relates to each item: **Mimic** or **Annex**. * It outputs **publishable, versioned, reusable Reference Charts** (builder-grade, not marketing docs). Core principle: **many tools are possible, but there is one reading layer** — the **Competence Evidence Layer (CEL)**. ## ## **2\) Integration rule (Mimic vs Annex)** Kompendio is not “a link list”. It is an **integration repertory**. Each entry must answer: *how does KonnectED use this reference?* * **Mimic** Replicate the pattern (UX / flow / model) without importing the entire platform. * **Annex** Connect an **isolated sidecar**, standards-based, when it accelerates delivery *without capturing sovereignty*. Interop “backbone” standards to treat as first-class references: * **OIDC**, **LTI 1.3**, **xAPI**, **Open Badges** ## **3\) What Kompendio contains (three shelves)** ### **Shelf A — Backbone standards (interop & portability)** These are **mandatory** because they define what “portable” means: * **OIDC (SSO)** — single sign-on baseline for sidecars * **LTI 1.3 (+ Advantage services)** — tool launch \+ grade/roster/deep linking [1EdTech LTI](https://www.1edtech.org/standards/lti?utm_source=chatgpt.com) * **xAPI** — learning event capture / evidence events [xAPI spec repo](https://github.com/adlnet/xAPI-Spec?utm_source=chatgpt.com) * **cmi5** — xAPI profile for LMS-style launch/tracking [cmi5 spec](https://aicc.github.io/CMI-5_Spec_Current/?utm_source=chatgpt.com) * **Open Badges 3.0** — verifiable credential export (portable credentials) [Open Badges 3.0](https://www.imsglobal.org/spec/ob/v3p0?utm_source=chatgpt.com) **v1.1 references to inventory early (comparison standards):** QTI, Common Cartridge / Thin CC, OneRoster, Caliper, SCORM legacy. [1EdTech specifications](https://www.1edtech.org/specifications?utm_source=chatgpt.com) ### **Shelf B — Activity engines (tools that produce evidence)** These are the “best OSS options” already aligned with the KonnectED Kintsugi posture (sidecars or patterns): * **Moodle** — LMS patterns (sometimes annexed) * **H5P** — interactive learning objects / activities * **TAO Community Edition** — high-stakes assessment patterns * **Safe Exam Browser (SEB)** — optional secure exam mode * **LimeSurvey** — baseline \+ follow-up measurement * **xAPI LRS** (Learning Locker / SQL LRS) — evidence ledger / learning record store * **Open Badges issuer** (Badgr / EduBadges) — optional issuance sidecar *(Kompendio entry for each must specify: Mimic vs Annex, what evidence it emits, and what KonnectED stores.)* ### **Shelf C — Sovereign infrastructure (packs, evidence, discovery)** These are the enabling components that make KonnectED portable and scalable: * **Keycloak** — recommended SSO (OIDC) * **OpenSearch** — discovery/search at scale * **SeaweedFS / MinIO (S3-compatible)** — artifact \+ evidence storage (snapshots, packs) ## ## ## **4\) Central object: Evidence (CEL)** Kompendio KonnectED is governed by the **Competence Evidence Layer (CEL)**: every learning signal becomes a normalized evidence object. Typical evidence sources: * quiz results * rubrics * peer validation * attendance/session signals * artifacts (files, projects, submissions) * follow-up outcomes CEL must be visible and consistent everywhere via a simple display structure: **who / what / when / result / artifact / provenance / verification** This becomes the common language across tools, charts, and credentials. ## ## ## **5\) What Kompendio publishes (deliverables)** ### **A) Reference fiches (one page per standard/tool)** Every fiche must answer: * **What it is for** in the Learn→Follow-up loop * **Mimic vs Annex** (explicit choice \+ rationale) * **What evidence it produces** (CEL mapping; xAPI; badges; artifacts) * **Constraints** (license, isolation requirements, dual-truth risks, ToS considerations) * **Canonical entrypoints** (spec/docs/repo/conformance pages) ### **B) Reference Charts (v1: 6 high-leverage charts)** 1. **Interop Chart** “How everything talks to everything”: OIDC / LTI 1.3 / xAPI / cmi5 / Open Badges [LTI](https://www.1edtech.org/standards/lti?utm_source=chatgpt.com) 2. **Assessment Ladder Chart** Formative → Summative → Secure mode (H5P / TAO / SEB) 3. **Credential Portability Chart** Internal certificate → Open Badges export → verification path [Open Badges 3.0](https://www.imsglobal.org/spec/ob/v3p0?utm_source=chatgpt.com) 4. **Evidence Pattern Chart (CEL)** What “defensible evidence” looks like \+ examples (quiz, rubric, artifact, peer validation) 5. **Follow-up Impact Chart** Measuring transfer/impact over time (baseline → follow-up → re-assess → artifacts) 6. **Sovereignty / Deployment Chart** Packs, offline/low connectivity, evidence storage, reproducibility, audit readiness ## ## ## **6\) Ratings (human-readable, decision-grade)** Kompendio rates references using dimensions that are understandable by builders and decision-makers: * **Interop quality** (standards supported \+ quality of implementation) * **Portability** (exports, packs, offline readiness) * **Auditability** (traceability, versioning, evidence links) * **Governance & longevity** (maturity, community, cadence) * **Sovereignty & dependencies** (vendor capture, ToS friction, isolation feasibility) * **Learning-outcomes fit** (does it help prove outcomes and impact?) Ratings should support two views: * **Raw score** (simple aggregate) * **Advisory score** (reserved for later domain-weighted logic) ## ## ## **7\) Prioritized backlog** ### **v1 “Ship” (minimum viable Kompendio)** * Kompendio repertory populated with: * Shelf A backbone standards * Shelf B activity engines * Shelf C sovereign infra * The 6 Reference Charts published and versioned * Simple lifecycle workflow: **Draft → Reviewed → Published/Trusted** * KonnectED integration requirement: Charts and fiches must be usable inside the **Knowledge \+ CertifiKation** flows. ### **v1.1 (evidence \+ interop extensions)** * Add comparison standards as references (even if not integrated): QTI, Common Cartridge/Thin CC, OneRoster, Caliper, SCORM [1EdTech specifications](https://www.1edtech.org/specifications?utm_source=chatgpt.com) * Dispute \+ revalidation workflow (challenge → review → update/new version) * “Used in program” attestations (where it’s actually used) ### **v2 (selective annex)** * Annex additional OSS modules only if: * clearly isolable * standards-compatible * improves outcomes without creating a second truth store Examples: portfolio/evidence sidecar, OSS classroom, OER publishing sidecar. ## ## ## **8\) Definition of Done (v1)** Kompendio KonnectED v1 is “done” when: * Backbone standards (OIDC, LTI 1.3, xAPI/cmi5, Open Badges) are covered by fiches \+ the Interop Chart. [LTI](https://www.1edtech.org/standards/lti?utm_source=chatgpt.com) * Each listed sidecar/tool (Moodle, H5P, TAO, LRS, LimeSurvey, Badges issuer, SEB, OpenSearch, SeaweedFS/MinIO, Keycloak) has a clear fiche: * Mimic vs Annex * evidence mapping to CEL * canonical entrypoints * The 6 charts are published, versioned, and usable across the Learn→Follow-up loop. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/docs/Technical-Reference/Kintsugi_Kompendio/SmartVote-EkoH-kintsugi-upgrade-v1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 1f436c903a7b029bddd7dff0d63794c2997732465e2167f1f613b3d2cc5adb2b CONTENT_BYTES: 7459 ================================================================================================ # **SmartVote / EkoH — Kintsugi v1** **Scope:** Upgrade SmartVote into a governance-grade “decision engine” while keeping **EkoH stable as the canonical registry** for expertise indicators \+ ethical multipliers. **Deployment posture:** Hybrid (SaaS \+ self-host / on-prem). --- ## **1\) What SmartVote and EkoH are (in your current architecture)** ### **EkoH (stays as-is: registry \+ audit)** EkoH already defines the canonical objects you need for weighting and explainability: * expertise domains \+ user expertise scores, ethics multiplier, configuration weights, contextual analysis logs, privacy settings, and score history/audit. ### **Smart Vote (single source of voting truth)** Smart Vote already defines: * Vote (raw\_value \+ weighted\_value), vote modalities, aggregated results, and cross-module mapping. And it’s positioned as the single source of voting truth in the platform integrity rules. ## **2\) What “Kintsugi” means here** Kintsugi is **bringing best open-source building blocks under one coherent roof—without merging everything into a monolith**. Key policy: **Mimic vs Annex**. Annex only when a sidecar can be isolated and won’t create licensing/UX/dual-truth problems; otherwise mimic the pattern natively. ## ## **3\) The target outcome** SmartVote becomes a “decision engine” that can drive: * **formal decision mechanics** (time-boxed, thresholded) and **outcome publication**, * embedded inside a broader civic workflow (consultation → drafting → voting → execution \+ accountability timelines). ## **4\) Core principles (ported from the Kintsugi plans)** 1. **One-roof experience** (one identity, consistent permissions). 2. **No dual truth** (canonical IDs \+ lifecycle inside Konnaxion, even if sidecars exist). 3. **Integration contract for any annexed component**: identity/access, canonical IDs, events, portability/export. 4. **Architectural integrity**: external apps are mimicked or isolated; never merged into core. 5. **Hybrid by default**. ## ## ## **5\) “Best of each” blueprint (what to mimic vs annex)** ### **A) Mimic Decidim (process \+ legitimacy scaffolding)** **Mimic these patterns:** * participation workflows and the **consultation → drafting → voting → execution** pipeline, plus public accountability timelines. **Where it lands in SmartVote/EkoH:** * a **Process / Consultation layer** above SmartVote that controls phases, eligibility windows, and what gets published when. ### **B) Mimic LiquidFeedback (delegation \+ voting theory)** **Mimic these patterns:** * delegated voting logic \+ “vote flow mathematics”. **What you add (your differentiator):** * domain-specific delegation \+ ethical multiplier governance. ### **C) Mimic Decidim Awesome-style governance knobs (scheme registry)** You cloned decidim-module-decidim\_awesome because it’s useful as a **reference** for “admin-selectable voting mechanics” and “weight breakdown surfaces”. In SmartVote, implement the *idea* as: * a **VotingScheme registry** (per consultation/component) * **validators** (who can vote, allowed ballots, weight constraints) * **result presentation adapters** (charts, breakdowns, export) (Implementation stays native to your stack to avoid platform-shell contamination; consistent with Mimic vs Annex.) ## ## ## **6\) SmartVote/EkoH architecture v1** ### **6.1 Canonical modules** 1. **EkoH Registry (stable)** * ExpertiseCategory, UserExpertiseScore, UserEthicsScore, ScoreConfiguration, ScoreHistory, privacy \+ context logs. 2. **SmartVote Engine (upgrade focus)** * Vote (raw+weighted), VoteModality, VoteResult, IntegrationMapping. 3. **Process / Consultation Orchestrator (new)** * Implements the “consultation → drafting → voting → execution” pipeline as first-class objects. 4. **Insights surfaces (read-optimized)** * Public dashboards \+ transparency pages (aligned with “outcome publication” in decision stage). ### **6.2 What SmartVote must add to become governance-grade** * **Policy & phase model** (open/close windows, quorum/threshold, tie-break policy) * **Tally backends by modality** (don’t reduce everything to a single sum) * **Explainability endpoints** (weight breakdown, without leaking private data) * **Export bundles** (portability contract) These are direct extensions of the integration/portability contract. ## ## ## **7\) End-to-end pipeline (SmartVote/EkoH version)** This is the SmartVote-focused analogue of the ethiKos pipeline stages. ### **Stage 0 — Setup (Process authoring)** * Define consultation/process, phases, rules, eligible cohorts. ### **Stage 1 — Eligibility \+ Weight snapshot (EkoH)** * Pull expertise \+ ethics multiplier; apply privacy settings; record weight explanation links. ### **Stage 2 — Decision window (Casting)** * Votes recorded with raw \+ weighted values (canonical). ### **Stage 3 — Tally** * Run the correct tally per modality (approval/rating vs ranking/preferential vs delegation-enabled). ### **Stage 4 — Outcome publication** * Publish formal results \+ transparency views (aligned with “formal outcome publication”). ### **Stage 5 — Execution \+ accountability** * Link adopted outcomes to “impact tracking” / follow-up actions (execution pipeline). ## ## **8\) Delivery plan (v1 milestones)** ### **Milestone 1 — “Truth \+ Explainability”** **Deliverables** * GET /weights/explain?user\&context returns: category scores, ethics multiplier, config version, and final weight (no private fields). * ScoreHistory enforced for any recalculation/config change. * Vote writes always store both raw\_value and weighted\_value. ### **Milestone 2 — “Process shell”** **Deliverables** * Process/Consultation objects implementing the pipeline structure. * Phase gating (open/close) that controls voting availability. * Public timeline objects for accountability (who/what/when), consistent with “public accountability timelines”. ### **Milestone 3 — “Modalities done right”** **Deliverables** * For each VoteModality, define: * ballot schema, * tally engine, * export format, * deterministic tie-break. * Keep VoteResult for simple totals, but store modality-specific outputs (JSON snapshots) for complex tallies. ### **Milestone 4 — “Delegation (Liquid patterns)”** **Deliverables** * Delegation logic (domain-scoped) with ethics governance hooks. * Anti-capture constraints (limits, decay, transparency views). ### ### **Milestone 5 — “Cross-module embed”** **Deliverables** * IntegrationMapping-based embedding so SmartVote can be used in other modules without duplicating vote logic. ## **9\) Decision on annexing (what you should *not* do in v1)** * **Do not annex Decidim or Awesome as running sidecars** in v1: they are “platform shells” and violate the “no contamination” posture. * **LiquidFeedback core** should be treated as a *reference implementation* first; annex only if you can isolate it behind the integration contract (events \+ portability \+ canonical IDs), otherwise mimic the math in your own tally layer. ## **10\) What stays stable (explicit)** * EkoH remains the expertise \+ ethics registry and audit backbone. * SmartVote remains the single source of voting truth; external inspirations do not become your core runtime. ================================================================================================ FILE: _BUG_HARVEST_REVIEW/LevelUpDiag/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 4c5868fff56fa849545f3ee1a9d208e2717d3c7409e066ec07b09a518d6f825b CONTENT_BYTES: 3838 ================================================================================================ # Konnaxion LevelUpDiag — Upgraded v3 This package upgrades the Konnaxion LevelUpDiag Mega Pack onto the evolved LevelUpDiag engine while preserving the Konnaxion-specific diagnostic domains and test order. ## Konnaxion target auto-detection When `target_repo_root` is `auto`, LevelUpDiag supports both common layouts: ```text <Konnaxion repo>/LevelUpDiag/ ``` and the historical workspace layout: ```text <workspace>/ ├── LevelUpDiag/ └── Konnaxion/ ├── frontend/ └── backend/ ``` It scores Konnaxion markers (`frontend`, `backend`, `package.json`, `manage.py`) and selects the correct target automatically. ## What is preserved - Exact Konnaxion taxonomy N00..N11. - Existing Django, Next, TypeScript, ESLint, Jest, OpenAPI, Playwright, Celery/Redis, Capsule Manager and deployed-runtime diagnostics. - Static source audit: double `/api/api`, forbidden legacy namespaces, CSRF-risk and unmapped endpoint checks. - `.venv` Python autodetection and `corepack pnpm` fallback. - Remote diagnostics disabled by default and no destructive deployment/restart/restore operations. - Original ordered campaigns. ## What is upgraded - Process isolation: every level runs in its own Python process. - Explicit sequential campaign execution. Konnaxion test order is never lost to parallel scheduling. - Campaign/expected-level metadata propagated into N00 session state. - N11 correlates only the levels expected by the active campaign. - Current-only evidence retention: old LevelUpDiag `runs`, `logs`, `diagnostics`, `latest`, `current` and stale Konnaxion session evidence are purged at the start of a campaign. - Bounded/redacted command output, `shell=False`, timeouts and progress heartbeat. - Modern manifest/config schemas while accepting the previous local Konnaxion config schema during migration. ## Primary campaign ```powershell python levelupdiag.py run connection-debug ``` Its exact sequence is: ```text N00 -> N01 -> N02 -> N03 -> N04 -> N05 -> N06 -> N11 ``` ## Recommended escalation sequence The existing Konnaxion workflow is preserved: ```text source-audit -> auth-debug -> connection-debug -> full-local ``` Run it automatically with: ```powershell python levelupdiag.py run-sequence recommended-debug ``` Each campaign still has its own N00 session and N11 final correlation. ## Configuration If the `levelupdiag/` directory is copied directly into the Konnaxion repo, the default `target_repo_root: "auto"` diagnoses its parent. For a standalone LevelUpDiag checkout, run the configuration script or set `target_repo_root` in `levelupdiag.config.local.json`. No application command is guessed outside the Konnaxion command defaults already encoded by this pack. ## Runtime evidence Only current evidence is retained: ```text <Konnaxion>/.levelupdiag/current/ <Konnaxion>/.levelupdiag/latest/ ``` No historical run archive is maintained by default. ## Console graphique de sélection Le root inclut maintenant `LEVELUPDIAG_CONSOLE.pyw`. Sous Windows, un double-clic ouvre une console graphique inspirée du modèle fourni : - sélection d'une campagne depuis le manifest ; - sélection manuelle de niveaux N00..N11 ; - presets Source audit, Auth debug, Connection debug et Full local ; - sortie du diagnostic en direct ; - arrêt du processus ; - ouverture directe du dossier de preuves `.levelupdiag/current`. La console lance le même moteur `levelupdiag.py`; elle ne duplique pas les tests. ## Nettoyage des alias historiques Les anciens alias `MegaPack` ont été retirés du root et sont supprimés lors d'un upgrade après sauvegarde : - `INSTALL_AND_CONFIGURE_KONNAXION_MEGAPACK.pyw` - `CONFIGURE_KONNAXION_MEGAPACK.ps1` - `INSTALL_MEGAPACK.ps1` Les noms LevelUpDiag v3 sont désormais les seules entrées d'installation/configuration conservées. ================================================================================================ FILE: backend/konnaxion/ethikos_20260903_131935_Dump/00_START_HERE.instructions.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 87a6cc1dccbc35fdf27fc36d62ed3ccd820c4e0abcc29cd54094ad403278b53d CONTENT_BYTES: 2624 ================================================================================================ # START HERE — Instructions for AI You are given a repository codedump split into multiple volume files. ## Goal Answer questions by opening the minimum necessary content. ## Format notes - Use `==== FILE_INDEX ====` first in each volume. - Search for `ENTRY` lines to locate file metadata quickly. - Then jump to `----- FILE BEGIN -----` with matching `path="..."`. - For large files, prefer `--- CHUNK BEGIN ---` blocks. ## AI navigation features When available, use these sections before reading full files: - `FILE DETAIL INDEX`: find exact file metadata, volume, line range, chunk ranges, and summary. - `SYMBOL INDEX`: locate classes, functions, and methods directly. - `IMPORT INDEX`: inspect dependencies before expanding to related files. - `PATCH TARGETS`: identify likely files to modify for common change types. - `line_ref`: full line range for a file. - `chunk_refs`: smaller line ranges for large files. Navigation rule: 1. Start from the master index if present. 2. Use `SYMBOL INDEX` when looking for a class, function, or method. 3. Use `IMPORT INDEX` when tracing dependencies. 4. Use `FILE DETAIL INDEX` to choose the smallest relevant file or chunk range. 5. Read only the needed file or chunk content. ## How to navigate this dump 1) Open `Code_snapshot_ethikos.zip` (single upload archive), then use `CODE_SNAPSHOT_MANIFEST.md` or the repository-relative paths to find the source file you need. Optional: use `Index.txt` to locate the relevant volume faster. 2) Pick the relevant volume file. 3) Use the per-volume index section to locate the path. 4) Read the exact file content or required chunks only. 5) Expand cautiously through imports, calls, or routes, 1–2 hops unless needed. ## Rules - Do NOT try to read the entire dump. - Prefer the master index, file indexes, summaries, and chunk references before opening full files. - Prefer docs, diagrams, and generated indexes when present. - When answering, cite file paths and the volume filename. - Preserve clean source content when copying code; ignore physically numbered lines unless line citations are needed. ## Files - Instructions this file: `00_START_HERE.instructions.md` - Master index: `Index.txt` - Volumes: - ethikos_20260903_131935_01_ROOT.txt — ROOT FILES - ethikos_20260903_131935_02_demo_import.txt — FOLDER: demo_import - ethikos_20260903_131935_03_tests.txt — FOLDER: tests - ethikos_20260903_131935_04_migrations.txt — FOLDER: migrations - ethikos_20260903_131935_05_management.txt — FOLDER: management ## ChatGPT upload helper - Single upload archive: `Code_snapshot_ethikos.zip` ================================================================================================ FILE: backend/locale/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c0a3e3896516b0c5526551fc06b6a3c58cd5cf9e1b810b2e848d68f6cd89e72f CONTENT_BYTES: 1627 ================================================================================================ # Translations Start by configuring the `LANGUAGES` settings in `base.py`, by uncommenting languages you are willing to support. Then, translation strings will be placed in this folder when running: ```bash docker compose -f docker-compose.local.yml run --rm django python manage.py makemessages --all --no-location ``` This should generate `django.po` (stands for Portable Object) files under each locale `<locale name>/LC_MESSAGES/django.po`. Each translatable string in the codebase is collected with its `msgid` and need to be translated as `msgstr`, for example: ```po msgid "users" msgstr "utilisateurs" ``` Once all translations are done, they need to be compiled into `.mo` files (stands for Machine Object), which are the actual binary files used by the application: ```bash docker compose -f docker-compose.local.yml run --rm django python manage.py compilemessages ``` Note that the `.po` files are NOT used by the application directly, so if the `.mo` files are out of date, the content won't appear as translated even if the `.po` files are up-to-date. ## Production The production image runs `compilemessages` automatically at build time, so as long as your translated source files (PO) are up-to-date, you're good to go. ## Add a new language 1. Update the [`LANGUAGES` setting](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-LANGUAGES) to your project's base settings. 2. Create the locale folder for the language next to this file, e.g. `fr_FR` for French. Make sure the case is correct. 3. Run `makemessages` (as instructed above) to generate the PO files for the new language. ================================================================================================ FILE: backend/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: dac04f29e1863559e19c57765fa2230912e30176a7c9ce25f55ea8bbccf7c9f0 CONTENT_BYTES: 3630 ================================================================================================ # Konnaxion Our Project [![Built with Cookiecutter Django](https://img.shields.io/badge/built%20with-Cookiecutter%20Django-ff69b4.svg?logo=cookiecutter)](https://github.com/cookiecutter/cookiecutter-django/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) License: MIT ## Settings Moved to [settings](https://cookiecutter-django.readthedocs.io/en/latest/1-getting-started/settings.html). ## Basic Commands ### Setting Up Your Users - To create a **normal user account**, just go to Sign Up and fill out the form. Once you submit it, you'll see a "Verify Your E-mail Address" page. Go to your console to see a simulated email verification message. Copy the link into your browser. Now the user's email should be verified and ready to go. - To create a **superuser account**, use this command: $ python manage.py createsuperuser For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users. ### Type checks Running type checks with mypy: $ mypy konnaxion ### Test coverage To run the tests, check your test coverage, and generate an HTML coverage report: $ coverage run -m pytest $ coverage html $ open htmlcov/index.html #### Running tests with pytest $ pytest ### Live reloading and Sass CSS compilation Moved to [Live reloading and SASS compilation](https://cookiecutter-django.readthedocs.io/en/latest/2-local-development/developing-locally.html#using-webpack-or-gulp). ### Celery This app comes with Celery. To run a celery worker: ```bash cd konnaxion celery -A config.celery_app worker -l info ``` Please note: For Celery's import magic to work, it is important _where_ the celery commands are run. If you are in the same folder with _manage.py_, you should be right. To run [periodic tasks](https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html), you'll need to start the celery beat scheduler service. You can start it as a standalone process: ```bash cd konnaxion celery -A config.celery_app beat ``` or you can embed the beat service inside a worker with the `-B` option (not recommended for production use): ```bash cd konnaxion celery -A config.celery_app worker -B -l info ``` ### Email Server In development, it is often nice to be able to see emails that are being sent from your application. For that reason local SMTP server [Mailpit](https://github.com/axllent/mailpit) with a web interface is available as docker container. Container mailpit will start automatically when you will run all docker containers. Please check [cookiecutter-django Docker documentation](https://cookiecutter-django.readthedocs.io/en/latest/2-local-development/developing-locally-docker.html) for more details how to start all containers. With Mailpit running, to view messages that are sent by your application, open your browser and go to `http://127.0.0.1:8025` ### Sentry Sentry is an error logging aggregator service. You can sign up for a free account at <https://sentry.io/signup/?code=cookiecutter> or download and host it yourself. The system is set up with reasonable defaults, including 404 logging and integration with the WSGI application. You must set the DSN url in production. ## Deployment The following details how to deploy this application. ### Docker See detailed [cookiecutter-django Docker documentation](https://cookiecutter-django.readthedocs.io/en/latest/3-deployment/deployment-with-docker.html). ================================================================================================ FILE: docs/demo-scenarios/ethikos/ETHIKOS_DEMO_IMPORTER.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 9b3d3e879682659f09e21addd9858230dd0351f3eafae411dfaccdbeee11baaa CONTENT_BYTES: 20852 ================================================================================================ # ethiKos Demo Importer — Integrated Tool Documentation ## 1. Purpose The **ethiKos Demo Importer** is an internal admin-only tool that imports demo scenario data from JSON into ethiKos. It allows controlled demo customization without manually editing the database and without creating a complex CMS. The tool imports: ```txt demo actors categories topics stances arguments consultations consultation votes impact items ``` The JSON file is the source of truth. The app only validates, previews, imports, and resets the scenario. --- ## 2. Core concept ```txt Demo JSON file → Preview / validation → Import into ethiKos database → Display through existing ethiKos pages → Reset by scenario_key when needed ``` The importer does **not** create a new ethiKos module. It stays inside: ```txt Backend: konnaxion.ethikos.demo_import Frontend: /ethikos/admin/demo-importer API: /api/ethikos/demo-scenarios/ ``` --- ## 3. Canonical variables Use these values everywhere. ```txt Schema version: ethikos-demo-scenario/v1 Frontend route: /ethikos/admin/demo-importer Backend API base: /api/ethikos/demo-scenarios/ Backend endpoints: POST /api/ethikos/demo-scenarios/preview/ POST /api/ethikos/demo-scenarios/import/ POST /api/ethikos/demo-scenarios/reset/ Backend package: konnaxion.ethikos.demo_import Tracking model: DemoScenarioImport Scenario identity field: scenario_key Import mode field: mode Default import mode: replace_scenario Allowed modes: replace_scenario append_scenario Demo user prefix: demo_ Demo topic title prefix: [DEMO] Feature flag: ETHIKOS_DEMO_IMPORTER_ENABLED ``` --- # 4. File inventory ## Backend package ```txt backend/konnaxion/ethikos/demo_import/__init__.py backend/konnaxion/ethikos/demo_import/schema.py backend/konnaxion/ethikos/demo_import/importer.py backend/konnaxion/ethikos/demo_import/serializers.py backend/konnaxion/ethikos/demo_import/views.py backend/konnaxion/ethikos/demo_import/urls.py ``` ## Backend tracking model ```txt backend/konnaxion/ethikos/models_demo.py backend/konnaxion/ethikos/migrations/00XX_demo_scenario_import.py ``` ## Frontend ```txt frontend/app/ethikos/admin/demo-importer/page.tsx frontend/features/ethikos/demo-importer/types.ts frontend/features/ethikos/demo-importer/api.ts frontend/features/ethikos/demo-importer/DemoImporterPanel.tsx frontend/features/ethikos/demo-importer/JsonScenarioEditor.tsx frontend/features/ethikos/demo-importer/ImportResultPanel.tsx ``` ## Demo JSON scenarios ```txt docs/demo-scenarios/ethikos/public_square_demo.json docs/demo-scenarios/ethikos/ai_in_schools_demo.json docs/demo-scenarios/ethikos/community_budget_demo.json ``` ## Tests ```txt backend/konnaxion/ethikos/tests/test_demo_import_schema.py backend/konnaxion/ethikos/tests/test_demo_importer.py backend/konnaxion/ethikos/tests/test_demo_import_api.py ``` --- # 5. Backend file responsibilities ## `backend/konnaxion/ethikos/demo_import/__init__.py` Purpose: ```txt Marks demo_import as a Python package. Documents the package purpose. No runtime logic. ``` Contains: ```python """ ethiKos Demo Importer. Internal admin-only utilities for validating, previewing, importing, and resetting demo scenarios from JSON files. Canonical API base: /api/ethikos/demo-scenarios/ Canonical schema version: ethikos-demo-scenario/v1 """ ``` --- ## `backend/konnaxion/ethikos/demo_import/schema.py` Purpose: ```txt Defines shared constants. Validates demo scenario JSON. Returns structured validation errors. Protects the importer from invalid references. ``` Owns these constants: ```python SCHEMA_VERSION = "ethikos-demo-scenario/v1" DEFAULT_IMPORT_MODE = "replace_scenario" FEATURE_FLAG_NAME = "ETHIKOS_DEMO_IMPORTER_ENABLED" DEMO_USERNAME_PREFIX = "demo_" DEMO_TOPIC_TITLE_PREFIX = "[DEMO]" STANCE_MIN = -3 STANCE_MAX = 3 ``` Main function: ```python def validate_demo_scenario(data: dict) -> list[dict]: ... ``` Returns: ```json [ { "path": "stances[0].value", "message": "Stance value must be an integer from -3 to +3" } ] ``` If the list is empty, the JSON is valid. --- ## `backend/konnaxion/ethikos/demo_import/importer.py` Purpose: ```txt Main service layer. Imports validated JSON into ethiKos. Supports preview, import, reset, and object tracking. ``` Main functions: ```python def validate_and_preview_ethikos_demo_scenario(data: dict) -> dict: ... def import_ethikos_demo_scenario( data: dict, *, imported_by=None, dry_run: bool = False, ) -> dict: ... def reset_ethikos_demo_scenario( scenario_key: str, *, reset_by=None, ) -> dict: ... def summarize_scenario(data: dict) -> dict: ... def track_imported_object( *, scenario_key: str, object_type: str, obj, imported_by=None, object_label: str = "", ) -> None: ... def delete_tracked_scenario_objects( scenario_key: str, ) -> list[dict]: ... ``` Core import order: ```txt 1. Validate JSON 2. If dry_run=True, return summary only 3. If mode=replace_scenario, reset existing tracked data 4. Import actors 5. Import categories 6. Import topics 7. Import stances 8. Import arguments 9. Import consultations 10. Import consultation votes 11. Import impact items 12. Track every created object 13. Return summary ``` Important rule: ```txt The importer writes source demo data. It does not hand-edit Smart Vote readings. Readings/results should be recomputed or derived from imported facts. ``` --- ## `backend/konnaxion/ethikos/demo_import/serializers.py` Purpose: ```txt Defines DRF request/response serializer classes. Keeps API contract stable. Allows frontend and tests to rely on fixed response shapes. ``` Serializer classes: ```python DemoScenarioPreviewSerializer DemoScenarioImportSerializer DemoScenarioResetSerializer DemoImportErrorSerializer DemoImportSummarySerializer DemoImportResponseSerializer ``` Minimum reset request: ```json { "scenario_key": "public_square_demo" } ``` --- ## `backend/konnaxion/ethikos/demo_import/views.py` Purpose: ```txt Defines API views for preview, import, and reset. Checks feature flag. Restricts access to admin users. Delegates all business logic to importer.py. ``` View classes: ```python EthikosDemoScenarioPreviewView EthikosDemoScenarioImportView EthikosDemoScenarioResetView ``` Permission: ```python permission_classes = [permissions.IsAdminUser] ``` Feature flag guard: ```python settings.ETHIKOS_DEMO_IMPORTER_ENABLED ``` Behavior: ```txt Preview endpoint: - validates JSON - returns summary - does not write to database Import endpoint: - validates JSON - writes demo data - tracks created objects - returns summary Reset endpoint: - deletes objects tracked under scenario_key - returns deleted object list ``` --- ## `backend/konnaxion/ethikos/demo_import/urls.py` Purpose: ```txt Maps demo importer views to API URLs. ``` Routes: ```python urlpatterns = [ path( "demo-scenarios/preview/", EthikosDemoScenarioPreviewView.as_view(), name="preview", ), path( "demo-scenarios/import/", EthikosDemoScenarioImportView.as_view(), name="import", ), path( "demo-scenarios/reset/", EthikosDemoScenarioResetView.as_view(), name="reset", ), ] ``` Final mounted paths: ```txt /api/ethikos/demo-scenarios/preview/ /api/ethikos/demo-scenarios/import/ /api/ethikos/demo-scenarios/reset/ ``` --- # 6. Tracking model ## `backend/konnaxion/ethikos/models_demo.py` Purpose: ```txt Tracks every database object created by a demo scenario. Allows safe reset by scenario_key. Prevents deleting unrelated production or test data. ``` Model: ```python class DemoScenarioImport(models.Model): scenario_key = models.CharField(max_length=120, db_index=True) object_type = models.CharField(max_length=120, db_index=True) object_id = models.PositiveIntegerField(db_index=True) object_label = models.CharField(max_length=255, blank=True) imported_by = models.ForeignKey( settings.AUTH_USER_MODEL, on_delete=models.SET_NULL, null=True, blank=True, ) imported_at = models.DateTimeField(auto_now_add=True) ``` Tracked object types: ```txt user category topic stance argument consultation consultation_vote consultation_result impact_item ``` Important alignment rule: ```python # backend/konnaxion/ethikos/models.py from .models_demo import DemoScenarioImport ``` This ensures Django detects the model for migrations. --- ## `backend/konnaxion/ethikos/migrations/00XX_demo_scenario_import.py` Purpose: ```txt Creates the DemoScenarioImport table. ``` Rename `00XX` to the next migration number. Example: ```txt 0007_demo_scenario_import.py ``` --- # 7. Frontend file responsibilities ## `frontend/app/ethikos/admin/demo-importer/page.tsx` Purpose: ```txt Defines the Next.js route page. Mounts the DemoImporterPanel. ``` Route: ```txt /ethikos/admin/demo-importer ``` Content: ```tsx import { DemoImporterPanel } from "@/features/ethikos/demo-importer/DemoImporterPanel"; export default function EthikosDemoImporterPage() { return <DemoImporterPanel />; } ``` --- ## `frontend/features/ethikos/demo-importer/types.ts` Purpose: ```txt Defines TypeScript types matching the JSON schema and backend responses. Uses snake_case to match backend JSON exactly. ``` Important types: ```ts EthikosDemoScenario EthikosDemoActor EthikosDemoCategory EthikosDemoTopic EthikosDemoStance EthikosDemoArgument EthikosDemoConsultation EthikosDemoConsultationOption EthikosDemoConsultationVote EthikosDemoImpactItem EthikosDemoImportSummary EthikosDemoImportError EthikosDemoImportResponse EthikosDemoResetRequest ``` Rule: ```txt Do not convert JSON fields to camelCase. Use snake_case everywhere. ``` --- ## `frontend/features/ethikos/demo-importer/api.ts` Purpose: ```txt Centralizes API endpoints and fetch helpers. Parses pasted JSON. Calls preview/import/reset endpoints. Normalizes backend errors. ``` Constants: ```ts export const ETHIKOS_DEMO_IMPORTER_ROUTE = "/ethikos/admin/demo-importer"; export const ETHIKOS_DEMO_API_BASE = "/api/ethikos/demo-scenarios"; export const ETHIKOS_DEMO_PREVIEW_ENDPOINT = `${ETHIKOS_DEMO_API_BASE}/preview/`; export const ETHIKOS_DEMO_IMPORT_ENDPOINT = `${ETHIKOS_DEMO_API_BASE}/import/`; export const ETHIKOS_DEMO_RESET_ENDPOINT = `${ETHIKOS_DEMO_API_BASE}/reset/`; ``` Functions: ```ts previewEthikosDemoScenario importEthikosDemoScenario resetEthikosDemoScenario parseEthikosDemoScenarioJson ``` --- ## `frontend/features/ethikos/demo-importer/DemoImporterPanel.tsx` Purpose: ```txt Main user interface controller. Manages JSON text, parsed scenario, preview result, import result, reset result, and loading states. ``` State names: ```txt jsonText parsedScenario previewResult importResult resetResult isPreviewing isImporting isResetting errorMessage ``` User actions: ```txt Paste JSON Preview Import Reset scenario View result JSON ``` Uses: ```txt JsonScenarioEditor ImportResultPanel api.ts helpers types.ts types ``` --- ## `frontend/features/ethikos/demo-importer/JsonScenarioEditor.tsx` Purpose: ```txt Simple JSON textarea component. Receives current JSON text and update callback. Displays syntax/schema error message if present. ``` Props: ```ts type JsonScenarioEditorProps = { value: string; onChange: (value: string) => void; errorMessage?: string; }; ``` --- ## `frontend/features/ethikos/demo-importer/ImportResultPanel.tsx` Purpose: ```txt Displays preview/import/reset results. Shows summaries, validation errors, warnings, created objects, updated objects, and deleted objects. ``` Props: ```ts type ImportResultPanelProps = { title: string; result: EthikosDemoImportResponse | null; }; ``` --- # 8. Demo JSON files ## Location ```txt docs/demo-scenarios/ethikos/ ``` Files: ```txt public_square_demo.json ai_in_schools_demo.json community_budget_demo.json ``` Each file follows the same schema. --- ## Root JSON structure ```json { "schema_version": "ethikos-demo-scenario/v1", "scenario_key": "public_square_demo", "scenario_title": "Public Square Redevelopment Demo", "mode": "replace_scenario", "metadata": {}, "actors": [], "categories": [], "topics": [], "stances": [], "arguments": [], "consultations": [], "consultation_votes": [], "impact_items": [] } ``` --- ## Object relationships ```txt actors[].key referenced by: stances[].actor arguments[].actor consultation_votes[].actor categories[].key referenced by: topics[].category topics[].key referenced by: stances[].topic arguments[].topic arguments[].key referenced by: arguments[].parent consultations[].key referenced by: consultation_votes[].consultation impact_items[].consultation consultations[].options[].key optionally referenced by: consultation_votes[].option ``` --- # 9. API contract ## Preview ```txt POST /api/ethikos/demo-scenarios/preview/ ``` Input: ```json { "schema_version": "ethikos-demo-scenario/v1", "scenario_key": "public_square_demo", "...": "..." } ``` Success response: ```json { "ok": true, "dry_run": true, "scenario_key": "public_square_demo", "summary": { "actors": 2, "categories": 1, "topics": 1, "stances": 2, "arguments": 2, "consultations": 1, "consultation_votes": 2, "impact_items": 1 }, "created": [], "updated": [], "deleted": [], "warnings": [] } ``` --- ## Import ```txt POST /api/ethikos/demo-scenarios/import/ ``` Success response: ```json { "ok": true, "dry_run": false, "scenario_key": "public_square_demo", "summary": { "actors": 2, "categories": 1, "topics": 1, "stances": 2, "arguments": 2, "consultations": 1, "consultation_votes": 2, "impact_items": 1 }, "created": [], "updated": [], "deleted": [], "warnings": [] } ``` --- ## Reset ```txt POST /api/ethikos/demo-scenarios/reset/ ``` Input: ```json { "scenario_key": "public_square_demo" } ``` Success response: ```json { "ok": true, "scenario_key": "public_square_demo", "deleted": [ { "object_type": "topic", "object_id": 12, "object_label": "[DEMO] How should we redesign Place des Rivières?" } ] } ``` --- ## Validation error response ```json { "ok": false, "dry_run": true, "scenario_key": "public_square_demo", "errors": [ { "path": "stances[0].value", "message": "Stance value must be an integer from -3 to +3" } ], "warnings": [] } ``` --- # 10. Import modes ## `replace_scenario` Default mode. Behavior: ```txt 1. Reset previous objects tracked under the same scenario_key. 2. Import the new JSON content. 3. Track all created objects. ``` Use for demos. ```json { "mode": "replace_scenario" } ``` --- ## `append_scenario` Behavior: ```txt 1. Do not reset previous scenario objects. 2. Add/import the new content. 3. Track new objects under the same scenario_key. ``` Use only when intentionally layering data. ```json { "mode": "append_scenario" } ``` --- # 11. Reset behavior Reset must be based on: ```txt DemoScenarioImport.scenario_key ``` Reset flow: ```txt 1. Find all DemoScenarioImport rows for scenario_key. 2. Group them by object_type. 3. Delete objects in safe dependency order. 4. Return deleted object list. 5. Delete tracking rows. ``` Recommended delete order: ```txt argument stance consultation_vote consultation_result impact_item topic consultation category user ``` Users should only be deleted if they are demo users: ```txt username starts with demo_ ``` Fallback safety rule: ```txt Never delete non-demo users during reset. ``` --- # 12. Validation rules The schema validator should enforce: ```txt schema_version must equal ethikos-demo-scenario/v1 scenario_key is required scenario_title is required mode must be replace_scenario or append_scenario actors[].key must be unique categories[].key must be unique topics[].key must be unique arguments[].key must be unique consultations[].key must be unique topics[].category must reference categories[].key stances[].actor must reference actors[].key stances[].topic must reference topics[].key arguments[].actor must reference actors[].key arguments[].topic must reference topics[].key arguments[].parent must reference arguments[].key if present consultation_votes[].actor must reference actors[].key consultation_votes[].consultation must reference consultations[].key impact_items[].consultation must reference consultations[].key stances[].value must be integer from -3 to +3 topics[].status must be open, closed, or archived consultations[].status must be open, closed, or archived arguments[].side must be pro, con, neutral, or null ``` --- # 13. Security and access The tool is internal. Access rules: ```txt Only admin users can access API endpoints. Feature flag must be enabled. The importer should not run publicly by default. ``` Environment variable: ```env ETHIKOS_DEMO_IMPORTER_ENABLED=true ``` Django setting: ```python ETHIKOS_DEMO_IMPORTER_ENABLED = env.bool( "ETHIKOS_DEMO_IMPORTER_ENABLED", default=False, ) ``` If disabled, API returns permission denied. --- # 14. Inner working: full data flow ```txt Admin opens: /ethikos/admin/demo-importer Admin pastes JSON. Frontend: 1. Stores JSON in jsonText 2. Parses JSON locally 3. Calls preview endpoint Backend preview: 1. Checks feature flag 2. Checks admin permission 3. Validates JSON 4. Returns summary/errors 5. Writes nothing Admin clicks Import. Frontend: 1. Sends parsed JSON to import endpoint Backend import: 1. Checks feature flag 2. Checks admin permission 3. Validates JSON 4. Opens database transaction 5. If mode=replace_scenario, resets previous tracked objects 6. Creates/updates demo users 7. Creates categories 8. Creates topics 9. Creates stances 10. Creates arguments 11. Creates consultations 12. Creates consultation votes 13. Creates impact items 14. Tracks created objects in DemoScenarioImport 15. Returns summary Admin visits existing ethiKos pages. Existing ethiKos UI: 1. Reads normal ethiKos data 2. Shows imported demo topics, stances, arguments, votes, and impact items Admin clicks Reset. Backend reset: 1. Finds DemoScenarioImport records for scenario_key 2. Deletes tracked objects in safe order 3. Deletes tracking rows 4. Returns deleted object list ``` --- # 15. Testing plan ## `test_demo_import_schema.py` Covers JSON validation. Tests: ```python def test_valid_demo_scenario_passes_validation(): ... def test_invalid_schema_version_fails_validation(): ... def test_unknown_actor_reference_fails_validation(): ... def test_unknown_topic_reference_fails_validation(): ... def test_stance_outside_allowed_range_fails_validation(): ... def test_unknown_consultation_reference_fails_validation(): ... ``` --- ## `test_demo_importer.py` Covers importer service behavior. Tests: ```python def test_import_creates_demo_actors_categories_topics_stances_and_arguments(): ... def test_import_replace_scenario_resets_previous_tracked_objects(): ... def test_import_tracks_created_objects(): ... def test_reset_deletes_only_tracked_scenario_objects(): ... def test_dry_run_does_not_create_objects(): ... ``` --- ## `test_demo_import_api.py` Covers API behavior. Tests: ```python def test_preview_requires_admin_user(): ... def test_import_requires_admin_user(): ... def test_reset_requires_admin_user(): ... def test_preview_returns_summary_for_valid_payload(): ... def test_import_returns_created_summary_for_valid_payload(): ... def test_reset_requires_scenario_key(): ... ``` --- # 16. Implementation order Recommended order for parallel work: ```txt 1. schema.py 2. types.ts 3. api.ts 4. models_demo.py 5. migration file 6. importer.py 7. serializers.py 8. views.py 9. urls.py 10. page.tsx 11. JsonScenarioEditor.tsx 12. ImportResultPanel.tsx 13. DemoImporterPanel.tsx 14. demo JSON files 15. backend tests ``` Critical dependency: ```txt schema.py and types.ts should be aligned first. ``` Everything else depends on those names. --- # 17. Non-goals The Demo Importer should not: ```txt become a full CMS edit real user voting history create a new top-level app create new public routes manually fake Smart Vote readings bypass admin permissions delete untracked production data expand API paths only when they belong to the current owner contract ``` --- # 18. Final operating rule ```txt The JSON scenario is the demo source of truth. The importer validates it, imports it, tracks it, and resets it. The existing ethiKos app renders the imported data through normal routes. ``` ================================================================================================ FILE: docs/demo-scenarios/ethikos/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 14af8597e9102e540a89cb922767e2c14ff751dbbf508d606d8c500b5b981105 CONTENT_BYTES: 1434 ================================================================================================ # ethiKos Demo Scenario JSON Pack These files are ready-to-import demo scenario payloads for the ethiKos Demo Importer. ## Importer contract - schema_version: ethikos-demo-scenario/v1 - mode: replace_scenario - demo users use the `demo_` prefix - demo topic and consultation titles use the `[DEMO]` prefix - stances use the -3..+3 scale - consultation votes include raw_value and weighted_value - each scenario is independent and resettable by scenario_key ## Files - `public_square_redevelopment_demo.json` — Public Square Redevelopment Demo (Civic planning + Korum + Konsultations) - `ai_in_schools_policy_demo.json` — AI in Schools Policy Demo (Education policy + safeguards + EkoH-weighted expert context) - `community_budget_allocation_demo.json` — Community Budget Allocation Demo (Participatory budgeting + alternate priorities) - `climate_action_weighted_reading_demo.json` — Climate Action Weighted Reading Demo (Smart Vote + EkoH weighted influence) - `cultural_heritage_archive_demo.json` — Cultural Heritage Archive Demo (Kreative + cultural policy + trust) - `startup_grant_feedback_demo.json` — Startup Grant Feedback Demo (Business + mentorship + weighted review) - `digital_safety_curriculum_demo.json` — Digital Safety Curriculum Demo (Education + cybersecurity + media trust) - `smart_mobility_corridor_demo.json` — Smart Mobility Corridor Demo (Urban mobility + infrastructure + accessibility) ================================================================================================ FILE: docs/KONNAXION_UPGRADE_TO_DO(credentialAnalyser).md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c5f1ffb360552bbef12c4faa39e0dc8e5a93fd86746ee72aa1dc728aa4aa4008 CONTENT_BYTES: 16778 ================================================================================================ # Konnaxion — Upgrade To-To **Document ID:** `UPGRADE_TO_TO.md` **Scope:** conservative upgrade of the existing Konnaxion platform **Status:** proposed **Principle:** strengthen existing contracts without introducing a new application, new product surface, or parallel source of truth. --- ## 1. Purpose This upgrade strengthens Konnaxion in two existing areas: 1. **KonnectED / CertifiKation evaluation semantics** 2. **EkoH evidence intake, scoring traceability, and governance** The upgrade is intentionally conservative. Konnaxion is already stable; therefore the default rule is: > **Preserve existing models, routes, UI surfaces, ownership boundaries, and runtime behavior unless a change is required to close a concrete ambiguity or integrity gap.** This document does not define a new application. --- ## 2. Current baseline Konnaxion already contains the required structural foundations. ### KonnectED / CertifiKation Existing concepts include: - `CertificationPath` - `Evaluation` - `PeerValidation` - `Portfolio` - `InteropMapping` - certification registration, preparation, result and dashboard surfaces `Evaluation` already provides: - a user binding; - a certification path; - `raw_score`; - a flexible `metadata` object. The flexible metadata field is sufficient for the proposed upgrade without requiring a schema migration. ### EkoH EkoH already provides: - canonical expertise taxonomy; - per-user domain expertise scores; - multidimensional scoring based on: - `quality`; - `expertise`; - `frequency`; - score configuration; - score history; - contextual-analysis audit; - rating visibility; - scoped access controls; - dedicated score recalculation. EkoH scoring is already explicitly separate from Smart Vote consumption. --- ## 3. Upgrade goals The upgrade SHALL: 1. make evaluation results more interpretable than a raw score; 2. keep assessment evidence distinct from certification/attestation decisions; 3. define what evidence is allowed to influence EkoH; 4. preserve provenance and scope for evidence that affects reputation; 5. make score changes traceable; 6. preserve privacy and consent boundaries; 7. support correction, expiry, revocation and contestation; 8. prevent derived downstream signals from feeding back into EkoH as new expertise evidence; 9. remain backward-compatible wherever practical. --- ## 4. Non-goals This upgrade SHALL NOT: - create a new top-level Konnaxion application; - create a second evaluation engine beside the existing CertifiKation flow; - create a second reputation engine beside EkoH; - add a general-purpose human score; - add public ranking by default; - redesign the current Konnaxion UI; - require new certification pages; - introduce a new mandatory database schema in the first implementation phase; - allow external or internal producers to write `UserExpertiseScore` directly; - allow AI analysis to silently mutate canonical expertise scores; - allow Smart Vote results or voting influence to become canonical EkoH expertise evidence. --- ## 5. Upgrade A — Evaluation result semantics ### 5.1 Raw score remains audit data `Evaluation.raw_score` MAY remain unchanged for compatibility. It SHALL NOT be treated as the complete semantic interpretation of a person's competence. A raw score answers: > What numerical result was observed in this evaluation? It does not answer: > What is this person's general value, intelligence, authority, or competence in unrelated contexts? ### 5.2 Canonical optional metadata The existing `Evaluation.metadata` field SHOULD support the following canonical keys when applicable: ```json { "status": "completed", "assessment_context": "...", "rule_version": "...", "confirmed_level": "...", "highest_explored_level": "...", "confidence": "...", "validity_conditions": [], "non_validity_conditions": [], "interpretation": { "strengths": [], "limitations": [], "uncertainties": [], "recommendations": [] }, "consent_scope": "...", "review_ref": "...", "source_ref": "..." } ``` These keys are optional and additive. Existing metadata such as: - `session_id`; - `full_name`; - `agreed_terms`; - `delivery_mode`; - `proctored`; - `target_date`; - `score_percent`; - `max_score`; - `appeal_status`; - `peer_validation_required`; remains valid. ### 5.3 Interpretation rules An evaluation result SHOULD distinguish: - **confirmed level** — level supported with sufficient confidence; - **highest explored level** — highest level meaningfully tested; - **confidence / uncertainty** — strength of the conclusion; - **validity conditions** — contexts in which the result applies; - **non-validity conditions** — conclusions the result does not support. The system SHOULD prefer statements such as: > Competence is confirmed to level X in context Y. over statements such as: > This person is competent in general. ### 5.4 Evaluation versus certification The following boundary SHALL remain explicit: ```text Evaluation ↓ provides evidence Certification review / policy ↓ decides Certification / attestation state ``` An evaluation MAY recommend certification review. An evaluation SHALL NOT implicitly create or guarantee an attestation solely because a score threshold was reached. --- ## 6. Upgrade B — Evaluation lifecycle and contestability Evaluation metadata SHOULD use explicit lifecycle states where applicable. Recommended states: ```text scheduled in_progress completed corrected contested expired cancelled ``` A corrected evaluation SHOULD preserve the reference to the prior result. A contested evaluation SHOULD remain available for audit but SHOULD NOT be silently rewritten as if no contest occurred. Where a result can materially affect certification, reputation or access, Konnaxion SHOULD expose or retain a review/appeal reference. --- ## 7. Upgrade C — EkoH evidence intake contract ### 7.1 Core rule EkoH SHALL remain the sole authority for canonical EkoH reputation scores. Evidence producers provide evidence or normalized evidence signals. They do not provide authoritative final EkoH scores. ```text source fact ↓ evidence ↓ qualification / admissibility ↓ EkoH metric aggregation ↓ EkoH scoring ↓ UserExpertiseScore ``` ### 7.2 Minimum evidence envelope Any future evidence source that is allowed to affect EkoH SHOULD be representable by an internal envelope equivalent to: ```text evidence_id source_namespace source_ref subject_id domain_code evidence_type observed_at valid_until provenance status consent_scope reliability domain_relevance supersedes audit_ref idempotency_key ``` This is a **contract**, not necessarily a new database model. The first implementation SHOULD use an internal DTO, typed mapping, dataclass or equivalent boundary object before considering persistence. ### 7.3 Evidence status Evidence status SHOULD be explicit. Recommended states: ```text submitted under_review admissible partially_admissible rejected disputed expired revoked superseded ``` Only admissible or explicitly partially admissible evidence MAY influence EkoH scoring. ### 7.4 Verification is not scoring Konnaxion SHALL preserve this distinction: ```text evidence exists ≠ evidence is authentic ≠ evidence is relevant to this domain ≠ evidence is admissible ≠ evidence increases the EkoH score ``` The final reputation impact remains an EkoH scoring decision. --- ## 8. Upgrade D — Governed metric aggregation EkoH currently scores three normalized dimensions: ```text quality expertise frequency ``` The governed evidence collector SHOULD aggregate admissible evidence into these existing dimensions rather than create a parallel scoring system. The collector SHALL: 1. ignore rejected, revoked or expired evidence unless policy explicitly says otherwise; 2. resolve superseded/duplicate evidence before aggregation; 3. respect domain mapping; 4. respect consent and permitted use; 5. keep source provenance available for audit; 6. return `None` when complete trustworthy metrics cannot be produced. It SHALL NOT fabricate zero-valued metrics merely because evidence is unavailable. This preserves the current fail-safe recalculation behavior. --- ## 9. Upgrade E — Score authority and write boundary Canonical EkoH score mutation SHOULD occur only through the existing EkoH scoring service or a clearly designated wrapper around it. Direct writes to: ```text UserExpertiseScore.raw_score UserExpertiseScore.weighted_score ``` from unrelated modules SHOULD be prohibited by convention and tests. Recommended write path: ```text governed evidence collector ↓ quality / expertise / frequency ↓ compute_user_domain_score(...) ↓ UserExpertiseScore ``` A producer MAY submit evidence. A producer SHALL NOT decide the final normalized domain score. --- ## 10. Upgrade F — Traceability Every material score change SHOULD be explainable. At minimum the system SHOULD be able to recover: - user; - domain; - old score; - new score; - reason; - evidence references or aggregation reference; - scoring configuration/rule version; - timestamp. Existing `ScoreHistory` remains the canonical score-history mechanism. Where additional structured context is useful, existing JSON-capable audit structures SHOULD be preferred before introducing new tables. --- ## 11. Upgrade G — Corrections, revocation and supersession Evidence MAY change after initial acceptance. The system SHOULD support these semantics: ```text correction revocation expiry supersession ``` A source correction SHALL NOT silently overwrite historical meaning. Instead: ```text old evidence ↓ corrected/revoked/superseded new authoritative state ↓ EkoH re-evaluation ↓ new score + history entry ``` The evidence boundary MUST NOT directly patch the final EkoH score to compensate. The score is recomputed through the canonical scoring path. --- ## 12. Upgrade H — Privacy and consent Konnaxion SHALL preserve the distinction between: ```text raw evidence visibility evaluation visibility EkoH score visibility EkoH history visibility identity visibility ``` A public EkoH score does not imply that the underlying evidence is public. A public certification does not imply that all evaluation details are public. An evidence envelope SHOULD carry sufficient consent/use information to prevent a downstream consumer from assuming broader rights than were granted at collection time. Existing EkoH confidentiality, rating visibility and scoped access controls remain authoritative for EkoH disclosure. --- ## 13. Upgrade I — AI boundary AI-assisted analysis MAY: - classify evidence; - suggest domain mapping; - summarize evidence; - identify anomalies; - recommend review; - propose contextual interpretation. AI-assisted analysis SHALL NOT, by default: - establish authoritative truth; - silently mark disputed evidence as accepted; - directly mutate canonical EkoH scores; - issue certification; - make an irreversible high-impact decision without the applicable governance path. The existing non-authoritative contextual-analysis behavior SHOULD remain the default pattern. --- ## 14. Upgrade J — No feedback loop from downstream derived signals Derived downstream outputs SHALL NOT automatically become new canonical EkoH expertise evidence. In particular: ```text EkoH expertise ↓ contextual downstream use ↓ derived influence / reading / result ``` MUST NOT become: ```text derived influence / reading / result ↓ new EkoH expertise evidence ↓ higher EkoH expertise ↓ stronger derived influence ↓ ... ``` Any downstream object reused as evidence must have an independent evidentiary basis and explicit policy authorizing that use. Circular self-amplification is prohibited. --- ## 15. Implementation strategy ### Phase 0 — Documentation lock **Risk:** minimal **Database migration:** none **UI change:** none Actions: 1. adopt this document as the upgrade contract; 2. document evaluation-versus-certification ownership; 3. document EkoH score-write authority; 4. document the evidence-intake envelope; 5. document the no-feedback-loop invariant. This phase can be completed without changing runtime behavior. ### Phase 1 — Backward-compatible hardening **Risk:** low **Database migration:** none expected **UI change:** none required Actions: 1. add validation/helpers for canonical `Evaluation.metadata` keys; 2. add tests proving legacy metadata remains valid; 3. add tests proving AI/context analysis cannot write EkoH scores; 4. add tests proving non-EkoH modules cannot bypass the canonical scoring path; 5. standardize score-history reasons; 6. add explicit tests for revoked/expired/superseded evidence behavior when the collector is implemented. ### Phase 2 — Governed evidence collector **Risk:** controlled **Database migration:** avoid unless justified by real persistence requirements **UI change:** none required Implement the currently missing governed evidence aggregation behind `_collect_metrics()`. The collector SHOULD: ```text collect eligible evidence → validate status/provenance/scope → remove duplicates/superseded records → map to EkoH domain → aggregate quality/expertise/frequency → return metrics ``` If evidence is incomplete or not trustworthy: ```python return None ``` No score is overwritten. ### Phase 3 — Optional structured persistence Only introduce a persistent evidence table if actual product requirements prove that references and existing source objects are insufficient. A schema migration SHALL NOT be justified merely to mirror information already owned elsewhere in Konnaxion. --- ## 16. Compatibility requirements The upgrade SHOULD preserve: - existing frontend routes; - existing CertifiKation pages; - existing Evaluation API routes; - existing EkoH profile API behavior; - existing score normalization; - existing rating visibility behavior; - existing scoped rating access; - existing DB schema unless a later phase explicitly requires change. Existing clients that only understand `raw_score` and legacy `metadata` SHALL continue to function. New interpretation metadata is additive. --- ## 17. Required tests Before activating runtime changes, the following invariants SHOULD be covered: ### Evaluation - legacy Evaluation payloads remain readable; - canonical metadata keys are optional; - invalid canonical values fail predictably when validation is enabled; - corrected/contested state does not erase prior audit information. ### EkoH - missing evidence returns no scoring metrics rather than synthetic zeroes; - rejected evidence cannot affect scores; - revoked evidence triggers re-evaluation rather than direct score mutation; - duplicate/superseded evidence is not double-counted; - scoring remains bounded to `0..1`; - missing required scoring axes fail closed; - AI/context analysis does not mutate `UserExpertiseScore`; - score changes produce traceable history; - unauthorized consumers cannot access restricted scores/history. ### Boundary - no downstream derived signal can automatically re-enter EkoH as expertise evidence; - external/internal evidence producers cannot directly author canonical EkoH scores. --- ## 18. Definition of done The upgrade is complete when all of the following are true: 1. Konnaxion has one evaluation truth, not parallel evaluators. 2. Evaluation results have optional structured interpretation semantics. 3. Certification remains a distinct decision from evaluation. 4. EkoH has one canonical score-write path. 5. Evidence entering EkoH is provenance-aware, scoped and status-aware. 6. Missing evidence cannot erase existing reputation. 7. Correction/revocation/supersession can trigger deterministic re-evaluation. 8. Score changes are traceable. 9. Privacy of source evidence remains independent from score visibility. 10. AI analysis remains advisory by default. 11. Derived downstream signals cannot create reputation feedback loops. 12. Existing stable Konnaxion pages and APIs continue to operate. --- ## 19. Canonical architecture statement > **Konnaxion keeps source facts, evaluation, certification, evidence qualification, reputation scoring and downstream use as distinct authority boundaries. Existing components are strengthened rather than duplicated.** And operationally: ```text KonnectED / CertifiKation evaluation evidence ↓ governed evidence boundary ↓ EkoH metric aggregation ↓ EkoH canonical scoring ↓ authorized downstream consumption ``` No new application is required for this upgrade. ================================================================================================ FILE: docs/Konnaxion_UserWorkflow_Documentation_v0_1.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: d112abc7fe7192defe4e74f0461937aef76997c3cce2d2de71ff21232d51fedc CONTENT_BYTES: 38519 ================================================================================================ # Konnaxion — Documentation légère des User Workflows Version: v0.1 Statut: brouillon de travail Format: document unique, non exhaustif Objectif: décrire les parcours utilisateur principaux sans transformer le document en spécification complète écran par écran. Périmètre: Konnaxion, avec accent sur ethiKos, Smart Vote/EkoH, keenKonnect, KonnectED et Kreative. Principe: raconter les parcours comme des expériences utilisateur, puis relier chaque parcours aux modules, sous-modules et sorties attendues. ## 1. Intention du document - Ce document sert de base commune pour comprendre comment un utilisateur traverse Konnaxion. - Il ne remplace pas les contrats techniques, les routes, les modèles ou les plans de migration. - Il transforme l’architecture modulaire en parcours compréhensibles par des humains. - Il reste volontairement non exhaustif. - Il ne décrit pas chaque bouton, chaque état d’erreur ou chaque permission fine. - Il identifie les moments où un module commence, où un autre prend le relais, et ce que l’utilisateur comprend à chaque étape. - Il aide aussi les futures sessions d’IA à générer des écrans, des textes d’aide ou des tickets sans réinventer les workflows. Le document répond à une question simple: > Si une personne utilise Konnaxion pour apprendre, délibérer, décider, construire, collaborer ou publier une œuvre, quel chemin suit-elle? ## 2. Règles de cadrage - Un seul document. - Pas exhaustif. - Environ 1000 lignes. - Style lisible, narratif et fonctionnel. - Pas une spec technique complète. - Pas une liste de tous les endpoints. - Pas une matrice complète de permissions. - Pas une réécriture de l’architecture. - Pas de nouvelle route inventée. - Pas de nouveau shell d’interface. - Les modules existants restent les points d’entrée. - Les sous-modules expliquent les parcours, mais ne remplacent pas les modules. ## 3. Structure de lecture - Chaque module est présenté par son rôle utilisateur. - Chaque sous-module est présenté par ce que l’utilisateur veut accomplir. - Chaque parcours est décrit avec une situation concrète. - Les sorties attendues sont indiquées quand elles sont importantes. - Les intégrations Kintsugi/Kompendio sont mentionnées seulement aux endroits pertinents. - Les annexes futures sont distinguées des capacités natives. - Les workflows sont racontés en langage produit, pas en langage base de données. ## 4. Définitions rapides - **Module:** Grand domaine fonctionnel de Konnaxion, par exemple ethiKos ou KonnectED. - **Sous-module:** Capacité plus précise à l’intérieur d’un module, par exemple Korum, Konsultations ou CertifiKation. - **Workflow utilisateur:** Chemin parcouru par une personne pour atteindre un résultat compréhensible. - **Sortie utilisateur:** Résultat visible ou utile: vote, certificat, projet, archive, portefeuille, décision, rapport, etc. - **Baseline:** Lecture brute ou non pondérée d’un résultat. - **Reading / Lens:** Lecture déclarée d’un résultat, par exemple pondérée ou filtrée. - **Kintsugi:** Approche d’intégration harmonisée de capacités externes ou open-source sous un même toit, sans fusion brute. - **Kompendio:** Couche de références, standards, fiches, charts et packs réutilisables. ## 5. Vue d’ensemble des modules Konnaxion peut être lu comme une boucle complète: ```text Apprendre → se qualifier → participer → délibérer → décider → construire → documenter → publier → mesurer l’impact ``` - **ethiKos:** délibération, consultation, décision, impact et légitimité. - **Kollective Intelligence:** réputation, expertise, EkoH, Smart Vote et lectures de résultats. - **keenKonnect:** exécution de projets, collaboration, stockage et références de build. - **KonnectED:** apprentissage, ressources, évaluations, certifications et preuves de compétence. - **Kreative:** création, patrimoine, archives, expositions, collaboration créative et profils. ## 6. Personas de référence - **Maya — citoyenne participante:** veut comprendre un débat et voter sans être experte. - **Nadia — facilitatrice:** veut organiser une consultation et éviter que le débat devienne chaotique. - **Samuel — expert métier:** veut contribuer sans imposer son autorité comme vérité unique. - **Lina — apprenante:** veut suivre un parcours, prouver ses compétences et obtenir une certification. - **Omar — builder:** veut coordonner un projet, préserver les fichiers et produire un pack reproductible. - **Ariane — artiste ou médiatrice culturelle:** veut publier une œuvre, l’archiver et collaborer. - **Équipe admin — gouvernance et modération:** veut auditer, configurer, modérer et préserver la confiance. ## 7. Principes UX communs - Toujours montrer à l’utilisateur où il se trouve dans le processus. - Toujours séparer contribution, interprétation et décision. - Toujours distinguer résultat brut et lecture enrichie. - Toujours rendre les sorties importantes retrouvables. - Toujours expliquer pourquoi une recommandation ou une pondération existe. - Toujours éviter qu’un outil externe devienne une source de vérité cachée. - Toujours permettre de revenir du résultat vers les contributions sources. - Toujours préférer une interface simple avec des détails progressifs. ## 8. Parcours global: de l’idée à l’impact Scénario: une communauté veut transformer une place publique. 1. Un problème est soumis dans une consultation. 2. Les propositions sont clarifiées. 3. Les citoyens formulent des arguments. 4. Les positions se structurent. 5. Un vote ou une décision est lancé. 6. Le résultat brut est publié. 7. Des lectures Smart Vote peuvent être comparées. 8. Une décision est adoptée ou rejetée. 9. Des actions d’implémentation sont suivies. 10. Les preuves et résultats sont rendus visibles. Ce scénario traverse surtout ethiKos, Smart Vote, EkoH et éventuellement keenKonnect pour l’exécution. ## 9. ethiKos — rôle dans l’expérience ethiKos est l’espace où une communauté transforme du bruit social en décision lisible. - Il aide à capter les problèmes. - Il aide à structurer les débats. - Il aide à organiser la décision. - Il aide à publier les résultats. - Il aide à suivre l’impact. - Il garde les faits sources séparés des lectures interprétatives. ethiKos n’est pas seulement un forum. C’est un parcours de décision. ## 10. ethiKos — structure d’interface pré-Kintsugi La visite utilise seulement la surface d’interface existante: ```text /ethikos ├── /ethikos/decide/* ├── /ethikos/deliberate/* ├── /ethikos/trust/* ├── /ethikos/pulse/* ├── /ethikos/impact/* ├── /ethikos/learn/* ├── /ethikos/insights └── /ethikos/admin/* ``` Kintsugi n’ajoute pas une nouvelle porte d’entrée visible. Kintsugi améliore les capacités derrière cette structure. ## 11. ethiKos — histoire principale Maya arrive dans ethiKos parce que sa ville discute du réaménagement d’une place publique. Elle voit un sujet actif: ```text Réaménagement de la Place des Rivières État: consultation ouverte Participation: forte Décision: prévue après délibération ``` Maya ne sait pas encore si elle est pour ou contre. Elle veut comprendre, contribuer, puis voter. Le parcours proposé par l’interface est: 1. Lire les guides dans Learn. 2. Observer la situation dans Pulse. 3. Entrer dans le débat dans Deliberate. 4. Comprendre son contexte EkoH dans Trust. 5. Participer à la décision dans Decide. 6. Lire les résultats dans Decide Results ou Insights. 7. Suivre les actions dans Impact. ## 12. ethiKos / Learn — comprendre avant d’agir Route typique: `/ethikos/learn/guides` But utilisateur: - Comprendre comment participer. - Comprendre les règles de débat. - Comprendre la différence entre vote brut et lecture pondérée. - Comprendre le rôle de Smart Vote et EkoH. Exemple de contenu affiché: ```text Une délibération sert à comprendre les raisons. Une décision sert à choisir une option. Une baseline montre le résultat brut. Une lecture Smart Vote montre une interprétation déclarée. ``` Workflow: 1. L’utilisateur ouvre Learn. 2. Il lit un guide court. 3. Il consulte le glossaire. 4. Il retourne vers Deliberate ou Decide. Sortie attendue: - L’utilisateur sait comment contribuer sans confondre débat, vote et résultat. ## 13. ethiKos / Pulse — observer le climat Routes typiques: - `/ethikos/pulse/overview` - `/ethikos/pulse/live` - `/ethikos/pulse/health` - `/ethikos/pulse/trends` But utilisateur: - Voir ce qui se passe maintenant. - Identifier les tensions. - Identifier les convergences. - Trouver où sa contribution peut être utile. Exemple: ```text Climat du débat: - consensus partiel sur plus d’arbres - désaccord fort sur le stationnement - faible participation des commerçants - augmentation des arguments sur l’accessibilité ``` Workflow: 1. L’utilisateur ouvre Pulse. 2. Il voit les tendances globales. 3. Il clique sur un signal de tension. 4. Il est redirigé vers le débat ou la décision liée. Kintsugi: - Les capacités de cartographie avancée peuvent s’inspirer de Polis. - Polis reste différé dans la première passe. - La première version peut mimer certaines idées sans annexion. ## 14. ethiKos / Deliberate — débattre avec structure Routes typiques: - `/ethikos/deliberate/elite` - `/ethikos/deliberate/[topic]` - `/ethikos/deliberate/guidelines` But utilisateur: - Lire une question publique ou experte. - Comprendre les arguments. - Exprimer une position. - Ajouter une raison. - Répondre à une raison. - Repérer les preuves, objections et nuances. Exemple de sujet: ```text Faut-il réduire le stationnement autour de la Place des Rivières pour créer plus d’espace piéton et végétalisé? ``` Exemple d’action: ```text Maya choisit une stance +1. Elle ajoute une nuance: « Je suis favorable à plus d’espace vert, mais seulement si des places accessibles restent près des commerces. » ``` Workflow: 1. L’utilisateur ouvre un topic. 2. Il lit la thèse ou la question. 3. Il consulte les arguments pro et contre. 4. Il choisit une stance de -3 à +3. 5. Il ajoute un argument ou une objection. 6. Il répond à un argument existant. 7. Il suit les changements du débat. Sorties attendues: - Stance enregistrée. - Argument ajouté. - Graphe argumentatif enrichi. - Débat plus lisible. Kintsugi: - Kialo-style argument mapping est mimé nativement. - Consider.it-style reason capture est mimé nativement. - Aucune route `/kialo` n’est créée. - Les arguments restent des objets ethiKos/Korum. ## 15. ethiKos / Trust — comprendre le contexte de confiance Routes typiques: - `/ethikos/trust/profile` - `/ethikos/trust/badges` - `/ethikos/trust/credentials` But utilisateur: - Comprendre son profil EkoH. - Voir ses domaines d’expertise. - Comprendre ses badges. - Gérer sa visibilité si disponible. - Comprendre comment son contexte peut être utilisé dans certaines lectures. Exemple: ```text Profil EkoH de Maya Domaine: participation citoyenne Visibilité: pseudonyme public Influence: utilisée seulement dans des lectures déclarées ``` Workflow: 1. L’utilisateur ouvre son profil Trust. 2. Il voit ses domaines et badges. 3. Il comprend sa confidentialité. 4. Il retourne vers une décision ou un débat. Sorties attendues: - L’utilisateur comprend que EkoH fournit un contexte. - Il comprend que EkoH ne remplace pas son vote. Kintsugi: - EkoH reste natif. - EkoH n’est pas un moteur de vote. - EkoH fournit expertise, éthique, cohortes et snapshots. ## 16. ethiKos / Decide — participer à une décision Routes typiques: - `/ethikos/decide/public` - `/ethikos/decide/elite` - `/ethikos/decide/results` - `/ethikos/decide/methodology` But utilisateur: - Lire la décision à prendre. - Comprendre les options. - Participer au vote si admissible. - Voir la méthode de décision. - Lire les résultats bruts et les lectures. Exemple de décision: ```text Quel scénario doit guider le réaménagement? A. Place très végétalisée B. Place mixte C. Maintien du stationnement D. Report de la décision ``` Workflow: 1. L’utilisateur ouvre Decide. 2. Il choisit une décision active. 3. Il lit les options. 4. Il consulte la méthode. 5. Il vote. 6. Il reçoit une confirmation. 7. Il revient lire les résultats. Sorties attendues: - Vote ou ballot enregistré. - Résultat baseline disponible après clôture. - Lectures Smart Vote disponibles si configurées. Kintsugi: - Smart Vote produit les lectures dérivées. - EkoH peut fournir un snapshot de contexte. - OpenSlides peut devenir une annexe future pour mode assemblée. - All Our Ideas peut inspirer ou soutenir une priorisation future. - Your Priorities peut inspirer une priorisation citoyenne future. - Aucune annexe ne remplace la source de vérité ethiKos/Smart Vote. ## 17. ethiKos / Results — lire les résultats Route typique: `/ethikos/decide/results` But utilisateur: - Comprendre ce qui a été décidé. - Voir le résultat brut. - Comparer les lectures déclarées. - Comprendre la méthode. - Vérifier que la lecture pondérée ne cache pas la baseline. Exemple: ```text Baseline: Option B: 48% Option A: 31% Option C: 15% Option D: 6% Lecture expertise mobilité: Option B reste première. Option A augmente légèrement. ``` Workflow: 1. L’utilisateur ouvre les résultats. 2. Il voit la baseline. 3. Il active une lecture Smart Vote. 4. Il lit l’explication de la lecture. 5. Il peut revenir aux contributions sources. Sorties attendues: - Résultat lisible. - Méthode transparente. - Lectures comparables. ## 18. ethiKos / Impact — suivre après la décision Routes typiques: - `/ethikos/impact/feedback` - `/ethikos/impact/outcomes` - `/ethikos/impact/tracker` But utilisateur: - Voir ce qui arrive après une décision. - Suivre les engagements. - Ajouter du feedback. - Voir les preuves d’exécution. - Comprendre si la décision a réellement produit un changement. Exemple: ```text Décision adoptée: Place mixte avec stationnement partiellement réduit Actions: 1. Plan préliminaire 2. Consultation accessibilité 3. Test temporaire 4. Rapport d’impact ``` Workflow: 1. La décision est clôturée. 2. Des actions sont créées. 3. Un responsable ou une équipe est associé. 4. Des preuves et statuts sont publiés. 5. Les utilisateurs peuvent donner du feedback. 6. Le suivi est clôturé ou révisé. Kintsugi: - Les patterns d’accountability peuvent s’inspirer de Decidim ou CONSUL. - Ils sont mimés nativement. - L’exécution peut être liée à keenKonnect. - La vérité d’impact reste dans ethiKos/Konsultations. ## 19. ethiKos / Insights — interpréter sans confondre Route typique: `/ethikos/insights` But utilisateur: - Analyser les résultats. - Comparer baseline et lectures. - Explorer les cohortes. - Lire les tendances. - Comprendre l’évolution d’un débat. Workflow: 1. L’utilisateur choisit un sujet ou une décision. 2. Il voit les faits sources. 3. Il compare les lectures. 4. Il filtre par cohorte ou période. 5. Il exporte ou partage un résumé si disponible. Sorties attendues: - Analyse lisible. - Comparaison reproductible. - Audit possible. ## 20. ethiKos / Admin — gouverner le système Routes typiques: - `/ethikos/admin/audit` - `/ethikos/admin/moderation` - `/ethikos/admin/roles` But utilisateur admin: - Auditer les contributions et résultats. - Modérer les contenus signalés. - Gérer les rôles. - Gérer l’éligibilité. - Préserver la traçabilité. Workflow: 1. L’admin consulte les événements sources. 2. Il vérifie les lectures et snapshots. 3. Il traite les signalements. 4. Il ajuste les rôles ou permissions. 5. Il documente les actions importantes. Kintsugi: - Les annexes futures doivent rester isolées. - Une annexe ne doit pas écrire dans les tables de Korum ou Konsultations. - OpenSlides peut être envisagé pour un mode assemblée futur. - Les sorties d’annexes doivent devenir des artefacts ou projections vérifiables. ## 21. Kollective Intelligence — rôle utilisateur Kollective Intelligence n’est pas toujours visible comme un module narratif séparé. Il fournit des capacités transversales qui apparaissent dans les workflows. - EkoH rend visibles expertise, réputation, éthique et confiance. - Smart Vote rend visibles les votes, modalités, résultats et lectures. - Insights rend les résultats comparables. ## 22. EkoH — workflow utilisateur But utilisateur: - Comprendre son influence contextuelle. - Voir ses domaines d’expertise. - Comprendre son score éthique ou ses badges. - Choisir une visibilité publique, pseudonyme ou privée si disponible. Scénario: ```text Samuel est urbaniste. Il contribue à un débat sur la mobilité. Son expertise peut être utilisée dans une lecture déclarée. Le public voit toujours la baseline. La lecture experte est seulement une interprétation supplémentaire. ``` Workflow: 1. L’utilisateur contribue dans un module. 2. Les signaux pertinents alimentent son profil. 3. EkoH calcule ou met à jour un contexte. 4. Le contexte peut être utilisé par Smart Vote. 5. Les changements restent auditables. Sorties attendues: - Profil de confiance. - Domaines d’expertise. - Historique ou trace. - Snapshot utilisé pour une lecture. ## 23. Smart Vote — workflow utilisateur But utilisateur: - Voter selon une modalité déclarée. - Voir le résultat brut. - Comparer les lectures pondérées ou filtrées. - Comprendre la méthode de calcul. Workflow: 1. Une cible de vote est ouverte. 2. Une modalité est choisie. 3. L’utilisateur vote. 4. Le vote brut est enregistré. 5. Smart Vote calcule un résultat. 6. Des lectures peuvent être publiées. 7. Les résultats deviennent visibles dans ethiKos ou Insights. Sorties attendues: - Vote enregistré. - VoteResult ou équivalent. - Baseline. - ReadingResults. - Explication de méthode. ## 24. keenKonnect — rôle dans l’expérience keenKonnect est l’espace où une décision, une idée ou un apprentissage peut devenir un projet réel. - Konstruct sert à exécuter le projet. - Stockage sert à préserver les fichiers et versions. - Kompendio sert à guider le projet avec des références fiables. ## 25. keenKonnect / Konstruct — exécuter un projet But utilisateur: - Créer un projet. - Inviter une équipe. - Définir des tâches. - Discuter. - Joindre des ressources. - Suivre l’avancement. Scénario: ```text Après la décision sur la place publique, une équipe crée un projet keenKonnect: « Prototype de mobilier temporaire pour la Place des Rivières ». ``` Workflow: 1. L’utilisateur ouvre le Project Studio. 2. Il crée ou rejoint un espace projet. 3. Il définit les rôles. 4. Il crée des tâches. 5. Il ajoute des ressources. 6. L’équipe communique dans le chat. 7. L’IA peut résumer les décisions et prochaines actions. Sorties attendues: - Projet. - Équipe. - Tâches. - Messages. - Ressources. - Résumé ou recommandations. ## 26. keenKonnect / Stockage — préserver les artefacts But utilisateur: - Déposer des fichiers. - Versionner des documents. - Contrôler l’accès. - Indexer les ressources. - Retrouver ce qui a été utilisé. Workflow: 1. L’utilisateur dépose un fichier dans un projet. 2. Le type et la taille sont validés. 3. Le fichier devient une ressource projet. 4. Une version est créée. 5. L’indexation rend le fichier retrouvable. 6. Les collaborateurs reçoivent une mise à jour. Sorties attendues: - ProjectResource. - Historique de version. - Permissions appliquées. - Index de recherche. - Événement de synchronisation. ## 27. keenKonnect / Kompendio — guider le build But utilisateur: - Trouver des plateformes ou références fiables. - Comparer des références. - Créer des Reference Charts. - Attacher des stacks de référence à un projet. - Exporter des packs réutilisables. Scénario: ```text Omar veut construire un banc modulaire. Il cherche des références de matériaux, d’assemblage et de sécurité. Kompendio lui fournit un stack de références vérifiées. Ce stack est attaché au projet keenKonnect. ``` Workflow: 1. L’utilisateur recherche une plateforme de référence. 2. Il consulte une fiche. 3. Il vérifie les preuves. 4. Il ajoute une référence à un chart. 5. Le chart est revu. 6. Le chart est publié ou attaché au projet. 7. Un pack exportable est généré. Sorties attendues: - Reference Platform. - Reference Chart. - Reference Stack. - Evidence artifact. - Export pack. ## 28. keenKonnect — Release Pack But utilisateur: - Rendre un projet reproductible. - Préserver les documents essentiels. - Lier les références utilisées. - Exporter une version partageable. Workflow: 1. Le projet atteint une étape de publication. 2. Les fichiers importants sont sélectionnés. 3. Les références Kompendio sont épinglées. 4. Les tâches et décisions importantes sont résumées. 5. Un Release Pack est généré. 6. Le pack peut être archivé, partagé ou vérifié. Sorties attendues: - Manifest. - Artefacts. - Références épinglées. - Versions. - Éventuels checksums ou signatures. ## 29. KonnectED — rôle dans l’expérience KonnectED est l’espace où l’utilisateur apprend, pratique, prouve, valide et certifie. La boucle générale est: ```text Learn → Measure → Validate → Certify → Follow-up ``` - Knowledge fournit les ressources et parcours. - CertifiKation fournit évaluations, validations et certificats. - Kompendio documente les standards, outils et références d’interopérabilité. ## 30. KonnectED / Knowledge — apprendre But utilisateur: - Explorer une bibliothèque. - Trouver une ressource. - Suivre un cours. - Recevoir des recommandations. - Participer à un forum. - Contribuer à du contenu. Scénario: ```text Lina veut comprendre les bases de l’aménagement participatif. Elle ouvre Knowledge. Elle suit un module court. Sa progression est enregistrée. ``` Workflow: 1. L’utilisateur ouvre le catalogue. 2. Il cherche une ressource. 3. Il ouvre un cours ou une leçon. 4. Il progresse dans le contenu. 5. Il pose une question dans le forum. 6. Il reçoit une recommandation. 7. Sa progression est mise à jour. Sorties attendues: - LearningProgress. - KnowledgeRecommendation. - ForumTopic ou ForumPost. - CoCreationContribution si contribution. ## 31. KonnectED / CertifiKation — prouver et certifier But utilisateur: - Choisir un programme. - Suivre des jalons. - Passer une évaluation. - Soumettre une preuve. - Recevoir une validation pair ou mentor. - Obtenir un certificat. - Ajouter une preuve au portfolio. Workflow: 1. L’utilisateur choisit une CertificationPath. 2. Il consulte les compétences attendues. 3. Il réalise les activités requises. 4. Il passe une évaluation. 5. Il soumet un artefact si nécessaire. 6. Un pair ou mentor valide. 7. Le certificat est émis. 8. Le portfolio est mis à jour. Sorties attendues: - Evaluation. - PeerValidation. - Certificate. - Portfolio item. ## 32. KonnectED / Competence Evidence Layer But utilisateur: - Ne pas perdre les preuves d’apprentissage. - Pouvoir relier cours, évaluations, artefacts et certificats. - Rendre les compétences portables. Exemple d’évidence: ```text Qui: Lina Quoi: module d’aménagement participatif Quand: session du 12 mai Résultat: 86% Artefact: plan annoté Vérification: mentor approuvé ``` Workflow: 1. Une activité produit une preuve. 2. La preuve est normalisée. 3. Elle peut alimenter une évaluation. 4. Elle peut soutenir un certificat. 5. Elle peut apparaître dans un portfolio. 6. Elle peut être exportée ou vérifiée. ## 33. KonnectED / Kompendio — standards et références But utilisateur: - Comprendre quels standards et outils soutiennent la portabilité. - Documenter les choix d’intégration. - Publier des fiches ou charts de référence. Exemples de références: - OIDC pour identité. - LTI pour lancement d’outils. - xAPI pour événements d’apprentissage. - Open Badges pour credentials portables. - H5P pour activités interactives. - LRS pour journal d’apprentissage. Workflow: 1. Une équipe identifie un standard ou outil. 2. Kompendio documente son rôle. 3. Le choix mimic ou annex est explicité. 4. Une fiche est publiée. 5. La fiche devient réutilisable dans les projets. ## 34. Kreative — rôle dans l’expérience Kreative est l’espace de création, de conservation culturelle, d’archives, de galeries et de collaboration artistique. - Konservation préserve œuvres, archives, traditions et expositions. - Kontact relie les personnes, profils, opportunités et collaborations. ## 35. Kreative / Konservation — archiver et exposer But utilisateur: - Publier une œuvre. - Ajouter des métadonnées. - Créer une galerie. - Soumettre une tradition culturelle. - Créer une exposition virtuelle. - Enrichir le catalogue avec des tags ou classifications. Scénario: ```text Ariane numérise une collection de photos locales. Elle les ajoute à Konservation. Elle crée une galerie virtuelle sur l’histoire d’un quartier. ``` Workflow: 1. L’utilisateur téléverse une œuvre ou un document. 2. Il ajoute titre, description, média, région ou provenance. 3. Le système génère ou propose des tags. 4. Un modérateur peut approuver si nécessaire. 5. L’œuvre rejoint une galerie ou archive. 6. Une exposition peut être publiée. Sorties attendues: - KreativeArtwork. - Gallery. - TraditionEntry. - ArchiveDocument. - VirtualExhibition. - AICatalogueEntry. ## 36. Kreative / Kontact — rencontrer et collaborer But utilisateur: - Créer un profil professionnel. - Trouver des collaborateurs. - Voir des opportunités. - Créer un espace de collaboration. - Recevoir des recommandations ou endorsements. Workflow: 1. L’utilisateur complète son profil. 2. Il lie des œuvres ou tags. 3. Il reçoit des suggestions de contacts. 4. Il répond à une opportunité. 5. Il ouvre ou rejoint un workspace. 6. Une collaboration produit une œuvre, une recommandation ou un signal de confiance. Sorties attendues: - Profil. - CollabSession. - Opportunity. - Endorsement. - Portfolio créatif enrichi. ## 37. Workflow transversal: apprendre puis participer Scénario: ```text Lina apprend les bases de l’aménagement participatif dans KonnectED. Elle obtient une validation de compétence. Elle participe ensuite à un débat ethiKos sur l’espace public. Son contexte EkoH peut refléter progressivement son expertise. ``` Workflow: 1. Knowledge fournit le contenu. 2. CertifiKation valide une compétence. 3. Le portfolio garde la preuve. 4. EkoH peut refléter le domaine. 5. ethiKos utilise ce contexte dans certaines lectures. Sortie utilisateur: - L’apprentissage devient une capacité civique vérifiable. ## 38. Workflow transversal: décider puis construire Scénario: ```text Une communauté adopte une décision dans ethiKos. Une équipe ouvre un projet dans keenKonnect. Les artefacts sont stockés dans Stockage. Les références sont attachées via Kompendio. Un Release Pack documente le résultat. ``` Workflow: 1. Décision publiée. 2. Action d’impact créée. 3. Projet keenKonnect lié. 4. Équipe et tâches créées. 5. Fichiers et références ajoutés. 6. Pack reproductible publié. Sortie utilisateur: - La décision devient une réalisation traçable. ## 39. Workflow transversal: créer puis archiver Scénario: ```text Une artiste crée une œuvre avec une équipe. La collaboration est organisée dans Kontact ou keenKonnect. Le résultat est publié dans Kreative. Les documents sont préservés dans Konservation. ``` Workflow: 1. Profil ou opportunité. 2. Collaboration. 3. Production d’un artefact. 4. Publication. 5. Archivage. 6. Exposition ou portfolio. Sortie utilisateur: - La création devient visible, attribuée et préservée. ## 40. États d’interface communs Chaque workflow devrait prévoir au minimum: - État vide: rien n’a encore été créé. - État brouillon: l’utilisateur prépare une contribution. - État en cours: une action est ouverte. - État soumis: la contribution attend traitement. - État publié: la sortie est visible. - État archivé: la sortie reste consultable mais n’est plus active. - État erreur: quelque chose bloque. - État permission refusée: l’utilisateur comprend pourquoi. ## 41. États UX par type d’objet - **Débat:** brouillon, ouvert, fermé, archivé - **Consultation:** préparation, ouverte, clôturée, résultats publiés - **Vote:** non ouvert, ouvert, soumis, clôturé - **Projet:** idée, en cours, complété, validé - **Tâche:** todo, doing, done, blocked - **Ressource:** brouillon, publiée, versionnée, archivée - **Évaluation:** non commencée, en cours, soumise, réussie, échouée - **Certificat:** en attente, émis, révoqué si applicable - **Œuvre:** brouillon, soumise, approuvée, publiée, archivée ## 42. Permissions — niveau narratif Ce document ne définit pas toutes les permissions. Il recommande seulement de présenter les rôles de manière compréhensible. - Visiteur: peut lire ce qui est public. - Membre: peut contribuer selon les règles. - Contributeur vérifié: peut participer à certains espaces. - Expert ou mentor: peut valider ou commenter dans son domaine. - Owner ou responsable: peut gérer un projet, une consultation ou un contenu. - Modérateur: peut traiter les signalements. - Admin: peut configurer, auditer et gouverner. ## 43. Règles de lisibilité des résultats - Toujours afficher le résultat brut quand il existe. - Toujours nommer une lecture enrichie. - Toujours expliquer les inputs d’une lecture. - Toujours permettre de distinguer vote, stance, argument et lecture. - Toujours éviter les scores opaques. - Toujours relier un résultat à sa méthode. - Toujours garder une trace de publication. ## 44. Règles Kintsugi dans les workflows - Mimic signifie reproduire un pattern utile dans Konnaxion. - Annex signifie connecter un outil isolé comme sidecar. - La première passe privilégie le mimic natif. - Une annexe ne doit pas capturer la vérité du module. - Une annexe doit respecter identité, permissions, événements et export. - Une annexe doit produire des artefacts ou projections vérifiables. - Une annexe ne doit pas imposer un second shell utilisateur. ## 45. Où les annexes peuvent apparaître - **OpenSlides:** mode assemblée formelle; zone: ethiKos / admin ou decide methodology; statut: future annexe isolée. - **Your Priorities:** priorisation citoyenne; zone: ethiKos / consultations ou decide public; statut: future option. - **All Our Ideas:** comparaison paire-à-paire; zone: ethiKos / priorisation; statut: future option. - **Polis:** cartographie de consensus; zone: ethiKos / pulse ou insights; statut: différé. - **H5P:** activités interactives; zone: KonnectED / Knowledge; statut: annexe possible. - **LRS xAPI:** journal de preuves d’apprentissage; zone: KonnectED / evidence; statut: annexe possible. - **InvenTree:** BOM/inventaire; zone: keenKonnect / Kintsugi lanes; statut: annexe possible. - **Etherpad/HedgeDoc:** édition collaborative; zone: keenKonnect / docs; statut: annexe possible. - **OpenSearch:** recherche; zone: transversal; statut: annexe possible. ## 46. Anti-patterns à éviter - Transformer un workflow en liste d’endpoints. - Cacher une décision derrière un score non expliqué. - Faire croire qu’une lecture pondérée remplace le résultat brut. - Créer un module externe visible pour chaque inspiration. - Multiplier les menus au lieu de clarifier les parcours. - Mélanger débat, vote, évaluation et réputation. - Faire écrire une annexe dans les tables de vérité. - Ajouter une nouvelle interface avant de clarifier la sortie utilisateur. ## 47. Gabarit court pour documenter un workflow À utiliser pour les prochaines itérations: ```text Nom du workflow: Module: Sous-module: Utilisateur principal: Situation de départ: Objectif utilisateur: Étapes: 1. 2. 3. Sortie attendue: États importants: Permissions importantes: Liens avec autres modules: Kintsugi / Kompendio: Questions ouvertes: ``` ## 48. Exemple de fiche workflow: débat ethiKos ```text Nom du workflow: Participer à un débat structuré Module: ethiKos Sous-module: Korum Utilisateur principal: citoyen ou expert Situation de départ: un sujet est ouvert Objectif: comprendre les arguments et contribuer Étapes: 1. Ouvrir le topic 2. Lire la thèse 3. Lire les arguments pro/con 4. Choisir une stance 5. Ajouter un argument 6. Répondre ou suivre Sortie: stance + argument Kintsugi: Kialo/Consider.it mimés nativement ``` ## 49. Exemple de fiche workflow: certification KonnectED ```text Nom du workflow: Obtenir une certification Module: KonnectED Sous-module: CertifiKation Utilisateur principal: apprenant Situation de départ: un programme est disponible Objectif: prouver une compétence Étapes: 1. Choisir un parcours 2. Suivre les ressources 3. Passer une évaluation 4. Soumettre une preuve 5. Recevoir validation 6. Obtenir certificat Sortie: certificat + portfolio Kintsugi: evidence layer + standards portables ``` ## 50. Exemple de fiche workflow: projet keenKonnect ```text Nom du workflow: Exécuter un projet reproductible Module: keenKonnect Sous-module: Konstruct + Stockage + Kompendio Utilisateur principal: builder Situation de départ: une idée ou décision doit être réalisée Objectif: produire un projet documenté Étapes: 1. Créer un projet 2. Inviter une équipe 3. Créer des tâches 4. Ajouter fichiers 5. Attacher références 6. Générer Release Pack Sortie: projet + artefacts + références Kintsugi: lanes open-source possibles ``` ## 51. Priorités pour la prochaine version du document - Transformer les workflows principaux en fiches homogènes. - Ajouter les rôles par workflow. - Ajouter les états UI minimums. - Ajouter les erreurs ou blocages fréquents. - Ajouter les sorties attendues par écran. - Ajouter un tableau de navigation par module. - Ajouter une annexe de microcopies utilisateur. - Ajouter un index des termes. ## 52. Résumé final Ce document décrit Konnaxion comme une série de parcours utilisateur plutôt que comme une collection de modules techniques. La logique principale est: ```text Comprendre → contribuer → décider → apprendre → prouver → construire → préserver → mesurer ``` ethiKos donne la structure civique. Kollective Intelligence donne les lectures et contextes. KonnectED transforme l’apprentissage en preuve. keenKonnect transforme les décisions et idées en projets reproductibles. Kreative rend la création visible, collaborative et préservée. Kintsugi et Kompendio ne remplacent pas ces parcours. Ils renforcent leur cohérence, leur portabilité, leur auditabilité et leur capacité à intégrer des outils sans perdre la source de vérité. ## 53. Notes de conception rapides par écran - **/ethikos/learn/guides:** rassurer et expliquer avant action. - **/ethikos/pulse/overview:** montrer l’état du système. - **/ethikos/deliberate/[topic]:** structurer les raisons. - **/ethikos/trust/profile:** expliquer la confiance. - **/ethikos/decide/public:** permettre une décision claire. - **/ethikos/decide/results:** rendre les résultats comparables. - **/ethikos/impact/tracker:** suivre la promesse. - **/ethikos/insights:** interpréter sans confondre. - **/ethikos/admin/audit:** préserver la vérifiabilité. - **/projects:** trouver ou créer un espace d’exécution. - **/projects/[slug]:** coordonner le travail. - **/learn:** explorer et apprendre. - **/course/[slug]:** suivre une progression. - **/certs:** prouver et certifier. - **/kreative:** créer et exposer. - **/archive:** préserver et transmettre. - **/connect:** rencontrer et collaborer. ## 54. Questions ouvertes - Quels workflows doivent devenir prioritaires pour l’implémentation UI? - Quels rôles doivent être visibles dès la première version? - Quels états d’erreur méritent une microcopie dédiée? - Quels résultats doivent être exportables? - Quels workflows doivent être testés en smoke test? - Quels écrans doivent rester publics? - Quels écrans doivent nécessiter authentification? - Où faut-il afficher les explications de Smart Vote sans surcharger l’utilisateur? - Où faut-il afficher les preuves EkoH? - Quels outils Kintsugi doivent rester seulement mentionnés comme futurs? ## 55. Fin du brouillon Ce document est une base narrative et fonctionnelle. Il doit rester vivant, mais ne doit pas devenir une spec technique exhaustive. Les prochaines versions peuvent ajouter des fiches workflow plus détaillées sans changer l’intention générale. ## 56. Index de workflows potentiels - Créer une consultation - Soumettre une suggestion citoyenne - Trier une suggestion - Ouvrir un débat - Prendre position - Ajouter un argument - Répondre à un argument - Signaler un argument - Modérer un argument - Clôturer un débat - Créer une décision - Configurer une modalité de vote - Voter - Publier une baseline - Publier une lecture Smart Vote - Comparer deux lectures - Créer une action d’impact - Suivre une action - Ajouter un feedback d’impact - Auditer une décision - Consulter son profil EkoH - Modifier sa visibilité - Explorer des scores par domaine - Créer un projet - Inviter une équipe - Créer une tâche - Assigner une tâche - Joindre un fichier - Créer une version - Restaurer une version - Attacher une référence Kompendio - Publier un Reference Chart - Générer un Release Pack - Chercher une ressource Knowledge - Suivre un cours - Participer à un forum - Créer une contribution de contenu - Recevoir une recommandation - Choisir une certification - Passer une évaluation - Soumettre une preuve - Valider comme pair - Obtenir un certificat - Mettre à jour un portfolio - Téléverser une œuvre - Créer une galerie - Soumettre une tradition - Publier une exposition - Créer un profil créatif - Trouver une opportunité - Créer une session de collaboration - Laisser une recommandation ================================================================================================ FILE: docs/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: afda7638e8f10ca93e5baa571a6937c2216b7a654057a0974fcbae0dc66f9b55 CONTENT_BYTES: 1901 ================================================================================================ # Konnaxion — Documentation ## Scope Konnaxion is an **ecosystem system** of the kOA Digital Ecosystem and a **platform** in its own product scope. It owns its civic/public domain state and its application surfaces. It is not the kOA Digital Ecosystem itself, and it does not absorb the authority of Orgo, Kristal, SemantiK Architect or kOA-Linux when integrated with them. Within Konnaxion, the word **module** is only a convenient product/UI term. Architecture documents use the more precise terms **domain**, **application**, **service**, **component**, **gateway** and **external ecosystem system**. ## Canonical reading order 1. `Technical-Reference/DocV14/Konnaxion v14 - Full-Stack Technical Specification.md` 2. `Technical-Reference/GLOSSARY.md` 3. `Technical-Reference/BOUNDARIES_AND_OWNERSHIP.md` 4. `Technical-Reference/CONTRACTS.txt` 5. `Technical-Reference/EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md` 6. `Technical-Reference/CODE_ALIGNMENT_NOTES.md` 7. `Technical-Reference/DocV14/Konnaxion v14 - Site Navigation Map.md` 8. `Konnaxion_User_Workflows.md` ## Architectural invariants - One authoritative owner per state. - No direct write across ownership boundaries. - Source facts and derived readings are distinct. - A reading never retroactively becomes a source fact. - EkoH context does not become a civic vote. - Smart Vote does not silently replace a public baseline. - External systems integrate through explicit contracts, not shared internal tables. - Presentation does not transfer authority. - A Konnaxion deployment inside kOA-Linux remains Konnaxion-owned at the domain level. ## Core Konnaxion rule > **Single Truth, Multiple Readings.** A stable source event or civic state may be interpreted through one or more explicitly declared readings. The reading identifies the method and context used to derive it; it does not mutate the source. ================================================================================================ FILE: docs/status/2026-08-27-technical-maturity-assessment.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3980af330b06e0df63b8a651da3f35af7dc6f83a97ae53078fddb6d2572742e8 CONTENT_BYTES: 5821 ================================================================================================ # Konnaxion Technical Maturity Assessment **Assessment date:** 2026-08-27 **Current status:** Advanced Functional Beta **Estimated engineering maturity:** ~75% **Estimated Release Candidate readiness:** ~55–60% > This assessment is a technical maturity checkpoint. It is not a Release Candidate declaration and the percentages are engineering estimates, not mathematical completion metrics. ## Executive summary Konnaxion has moved beyond the prototype stage and now represents a substantial functional application platform. The strongest product areas are ethiKos, EkoH, and Smart Vote. The Django backend, Next.js frontend, migrations, production build, seed/import workflows, and end-to-end walkthrough infrastructure demonstrate substantial implementation maturity. The main weakness is uneven qualification across the full product surface. Some modules are advanced, while others still contain partial, placeholder, demonstration, or insufficiently tested functionality. The most accurate current classification is: **Advanced Functional Beta** ## Maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 85–90% | | Backend implementation | 75–80% | | Frontend implementation | 75–80% | | ethiKos | ~85% | | EkoH | 85–90% | | Smart Vote | 80–85% | | TeamBuilder | 65–70% | | Kontrol | 60–70% | | KonnectED | 55–65% | | keenKonnect | 50–60% | | Kreative | 40–50% | | Automated testing | 55–65% | | End-to-end user workflows | 60–70% | | Application security maturity | 65–75% | | Deployment and packaging | 60–70% | | CI and release qualification | 40–50% | | Overall engineering maturity | ~75% | | RC readiness | ~55–60% | ## Strongest areas ### Frontend The inspected V4.1.3 build evidence showed: - successful TypeScript typecheck; - successful Next.js production build; - successful type validation; - successful generation of 115 static pages. The frontend is therefore substantially implemented and is not merely a collection of mockups. However, some secondary areas still contain placeholder, mock, scaffold, or demonstration-oriented behavior. ### Backend The Django backend includes: - models; - serializers; - services; - APIs; - migrations; - PostgreSQL; - Redis; - Celery; - Django REST Framework. The V4.1 validation evidence showed successful migrations, a clean Django system check, and no migration drift for ethiKos, EkoH, and Smart Vote. ## Module maturity ### ethiKos — ~85% ethiKos is one of the most advanced modules and includes: - topics; - stances; - arguments; - categories; - scenario import; - API; - seed data; - frontend workflows. A targeted backend campaign previously completed 35 tests successfully across ethiKos and Smart Vote-related functionality. ### EkoH — 85–90% EkoH is the most mature functional area observed. It includes: - expertise modeling; - scores; - visibility and privacy rules; - access scopes; - organization context; - history; - contextual analytics; - Smart Vote integration. A real privacy-policy defect was discovered during V4.1 validation and the later inspected snapshot contained a corresponding correction. This is a positive sign of genuine qualification activity. ### Smart Vote — 80–85% Smart Vote includes: - reading logic; - weighting; - ballots; - ethiKos integration; - EkoH integration; - baseline and expertise readings; - recusals. It is clearly beyond alpha maturity. ## Less mature areas The following modules are implemented but currently less mature or less thoroughly qualified: - TeamBuilder; - Kontrol; - KonnectED; - keenKonnect; - Kreative. The main issue is not necessarily absence of code. It is that implementation depth and automated test coverage are inconsistent across the platform. ## Test and qualification state Konnaxion has meaningful automated testing, but coverage is uneven. The most mature modules have useful tests, including privacy and business-rule tests. The project also contains Playwright workflows and guided walkthroughs, which provide a strong base for end-to-end release gates. However, the complete platform is not yet systematically qualified as one release. The current relationship can be summarized as: > **implemented functional surface > fully qualified functional surface** ## Main blockers before pre-RC Konnaxion should not yet be classified as pre-RC. The main remaining requirements are: 1. define the exact Version 1 release scope; 2. complete or explicitly defer unfinished product surfaces; 3. reach zero backend test failures; 4. make typecheck, lint, and production build mandatory; 5. expand automated testing to poorly covered modules; 6. convert major Playwright workflows into mandatory release gates; 7. test clean installation and migration paths; 8. test backup and restore; 9. qualify deployment reproducibility; 10. establish a versioned and repeatable release process. ## Release interpretation Konnaxion is already a substantial functional product. Its main challenge is to make release qualification catch up with the breadth of the implementation. > **Konnaxion: the product is largely visible and functional, but its qualification now needs to catch up with its functional surface.** ## Recommended public status **Advanced Functional Beta** Suggested short description: > Konnaxion has reached an advanced functional beta. Core application areas including ethiKos, EkoH and Smart Vote are substantially implemented, with working backend migrations, production frontend builds and growing automated test coverage. Remaining work focuses on platform-wide qualification, completion or deferral of unfinished surfaces, deployment reproducibility, security validation and mandatory end-to-end release gates. This is not yet a Release Candidate. ================================================================================================ FILE: docs/status/2026-09-05-bug-harvest-mass-audit.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3db4745bf1e9ec8dd5ec500ad9b757049933383a0e8a4af03fd911ef1ed2511f CONTENT_BYTES: 6784 ================================================================================================ # Konnaxion Bug Harvest — mass audit 2026-09-05 ## Scope This harvest intentionally does **not** repeat the already-green full backend suite, broad 124-route Playwright smoke, or the ethiKos/EkoH/Smart Vote delivery workflow. It targets the evidence-depth gap documented for the less-qualified platform surfaces. The source scan found 282 hotspot references across the selected frontend surfaces. The largest concentrations were KonnectED (84), keenKonnect (61), Kontrol (50), TeamBuilder (38), Kreative (25), and Konsensus (13). Common signals were mock/stub data, simulated success messages, TODOs, direct fetches, and console-only error paths. ## Fixed / wired in this batch ### TeamBuilder - Problem library now reads the existing `/api/teambuilder/problems/` backend instead of `MOCK_PROBLEMS`. - Create Problem now persists real `Problem` rows instead of displaying simulated success. - Problem detail now calls a real typed `getProblemDetail()` service method instead of an unsafe cast to a missing method. - `/teambuilder/create?problemId=...` now carries `problem_id` into session creation, preserving the intended Problem → BuilderSession relationship. - Duplicate `sectionLabel` JSX prop removed. - Added typed Problem request/response contracts to the frontend TeamBuilder service. ### KonnectED Existing backend models were present but several were not routed. This batch exposes canonical `/api/konnected/*` endpoints for: - recommendations; - learning progress; - mentor directory; - mentorship requests; - co-creation projects/contributions; - forum topics/posts. Additional safeguards: - recommendations are scoped to the authenticated user; - progress is scoped to the authenticated user and server-assigns ownership; - mentorship requests server-assign the mentee and expose only that learner's requests; - mentor discovery exposes active profiles; - forum write ownership is enforced for update/delete; - co-creation projects are read-only because the current model has no owner field; no ownership semantics were invented; - co-creation contributions permit authenticated creation but do not expose arbitrary update/delete mutation. Frontend wiring updated: - Community Discussions now uses canonical `konnected/forum-topics` and `konnected/forum-posts` endpoints. - Mentorship now loads real `MentorProfile` rows and creates real `MentorshipRequest` rows. - KonnectED dashboard uses canonical KonnectED and keenKonnect routes instead of stale root-level endpoint guesses. - My Teams now uses keenKonnect project-team membership and a server-side `leave` action. - Recommended Resources now uses the canonical recommendations route and no longer treats a failed feedback request as success. ### keenKonnect team membership - `ProjectTeamSerializer` now exposes stable project/user IDs and `project_title` for consumers. - Added an authenticated `my-teams` projection for the current user. - Added a guarded `leave` action; non-members cannot remove another user's membership and project owners must transfer ownership first. ### Test orchestration - `full-scan.ps1` no longer keeps the smoke Next process alive by default. Persistence is now opt-in via `-KeepFrontend`, preventing the inherited-process/pipe hang seen in the mega campaign. - Added a dedicated Playwright harvest config and workflow. - Added a one-click targeted Bug Harvest GUI runner. It runs only the new backend contracts and the new TeamBuilder/KonnectED depth workflow. It starts a fresh Next dev server on port 3001 so it cannot accidentally test a stale production build on port 3000. ## Captured but intentionally not faked in this batch These remain open because the current backend contract/model does not safely support the UI semantics yet: - **KonnectED learning paths:** UI still contains mock fallback and TODO complete/leave actions; no equivalent complete domain contract was found in this source pack. - **KonnectED standalone Team Builder:** UI describes a free-standing team with arbitrary email members, while the available keenKonnect model represents project membership. These are not silently treated as the same object. - **Recommendation feedback persistence:** the UI can attempt feedback, but no persisted feedback model/endpoint exists. Failure is now surfaced instead of falsely acknowledged. - **Kontrol roles/community/dashboard:** several pages remain mock-heavy; the inspected backend does not contain matching first-class role/community data contracts for those UI shapes. - **Kreative collaborative-space creation:** current UI fields do not map cleanly to the existing `CollabSession` model, so no lossy persistence mapping was invented. - **Kreative traditions archive:** frontend expects richer category/community/status/tag/year semantics than the inspected `TraditionEntry` model exposes. - **keenKonnect AI team matching:** still explicitly mock/TODO; no complete matching backend contract was present in the inspected source pack. - **keenKonnect knowledge document-management simulation:** save/version/comment flows still advertise simulation and need a real document-version/comment contract before wiring. ## Targeted validation added Backend targeted tests cover: - forum topic/post ownership; - mentor directory + mentorship request; - user-owned learning progress; - user-scoped nested recommendations; - read-only co-creation project exposure; - cross-user forum mutation denial; - existing TeamBuilder Problem API tests. Playwright targeted harvest covers: 1. authenticated real Problem creation; 2. Problem library UI visibility; 3. Problem detail UI visibility; 4. authenticated real ForumTopic + ForumPost creation; 5. Active Threads UI visibility; 6. real dynamic thread detail navigation + reply write through UI; 7. new KonnectED read API surfaces; 8. Mentorship and Dashboard runtime console/network findings. The existing full release gates should remain release gates, not the default bug-harvest loop. ## Navigation-depth findings A static navigation-target pass found additional interactions that broad page-load smoke cannot prove. The forum thread target was fixed in this batch by adding a real dynamic thread page backed by ForumTopic/ForumPost and a real reply action. The remaining high-confidence missing/static targets to disposition in later batches include: - keenKonnect document detail and workspace join/request-access targets; - KonnectED learning-library `/course/*` target; - several Kreative collaboration/profile/idea view/edit targets; - TeamBuilder human geo/language/schedules targets. These were captured rather than mass-created as placeholder pages, because a route shell without a matching domain contract would increase visible surface without increasing real completion. ================================================================================================ FILE: docs/status/2026-09-05-technical-maturity-assessment.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 3a560acd67b239b8be733073baaa00c73f85053bcb56960af52245ef6b75f230 CONTENT_BYTES: 11017 ================================================================================================ # Konnaxion Technical Maturity Assessment **Assessment date:** 2026-09-05 **Previous assessment:** 2026-08-28 **Current status:** Advanced Functional Beta — Release Qualification and Hardening **Estimated engineering maturity:** ~88% **Estimated Release Candidate readiness:** ~76–80% > This assessment is a technical maturity checkpoint. It is not a Release Candidate declaration. Percentages are engineering estimates based on validated implementation and qualification evidence, not mathematical completion metrics. ## Executive summary Konnaxion has advanced materially since the 2026-08-28 assessment, primarily through **diagnostic coverage, targeted defect closure, release-gate hardening, and reproducible local qualification** rather than through feature expansion. The LevelUpDiag progression covering repository/static analysis, backend, frontend, API contracts, runtime/browser behavior, jobs, security/auth, capsule integration, deployed-runtime checks, deep scan, and correlation/triage has been completed. The final correlation/triage campaign passed. The only deployed-runtime warning is expected because remote diagnostics are intentionally disabled; it is not currently classified as a product defect. The frontend release-gate surface has also improved substantially. TypeScript, ESLint, Next.js production build, Jest, pattern scanning, the public ethiKos Wave 1 workflow, and the authenticated ethiKos workflow have all produced green targeted evidence. The aggregate Playwright smoke campaign reached 123 passing tests with one authenticated failure caused by the smoke harness using an origin not trusted by the local CSRF configuration. That harness defect was corrected, and the previously failing authenticated workflow subsequently passed 2/2 on the canonical local origin. The current classification is therefore: **Advanced Functional Beta — Release Qualification and Hardening** Konnaxion is still **not a Release Candidate**. The largest remaining gaps are release-process finalization, backup/restore qualification, clean-target deployment reproducibility, final Version 1 scope control, and completion of final aggregate-gate evidence after tooling stabilization. ## Maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 90–93% | | Backend implementation | 90–93% | | Frontend implementation | 86–90% | | ethiKos | 94–96% | | EkoH | 93–96% | | Smart Vote | 92–95% | | TeamBuilder | 75–80% | | Kontrol | 68–74% | | KonnectED | 65–72% | | keenKonnect | 62–68% | | Kreative | 50–58% | | Automated testing | 84–88% | | End-to-end user workflows | 90–93% | | Application security maturity | 84–88% | | Deployment and packaging | 76–82% | | CI and release qualification | 68–74% | | Backup / restore qualification | 45–55% | | Overall engineering maturity | ~88% | | RC readiness | ~76–80% | ## Qualification evidence completed since 2026-08-28 ### 1. LevelUpDiag qualification progression completed The main diagnostic progression has been completed through correlation and triage. Validated state: - N00 Control & Discovery — PASS - N01 Repository & Static — PASS - N02 Backend / Django / DB — PASS - N03 Frontend / Next — PASS - N04 API Contracts — PASS - N05 Runtime & Browser — targeted failures corrected and validated - N06 Jobs / Redis / Celery — PASS - N07 Security & Auth — production/security qualification validated - N08 Capsule Local — targeted lifecycle/dependency issues corrected - N09 Deployed Runtime — expected WARN because remote diagnostics are disabled - N10 Deep Scan — targeted backend defects resolved; frontend orchestration defects corrected - N11 Correlation & Triage — PASS No broad rerun was required after targeted green results. ### 2. Deep backend qualification issue resolved A targeted N10 backend campaign was executed against a freshly created test database rather than the reused pytest database. Validated result: ```text 7 passed ``` The earlier warning was traced to stale reused test-database schema state rather than an active backend implementation defect. ### 3. Frontend aggregate gate made fail-safe `frontend/tools/full-scan.ps1` previously had several release-gate weaknesses: - ESLint invocation incompatible with the installed ESLint formatter set; - pattern scanning could throw when a file produced null content; - Playwright failures were not reliably propagated to the script exit code; - a running `next start` process could serve stale chunk references after `.next` was replaced; - the smoke server origin could conflict with local CSRF trust settings; - spawned Next.js process trees could keep smoke report files open. The scan wrapper was hardened to: - propagate failing step exit codes; - make pattern scanning null-safe; - use the supported ESLint invocation; - use the local backend proxy by default for local qualification; - build before smoke execution; - start the smoke target on the canonical trusted local origin; - stop the complete Next.js smoke process tree after execution; - restore a pre-existing frontend runtime state when appropriate. ### 4. Aggregate frontend evidence substantially green A full-scan execution produced: ```text TypeScript exit=0 ESLint exit=0 Next build exit=0 Jest exit=0 Pattern scan exit=0 Playwright SMOKE exit=1 ``` The Playwright smoke result contained: ```text 123 passed 1 failed ``` The single failure was the authenticated ethiKos workflow, which reported: ```text HTTP 403: /api/ethikos/stances ``` This was traced to the test harness running on port 3100 while local Django CSRF trust was configured for the canonical frontend origin on port 3000. The product workflow itself was then rerun on the canonical origin and passed. ### 5. Authenticated ethiKos workflow green The previously red authenticated workflow was rerun directly after the origin correction. Validated result: ```text 2 passed (22.8s) ``` This closes the observed authenticated Playwright failure from the aggregate smoke campaign. ### 6. Public ethiKos Wave 1 workflow green The targeted public Wave 1 workflow is green. Validated result: ```text 1 passed ``` The test now correctly accepts the semantic Smart Vote 404 used when an ethiKos topic has no bound Smart Vote reading context. This is intentional product behavior, not a missing-data defect. ### 7. Smart Vote no-binding semantics clarified For topics without a `SourceConsultationBinding`, the canonical behavior is a semantic 404 indicating that no Smart Vote reading context is bound to the ethiKos topic. The frontend and browser workflow now treat that response as an expected no-reading condition rather than as a generic application failure. No artificial binding or synthetic 200 response was introduced. ### 8. Production/security posture remains green Previously validated production/security controls remain part of the current qualified baseline: - `DEBUG=False`; - production hosts configured; - production frontend base URL configured; - production OpenAPI URL configured; - SSL redirect enabled; - secure session and CSRF cookies; - HttpOnly session and CSRF cookies; - `X_FRAME_OPTIONS=DENY`; - content-type sniffing disabled; - HSTS enabled; - `manage.py check --deploy` passing; - Flower port 5555 not publicly exposed. No new evidence in the current campaign invalidated these results. ## Current release interpretation Konnaxion has moved from broad integration hardening toward **repeatable release qualification**. The strongest evidence now covers: - backend correctness; - API contracts; - production frontend build viability; - type safety and linting; - public and authenticated ethiKos browser workflows; - Smart Vote integration semantics; - local jobs/runtime integration; - production/security configuration; - targeted deep-scan defect closure; - correlation and triage. The remaining gap is less about basic application functionality and more about converting the current qualification evidence into a fully repeatable release process. ## Remaining blockers before Release Candidate ### 1. Finalize Version 1 scope Still open. The exact Version 1 product surface must be frozen, with incomplete secondary surfaces either completed or explicitly deferred. ### 2. Complete final aggregate release-gate proof The underlying frontend gates and the previously failing authenticated workflow are green, and the aggregate wrapper has been corrected. A final aggregate run after the last process-lifecycle cleanup has intentionally not been repeated because the qualification strategy avoids redundant reruns after targeted green evidence. Before an RC declaration, one clean aggregate release-gate execution should be captured as release evidence. ### 3. Backup and restore drill Still open. The PostgreSQL backup and restore tooling exists, but an isolated destructive restore drill followed by application validation remains required. ### 4. Clean-target deployment reproducibility Still open. Production configuration is substantially hardened, but a complete clean-target deployment from documented inputs has not yet been captured as reproducible release evidence. ### 5. OpenAPI cleanup Still open. drf-spectacular schema warnings and duplicate/inferred-operation issues should be reduced or explicitly dispositioned before RC. ### 6. Secondary-surface qualification Still open. Kontrol, KonnectED, keenKonnect, Kreative and portions of TeamBuilder remain less deeply qualified than the ethiKos/EkoH/Smart Vote core. ### 7. Versioned release process In progress. The existing release marker is: ```text v0.8.0-beta.1 ``` This assessment recommends the next checkpoint as: ```text v0.8.0-beta.2 ``` The recommended interpretation is a continuation of the 0.8 beta line focused on qualification and hardening rather than a new feature-version boundary. ## Release recommendation Recommended current public status: **Advanced Functional Beta — Release Qualification and Hardening** Recommended version marker: **v0.8.0-beta.2** This tag should represent the current qualified beta checkpoint after the frontend workflow corrections, diagnostic progression, release-gate hardening, and updated technical maturity assessment. It should **not** be described as a Release Candidate. ## Suggested public description > Konnaxion is an advanced functional beta now focused on release qualification and hardening. Core backend, API, production build, security, and ethiKos/EkoH/Smart Vote workflows have strong automated evidence, including green public and authenticated browser workflows and completed diagnostic correlation/triage. Remaining work is concentrated in final release-gate capture, backup/restore qualification, reproducible clean deployment, secondary-surface qualification, OpenAPI cleanup, and Version 1 scope control. This release is not yet a Release Candidate. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-real-findings.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 4b67cc1693cade313e7411e978c5b99d56b3ec72c0a38c3afd4fd2b8962d4ede CONTENT_BYTES: 1457 ================================================================================================ # Konnaxion targeted bug harvest — real findings batch 2026-09-06 ## Evidence state The targeted backend surface had already passed its dedicated tests. The latest frontend harvest reached the consolidated final report instead of stopping at the first locator/runtime issue. ## Real findings fixed in this batch - Local isolated frontend `:3001` was absent from Django local CSRF/CORS trusted origins, while the harvest intentionally runs on `127.0.0.1:3001`. - KonnectED Dashboard requested the nonexistent `/api/community-dashboard/` endpoint and silently translated failure into synthetic zero metrics. - KonnectED Mentorship used deprecated Ant Design Card/Modal props. - The harvest attributed previous-route navigation cancellations to the next route and did not strictly prove the UI ForumPost mutation response. ## Harness behavior after this batch - targeted routes settle before the next navigation; - Next static/RSC `ERR_ABORTED` navigation noise is excluded narrowly; - API request failures remain visible; - the UI Forum reply must return a real 2xx POST response; - the persisted reply is asserted in the rendered List; - findings continue to be accumulated and reported together. ## Separate local runtime state The local Django runtime reported one unapplied `smart_vote` migration. This is a database state item, not an application-code patch. No ethiKos / EkoH / Smart Vote ownership or source-truth contract is changed. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-wave2a-mass-update.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: dfac143cf63a689cb9fa007738787d5c69963cbe49c469ee460e7f9c20df7be3 CONTENT_BYTES: 2583 ================================================================================================ # Konnaxion Bug Harvest Wave 2A — Mass Update ## Scope This batch follows the Wave 2 harvest across keenKonnect, Kreative and Kontrol. ## Runtime defects addressed - Kreative dashboard no longer references missing seeded media files directly. - `KreativeArtworkSerializer` exposes `media_url` only when the underlying storage object exists. - Kreative dashboard now derives featured work, gallery preview, creator activity and recent activity from the real artwork API. - Document Management uses `destroyOnHidden` instead of the deprecated drawer lifecycle prop. - Kontrol dashboard no longer presents fabricated governance KPIs or infrastructure health values. - Kontrol dashboard now reads the real admin user, moderation and audit endpoints. - Wave 2 route harvesting waits for delayed table/API activity before moving to the next route, reducing navigation-abort misattribution. ## False-success / persistence corrections - Submit Creative Work now persists a real `KreativeArtwork` through multipart API upload. - Cultural Archive contributions on Kreative Mentorship now persist real `TraditionEntry` rows. - Showcase review submission remains unavailable because there is no dedicated review contract; the UI no longer claims success. - Mentorship request delivery remains unavailable and the action is disabled rather than claiming success. - keenKonnect Document Management is explicitly session-local until a general document persistence contract exists. - Kontrol Users is explicitly read-only for user mutations. - Kontrol Roles is explicitly a read-only role/permission preview until a role-write contract exists. - Audit CSV export and moderation bulk actions are marked unavailable where no matching backend contract exists. ## Source audit semantics Wave 2 source audit now distinguishes: - **blocking source gaps**: undeclared test data, fake success, API/backend wiring TODOs, placeholder promises, fake admin mutations; - **declared deferred surfaces**: explicit preview/read-only/unavailable product areas. The current batch reduces blocking matches in the Wave 2 target set from **30 to 0** while keeping declared deferred surfaces visible in the harvest log. ## Architectural note No new backend domain model is invented to make a UI pass. Existing owners remain unchanged: - keenKonnect owns project/collaboration state; - Kreative owns artworks, galleries, collaboration sessions and traditions; - Kontrol owns platform administration/moderation surfaces. A UI is wired only where an existing backend contract matches the product semantics. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-wave2b-mass-update.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: f146b18d9395495d98176cf57e29be8aefbc60cba66402efb750f20ec425fcbd CONTENT_BYTES: 2265 ================================================================================================ # Bug Harvest Wave 2B — mass update **Date:** 2026-09-06 **Scope:** keenKonnect + Kreative + Kontrol secondary-surface hardening ## Qualification context Wave 1 TeamBuilder/KonnectED is already green. Wave 2A converted the first 30 blocking source gaps into real persistence or explicitly declared deferred surfaces. The post-Wave-2A source audit reported `blocking=0` and `declared-deferred=30`, while runtime still exposed AntD deprecations, React.Fragment warnings and navigation-cancellation noise. ## Wave 2B classification This batch follows the documented pre-RC rule: complete secondary product surfaces where a real backend contract exists, otherwise explicitly defer them. It does not create new ownership boundaries or parallel APIs. ### Real contracts used - `keenkonnect/projects/` - `kreative/artworks/` - `kreative/traditions/` - `kreative/collab-sessions/` - Kontrol admin read surfaces already exposed by the canonical router - canonical authenticated user update for the writable display name ### Explicitly deferred - AI matching persistence/membership actions - general Knowledge document persistence/versioning - KeenKonnect Workspace persistence/membership - native KeenKonnect Impact analytics/report persistence - expertise editing from KeenKonnect; expertise source ownership remains EkoH - Idea Incubator writes - showcase-review writes - mentor-request delivery - Kontrol role/user mutations without a write contract - community-moderation mutations without a dedicated contract ## Runtime/harness cleanup - AntD deprecations corrected on targeted secondary surfaces. - legacy `@ant-design/compatible` usage removed from Knowledge Document Management. - targeted Kontrol message calls use context-bound message APIs. - navigation-time `ERR_ABORTED` requests are correlated with page transition instead of being reported as backend defects. - Wave 2 now performs real UI POST assertions for Artwork and CollabSession and cleans created data afterward. ## Static validation before packaging ```text changed product/test files: 33 source audit blocking: 0 declared deferred markers: 108 TypeScript parser diagnostics: 0 known phantom endpoint literals: 0 ``` The next evidence needed is one targeted Wave 2 rerun only. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-wave2c.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: f5eacaeaa3b356ae53b5122b94528fd19c83a1a9034a63a8776b44691ee02a91 CONTENT_BYTES: 1421 ================================================================================================ # Bug Harvest Wave 2C — 2026-09-06 ## Input evidence Wave 2B established: - all expanded prewarm routes returned HTTP 200; - source audit: blocking=0, declared-deferred=108; - keenKonnect project creation reached HTTP 201; - the runtime workflow then exhausted the 360s test timeout waiting for the `Other` option in the Submit Creative Work category Select; - because the test timeout closed the browser context, the following Kontrol step failed while reading cookies and is not classified as a Kontrol API defect; - the backend log contains no artwork/collab POST after that point; - Track Project Impact emitted a `Tabs.TabPane` deprecation warning. ## Fix classification - harness robustness: targeted bugfix / platform readiness - `Tabs.TabPane`: tech debt cleanup - Ant Design static message context on real Kreative mutations: tech debt cleanup - stale `Harvest2 ...` records after interrupted runs: test hygiene No product ownership boundary changes are introduced. No missing backend contract is invented. Declared preview/read-only surfaces remain declared deferred. ## Required validation Run only the Wave 2 targeted harvest. A successful pass must prove: - source audit remains blocking=0; - real Artwork POST succeeds and is cleaned; - real CollabSession POST succeeds and is cleaned; - Kontrol real read endpoints remain healthy; - no runtime finding remains in the targeted Wave 2 surfaces. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-wave2d.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: cd53dacd26b812db5e42f7a9780c21169a889cdfdb1be2afa1743b42ad22d718 CONTENT_BYTES: 1228 ================================================================================================ # Konnaxion Bug Harvest Wave 2D ## Incoming evidence Wave 2C: - route prewarm: all targeted routes HTTP 200; - source-gap audit: blocking=0, declared-deferred=108; - backend admin/Kontrol endpoints: healthy; - stale Harvest2 project cleanup: verified; - runtime blockers reduced to: 1. AntD Select harness selection stayed on `Art` instead of `Other`; 2. React.Fragment `autoFocus` warning on two preview-heavy KeenKonnect pages. No Kreative artwork or CollabSession POST had yet occurred because the harness stopped before form submission. ## 2D changes - AntD category selection now targets the visible dropdown option directly. - The selected value remains asserted before submit. - The exact `React.Fragment` + `autoFocus` compatibility warning is retained in logs as `HARVEST2 DEPENDENCY-WARNING` but does not fail the product runtime gate. - The React-19-specific Ant Design runtime patch import is removed from the root layout because this frontend is still on React 18. - No product persistence contract is invented or broadened. ## Exit criterion The next Wave 2 run must reach: - real Artwork POST 2xx + cleanup; - real CollabSession POST 2xx + cleanup; - Kontrol API checks; - source audit blocking=0. ================================================================================================ FILE: docs/status/2026-09-06-bug-harvest-wave2e-context-isolation.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 5b810dc788b2627d9580cef88c0851a0f3ed058df82f9625c17ce01667f87785 CONTENT_BYTES: 1056 ================================================================================================ # Wave 2E — Playwright context isolation ## Classification `platform_readiness` The observed failure is not currently supported as a product/API defect: the route prewarm remained HTTP 200 and backend runtime evidence showed healthy API responses before the Playwright renderer reported `Page crashed`. ## Harness change Wave 2 remains one large campaign, but runtime qualification is now split into independent Playwright tests: - prewarm route families; - keenKonnect runtime/API; - Kreative runtime/API; - Kontrol runtime/API; - source-gap audit. Each runtime test receives a fresh BrowserContext/Page from Playwright. Failure in one runtime block does not prevent evidence collection from later blocks. ## Exit interpretation - Crash reproducible inside one isolated module: candidate `targeted_bugfix` for that module/route. - Crash disappears under isolated contexts: confirmed harness/resource-orchestration issue under `platform_readiness`. - API 4xx/5xx or page runtime error remains: classify and fix from the concrete evidence. ================================================================================================ FILE: docs/status/2026-09-06-technical-status-report-aligned.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 9a7627210d1829e5cff0bfd050a15bdd28170050827ab72b84b168dcb229786b CONTENT_BYTES: 16358 ================================================================================================ # Konnaxion Technical Status Report **Assessment date:** 2026-09-06 **Previous assessment:** 2026-09-05 **Current status:** Advanced Functional Beta — Final Release Candidate Qualification **Estimated engineering maturity:** ~92% **Estimated Release Candidate readiness:** ~86–90% **Recommended version checkpoint:** `v0.8.0-rc.1` (GitHub prerelease) **Version lineage:** public historical release `v0.1.0-demo-stable`; latest documented beta marker `v0.8.0-beta.1`; previously recommended next beta `v0.8.0-beta.2`. **Production status:** Not yet approved for public production deployment > This is an engineering status checkpoint based on validated local/runtime evidence, targeted bug-harvest evidence, the delivery workflow, and security diagnostics. Percentages are engineering estimates, not mathematical completion metrics. ## Executive summary Konnaxion has advanced materially since the 2026-09-05 assessment. The strongest change is that the principal Version 1 civic-decision slice — **ethiKos → EkoH → Smart Vote** — is now not only implemented but repeatedly qualified across production frontend build, browser workflows, backend contracts, database schema, real runtime APIs, Celery registration, and delivery-path automation. The frontend production build is green again after correcting the remaining TypeScript iterator/nullability issues. The current build compiles successfully, passes type validation, collects page data, and generates **115/115 static pages**. The four EkoH standalone surfaces modified to remove fabricated/global-weight semantics now pass targeted browser smoke **4/4**. Smart Vote has reached a substantially stronger contract state: - migration `0005_reconcile_vote_schema` is applied; - the live `ekoh_smartvote` schema matches the intended canonical structure; - `vote.modality_id` is a real FK to canonical `vote_modality` rows; - `weighted_value` remains nullable and is not treated as source truth; - five canonical modalities are present; - current vote rows are zero, so the reconciliation introduced no legacy-row conversion risk; - the real reading endpoint returns HTTP 200 for a bound ethiKos topic; - the reading exposes `reading_key`, `method`, `version`, `lens_hash`, and `snapshot_ref`; - the targeted reading/schema suite passes **5/5**. The release-acceptance golden workflow is already green and proves the intended ownership boundary: ethiKos owns source deliberation state, EkoH supplies contextual expertise/disclosure information, and Smart Vote publishes a separate declared advisory reading without mutating the public baseline. The main release risk has therefore shifted away from the core application and toward **deployment qualification and host security**. The most important remaining gate is now execution of the Linux/VPS security diagnostics on a fresh production target, followed by secret rotation, deployment validation, and a backup/restore drill. ## Current maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 93–96% | | Backend implementation | 94–96% | | Frontend implementation | 92–95% | | ethiKos | 97–98% | | EkoH | 96–98% | | Smart Vote | 97–98% | | TeamBuilder | 82–87% | | KonnectED | 78–84% | | Kontrol | 74–80% | | keenKonnect | 72–78% | | Kreative | 68–75% | | Automated testing | 92–95% | | End-to-end release workflow | 95–97% | | Application security configuration | 92–95% | | Local Docker/runtime hardening | 94–96% | | Deployed VPS security qualification | 55–65% | | Deployment / packaging | 84–88% | | CI / release qualification | 82–87% | | Backup / restore qualification | 50–60% | | Overall engineering maturity | ~92% | | Release Candidate readiness | ~86–90% | The lower deployed-security and backup/restore scores are evidence gaps rather than demonstrated application defects. ## Qualification evidence completed since 2026-09-05 ### 1. Bug Harvest depth substantially expanded The September 5/6 Bug Harvest campaigns intentionally stopped repeating already-green core suites and moved into previously under-qualified product surfaces. Important improvements include: - TeamBuilder Problem flows wired to real persistence; - KonnectED forum, mentorship, progress, recommendation and collaboration contracts exposed through canonical APIs; - keenKonnect team membership hardened with scoped membership/leave semantics; - Kreative artwork submission and collaboration-session flows moved to real persistence where backend contracts exist; - Kontrol surfaces stopped advertising fabricated administrative success where no write contract exists; - mock/fake-success patterns in the Wave 2 target set were converted either to real persistence or explicit deferred/read-only behavior; - navigation and Playwright harness noise was separated from real product defects. A key architectural rule was preserved throughout: **no backend domain model or ownership boundary was invented merely to make a UI test pass.** ### 2. Frontend production build restored to green The current Next.js 15.3.1 production build now: - compiles successfully; - passes TypeScript validity checks; - collects page data; - generates **115 / 115** static pages; - completes page optimization. The remaining `baseline-browser-mapping` and `caniuse-lite` messages are dependency freshness warnings and are not release-blocking application failures. This closes the prior production-build uncertainty caused by local `.next` locking and the later TypeScript regressions. ### 3. EkoH standalone surfaces corrected and requalified The modified EkoH pages no longer fabricate a universal Smart Vote voting weight or simulated expertise/history values. The following routes pass targeted Chromium smoke: - `/ekoh/achievements-badges/earned-badges-display` - `/ekoh/expertise-areas/view-current-expertise` - `/ekoh/overview-analytics/current-ekoh-score` - `/ekoh/voting-influence/current-voting-weight` Result: ```text 4 passed ``` The product semantics now remain consistent with the core rule that EkoH provides context while Smart Vote computes question/lens-specific advisory readings. ### 4. Smart Vote schema reconciliation closed The live `ekoh_smartvote` database reports migration: ```text [X] 0005_reconcile_vote_schema ``` Validated schema: ```text vote id user_id target_type target_id raw_value weighted_value NULL created_at modality_id NOT NULL vote_modality name parameters id PRIMARY KEY ``` Validated constraints include: - `vote_modality_id_fk`; - `vote_modality_pkey`; - unique modality name; - vote primary key; - vote uniqueness constraint. Canonical modality rows: ```text approval rating ranking preferential budget_split ``` Current rows: ```text vote = 0 vote_modality = 5 ``` No further migration action is required for `0005`. ### 5. Smart Vote real reading contract closed A real bound ethiKos topic returned: ```text HTTP 200 baseline participants = 3 readings = 1 reading_key = ekoh_weighted_v1 method = weighted_average version = v1 lens_hash = sha256:... snapshot_ref = ekoh_snapshot:... ``` The `method` and `version` metadata were added to the published reading contract and included in the lens identity. Targeted validation: ```text 5 passed ``` This closes the reproducibility metadata gap identified in the reading contract. ### 6. Smart Vote reporting no longer fabricates history The Smart Vote report path now uses real cross-sectional state. Where append-only historical vote events do not exist, historical daily vote series are explicitly reported as unavailable rather than synthesized. This preserves the distinction between: - current source facts; - derived Smart Vote readings; - historical evidence that does not actually exist. ### 7. Celery / scheduled task defects closed Previously observed runtime defects included: - a legacy Smart Vote aggregation path referencing a non-existent `vote` relation; - unregistered `contextual_analysis_batch` task messages. The Celery registration/schedule state was corrected. Current registered tasks include the expected EkoH and Smart Vote jobs, and the stale Beat entry was removed. No rerun is required unless the Celery task configuration changes. ### 8. Delivery golden workflow remains green The delivery workflow proves: ```text authentication → ethiKos deliberation → EkoH context → conflict / recusal → Smart Vote baseline + advisory reading → real stance write → real public vote → results / methodology / trust / impact / pulse ``` The workflow preserves the critical invariants: - ethiKos source stance remains canonical; - EkoH context is not authority; - Smart Vote reading is derived and separately identified; - recusal does not erase source participation; - no client-authored derived weight is stored as source truth. Expected Playwright delivery result: ```text 2 passed ``` ### 9. Local Docker/runtime hardening is green Validated local runtime posture: - Django bound to localhost; - Flower bound to localhost and unauthenticated requests rejected; - Mailpit bound to localhost; - Redis internal only; - Celery exposes no public port; - no Docker socket mount; - no host networking; - no privileged containers; - application log secret leakage corrected. Production Compose exposes only the intended Traefik public entrypoints. ### 10. Security diagnostics substantially complete locally SecurityDiag local checks established a strong application/configuration baseline. Validated areas include: - supply-chain / Capsule checks; - production Django security; - local Docker exposure; - secret-leak logging correction; - production service exposure configuration. The remaining security diagnostics are intentionally Linux/deployment-specific and cannot be closed from the Windows development host. ## Closed blockers from previous assessments The following items should no longer be carried forward as active blockers: - backend zero-failure qualification for the targeted release slice; - frontend TypeScript production-build regression; - EkoH standalone mock/global-weight presentation; - Smart Vote `0005` migration uncertainty; - Smart Vote reading `method/version` metadata; - Smart Vote fabricated historical report series; - Celery unregistered EkoH task; - stale Smart Vote aggregation schedule; - public Flower exposure in production Compose; - local Django database-configuration secret logging; - core ethiKos/EkoH/Smart Vote delivery workflow evidence. ## Remaining blockers before production promotion ### 1. Fresh VPS / Linux security qualification — BLOCKING This is now the most important gate. The prior security incident means the old compromised server must not become the trusted production base. Required target posture: ```text public: 80/tcp 443/tcp restricted: SSH not public: 3000 5555 5432 6379 8000 Docker TCP 2375/2376 ``` The fresh host must also validate: - SSH keys only; - root login disabled; - password / keyboard-interactive login disabled; - firewall enabled; - Fail2Ban active; - unattended security upgrades active; - no suspicious cron/systemd persistence; - no known incident IOCs; - Docker daemon not remotely exposed; - deployment user privilege kept minimal. ### 2. Secret rotation before production — BLOCKING The known credentials from the development/recovery period must be rotated before final delivery. This includes production-relevant: - SSH/deploy credentials; - Django secret; - database credentials; - Neon credentials; - admin/staff passwords; - provider/API tokens; - Git/deployment credentials. This work is intentionally deferred until the production delivery stage and should not be performed merely to make local tests pass. ### 3. Backup → isolated restore → validation drill — BLOCKING FOR FINAL RELEASE Backup tooling exists, but final evidence still needs: ```text backup → isolated restore → migrations/checks → application validation → evidence that DB/media recovery works ``` Do not use an old compromised full-disk image as a restore source. ### 4. Clean-target deployment reproducibility — BLOCKING FOR FINAL RELEASE A clean production target should prove: ```text clean source/release artifact → external production env → Docker build/start → migrations → HTTPS routing → application health → golden acceptance path ``` The result should be reproducible without depending on state inherited from the old VPS. ### 5. Version / release marker — READY The codebase is mature enough for a versioned prerelease checkpoint. Recommended marker: ```text v0.8.0-rc.1 ``` Interpretation: > First Release Candidate checkpoint for the qualified ethiKos/EkoH/Smart Vote delivery slice and the current platform-hardening baseline. Production promotion remains conditional on the VPS/security, secret-rotation, clean-deploy and restore gates. If this tag has not yet been created, it is the recommended next Git/GitHub marker. ### 6. Version 1 scope freeze / explicit deferrals — REQUIRED Secondary product surfaces should not delay the civic-decision release indefinitely. For Version 1, each incomplete surface should be explicitly classified as one of: ```text IN_SCOPE_AND_COMPLETE IN_SCOPE_READ_ONLY EXPLICIT_PREVIEW DEFERRED_POST_V1 ``` This is preferable to adding placeholder routes or fabricated persistence. ### 7. OpenAPI cleanup — NON-BLOCKING HARDENING drf-spectacular warnings remain technical-contract debt. They should be reduced before declaring the entire API surface polished/stable, but they are not currently evidence of a runtime failure in the qualified release slice. ## Release interpretation Konnaxion has crossed another material threshold. The core ethiKos/EkoH/Smart Vote application path is no longer the primary release risk. That slice now has: - real persistence; - canonical ownership boundaries; - green backend contract tests; - green production frontend build; - targeted browser smoke; - a green golden delivery workflow; - real Smart Vote reading identity and reproducibility metadata; - reconciled database schema; - local runtime hardening; - production application-security configuration. The dominant remaining risk is operational: > **Can the qualified application be deployed onto a clean, hardened, recoverable production host without reintroducing the conditions that enabled the previous compromise?** Until that is proven, the project should not be promoted to a final production release. ## Recommended current public status **Advanced Functional Beta — Final Release Candidate Qualification** Suggested short description: > Konnaxion is in final Release Candidate qualification. The core ethiKos, EkoH and Smart Vote civic-decision workflow is strongly validated across backend contracts, production frontend build, real browser workflows, database schema, derived-reading semantics and delivery automation. Secondary surfaces have undergone targeted Bug Harvest hardening, with unsupported functionality explicitly deferred rather than simulated. Remaining release risk is concentrated in fresh-VPS security qualification, secret rotation, reproducible clean deployment and backup/restore validation. ## Recommended next sequence ```text 1. Create/push v0.8.0-rc.1 prerelease checkpoint 2. Provision fresh VPS 3. Lock SSH + firewall before public exposure 4. Deploy clean release artifact 5. Rotate production credentials 6. Run Linux/VPS SecurityDiag gates 7. Validate only through 80/443 8. Run production golden acceptance workflow 9. Execute backup + isolated restore drill 10. Promote the validated artifact to the final production version ``` ## Bottom line ```text Core application: GREEN Frontend production build: GREEN ethiKos/EkoH/Smart Vote: GREEN Smart Vote schema/runtime: GREEN Golden delivery workflow: GREEN Local security/runtime: GREEN Secondary-surface harvest: STRONGLY IMPROVED / PARTLY DEFERRED Fresh VPS security: NOT YET QUALIFIED Backup/restore drill: NOT YET QUALIFIED Production promotion: BLOCKED ON OPERATIONS ``` **Engineering maturity:** ~92% **Release Candidate readiness:** ~86–90% **Recommended checkpoint:** `v0.8.0-rc.1` **Final production release:** not yet ================================================================================================ FILE: docs/status/2026-09-06-technical-status-report-wave2-closed.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 8fc597b65f67dc9c759a8901527e264c7c7c4769676bc489ba4eacd7943ab79b CONTENT_BYTES: 22414 ================================================================================================ # Konnaxion Technical Status Report **Assessment date:** 2026-09-06 **Previous assessment:** 2026-09-06 (pre-Wave-2 closure checkpoint) **Current status:** Advanced Functional Beta — Final Release Candidate Qualification **Estimated engineering maturity:** ~93% **Estimated Release Candidate readiness:** ~88–91% **Recommended version checkpoint:** `v0.8.0-rc.1` (GitHub prerelease) **Version lineage:** public historical release `v0.1.0-demo-stable`; latest documented beta marker `v0.8.0-beta.1`; previously recommended next beta `v0.8.0-beta.2`. **Production status:** Not yet approved for public production deployment **Checkpoint focus:** Wave 1 + Wave 2 secondary-surface qualification closed > This is an engineering status checkpoint based on validated local/runtime evidence, targeted bug-harvest evidence, the delivery workflow, and security diagnostics. Percentages are engineering estimates, not mathematical completion metrics. ## Executive summary Konnaxion has advanced materially since the 2026-09-05 assessment. The strongest change is that the principal Version 1 civic-decision slice — **ethiKos → EkoH → Smart Vote** — is now not only implemented but repeatedly qualified across production frontend build, browser workflows, backend contracts, database schema, real runtime APIs, Celery registration, and delivery-path automation. The frontend production build is green again after correcting the remaining TypeScript iterator/nullability issues. The current build compiles successfully, passes type validation, collects page data, and generates **115/115 static pages**. The secondary-surface qualification campaign has now crossed a second important threshold. **Wave 1 (TeamBuilder + KonnectED) is closed green**, and **Wave 2 (keenKonnect + Kreative + Kontrol) is also closed green** after splitting the long Playwright campaign into isolated browser contexts. Wave 2 final evidence is materially stronger than the previous checkpoint: - the full targeted campaign completes **6/6**; - all Wave 2 prewarm routes return HTTP 200; - keenKonnect, Kreative and Kontrol each pass their own isolated runtime/API block; - the source-gap audit reports **`blocking=0`** with unsupported surfaces explicitly classified as preview/read-only/deferred; - keenKonnect project creation is proven with real `POST 201` persistence and `DELETE 204` cleanup; - Kreative artwork creation is proven with real `POST 201` persistence and `DELETE 204` cleanup; - Kreative collaboration-session creation is proven with real `POST 201` persistence and `DELETE 204` cleanup; - the prior Playwright `Page crashed` failure disappeared once the modules were isolated into fresh contexts, confirming a harness/resource-orchestration issue rather than a demonstrated product/API defect. This closes the main local qualification uncertainty for the Wave 1/2 target set. Remaining local breadth work is now concentrated in the next secondary/transversal surfaces rather than the already-hardened TeamBuilder, KonnectED, keenKonnect, Kreative and Kontrol paths. The four EkoH standalone surfaces modified to remove fabricated/global-weight semantics now pass targeted browser smoke **4/4**. Smart Vote has reached a substantially stronger contract state: - migration `0005_reconcile_vote_schema` is applied; - the live `ekoh_smartvote` schema matches the intended canonical structure; - `vote.modality_id` is a real FK to canonical `vote_modality` rows; - `weighted_value` remains nullable and is not treated as source truth; - five canonical modalities are present; - current vote rows are zero, so the reconciliation introduced no legacy-row conversion risk; - the real reading endpoint returns HTTP 200 for a bound ethiKos topic; - the reading exposes `reading_key`, `method`, `version`, `lens_hash`, and `snapshot_ref`; - the targeted reading/schema suite passes **5/5**. The release-acceptance golden workflow is already green and proves the intended ownership boundary: ethiKos owns source deliberation state, EkoH supplies contextual expertise/disclosure information, and Smart Vote publishes a separate declared advisory reading without mutating the public baseline. The main release risk has therefore shifted away from the core application and toward **deployment qualification and host security**. The most important remaining gate is now execution of the Linux/VPS security diagnostics on a fresh production target, followed by secret rotation, deployment validation, and a backup/restore drill. ## Current maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 93–96% | | Backend implementation | 94–96% | | Frontend implementation | 92–95% | | ethiKos | 97–98% | | EkoH | 96–98% | | Smart Vote | 97–98% | | TeamBuilder | 86–90% | | KonnectED | 84–88% | | Kontrol | 82–86% | | keenKonnect | 80–85% | | Kreative | 78–84% | | Automated testing | 94–96% | | End-to-end release workflow | 96–98% | | Application security configuration | 92–95% | | Local Docker/runtime hardening | 94–96% | | Deployed VPS security qualification | 55–65% | | Deployment / packaging | 84–88% | | CI / release qualification | 84–89% | | Backup / restore qualification | 50–60% | | Overall engineering maturity | ~93% | | Release Candidate readiness | ~88–91% | The lower deployed-security and backup/restore scores are evidence gaps rather than demonstrated application defects. ## Qualification evidence completed since 2026-09-05 ### 1. Bug Harvest Wave 1 and Wave 2 qualification closed The September 5/6 Bug Harvest campaigns intentionally stopped repeating already-green core suites and moved into previously under-qualified product surfaces. #### Wave 1 — TeamBuilder + KonnectED Wave 1 is closed green. Validated outcomes include: - TeamBuilder Problem flows use real persistence rather than local-only success; - KonnectED forum topic/post/reply paths persist through canonical APIs; - mentorship, progress, recommendation and collaboration contracts are exposed through real backend endpoints; - duplicate route-key and stale harness issues were removed; - the final targeted TeamBuilder + KonnectED workflow passes without consolidated product findings. #### Wave 2 — keenKonnect + Kreative + Kontrol Wave 2 is now closed green after a broad source/runtime campaign. Final campaign result: ```text 6 passed frontend-wave2 exit=0 source blocking=0 declared-deferred=108 ``` The runtime qualification is intentionally split into independent Playwright contexts: ```text AUTH → PREWARM → keenKonnect runtime/API → Kreative runtime/API → Kontrol runtime/API → source-gap audit ``` This isolation eliminated the previous renderer contamination problem where one long-running page/context crash caused later modules to fail without independent evidence. Validated real mutations include: ```text keenKonnect project POST 201 → UI/read validation → DELETE 204 Kreative artwork POST 201 → persisted listing/read validation → DELETE 204 Kreative collaboration session POST 201 → persisted listing/read validation → DELETE 204 ``` Kontrol runtime/API reads are green, while unsupported administrative writes remain explicitly read-only rather than showing fabricated success. The Wave 2 source audit reports **zero blocking fake-success/missing-wiring findings**. Unsupported capabilities are explicitly declared as preview/read-only/deferred instead of being backed by invented contracts. Examples include: - AI matching save/join behavior where no matching-membership contract exists; - general knowledge-document persistence where no dedicated repository contract exists; - KeenKonnect workspace persistence/membership where no backend contract exists; - sustainability-impact report submission where no native write contract exists; - Kreative idea-incubator/showcase review surfaces without dedicated persistence contracts; - Kontrol role/user/community moderation writes where the current APIs are read-only. A key architectural rule was preserved throughout: **no backend domain model, API ownership boundary, or fake persistence path was invented merely to make a UI test pass.** The prior Playwright `Page crashed` result is now classified as **platform-readiness / harness resource orchestration**, not a confirmed product defect, because: - prewarm and backend APIs were healthy; - the crash contaminated later blocks only in the long shared context; - isolated contexts made keenKonnect, Kreative and Kontrol all pass in the same campaign. Remaining dependency/runtime warnings such as `React.Fragment + autoFocus` compatibility messages and Node `util._extend` deprecation are tracked as non-blocking technical debt, not product failures. ### 2. Frontend production build restored to green The current Next.js 15.3.1 production build now: - compiles successfully; - passes TypeScript validity checks; - collects page data; - generates **115 / 115** static pages; - completes page optimization. The remaining `baseline-browser-mapping` and `caniuse-lite` messages are dependency freshness warnings and are not release-blocking application failures. This closes the prior production-build uncertainty caused by local `.next` locking and the later TypeScript regressions. ### 3. EkoH standalone surfaces corrected and requalified The modified EkoH pages no longer fabricate a universal Smart Vote voting weight or simulated expertise/history values. The following routes pass targeted Chromium smoke: - `/ekoh/achievements-badges/earned-badges-display` - `/ekoh/expertise-areas/view-current-expertise` - `/ekoh/overview-analytics/current-ekoh-score` - `/ekoh/voting-influence/current-voting-weight` Result: ```text 4 passed ``` The product semantics now remain consistent with the core rule that EkoH provides context while Smart Vote computes question/lens-specific advisory readings. ### 4. Smart Vote schema reconciliation closed The live `ekoh_smartvote` database reports migration: ```text [X] 0005_reconcile_vote_schema ``` Validated schema: ```text vote id user_id target_type target_id raw_value weighted_value NULL created_at modality_id NOT NULL vote_modality name parameters id PRIMARY KEY ``` Validated constraints include: - `vote_modality_id_fk`; - `vote_modality_pkey`; - unique modality name; - vote primary key; - vote uniqueness constraint. Canonical modality rows: ```text approval rating ranking preferential budget_split ``` Current rows: ```text vote = 0 vote_modality = 5 ``` No further migration action is required for `0005`. ### 5. Smart Vote real reading contract closed A real bound ethiKos topic returned: ```text HTTP 200 baseline participants = 3 readings = 1 reading_key = ekoh_weighted_v1 method = weighted_average version = v1 lens_hash = sha256:... snapshot_ref = ekoh_snapshot:... ``` The `method` and `version` metadata were added to the published reading contract and included in the lens identity. Targeted validation: ```text 5 passed ``` This closes the reproducibility metadata gap identified in the reading contract. ### 6. Smart Vote reporting no longer fabricates history The Smart Vote report path now uses real cross-sectional state. Where append-only historical vote events do not exist, historical daily vote series are explicitly reported as unavailable rather than synthesized. This preserves the distinction between: - current source facts; - derived Smart Vote readings; - historical evidence that does not actually exist. ### 7. Celery / scheduled task defects closed Previously observed runtime defects included: - a legacy Smart Vote aggregation path referencing a non-existent `vote` relation; - unregistered `contextual_analysis_batch` task messages. The Celery registration/schedule state was corrected. Current registered tasks include the expected EkoH and Smart Vote jobs, and the stale Beat entry was removed. No rerun is required unless the Celery task configuration changes. ### 8. Delivery golden workflow remains green The delivery workflow proves: ```text authentication → ethiKos deliberation → EkoH context → conflict / recusal → Smart Vote baseline + advisory reading → real stance write → real public vote → results / methodology / trust / impact / pulse ``` The workflow preserves the critical invariants: - ethiKos source stance remains canonical; - EkoH context is not authority; - Smart Vote reading is derived and separately identified; - recusal does not erase source participation; - no client-authored derived weight is stored as source truth. Expected Playwright delivery result: ```text 2 passed ``` ### 9. Local Docker/runtime hardening is green Validated local runtime posture: - Django bound to localhost; - Flower bound to localhost and unauthenticated requests rejected; - Mailpit bound to localhost; - Redis internal only; - Celery exposes no public port; - no Docker socket mount; - no host networking; - no privileged containers; - application log secret leakage corrected. Production Compose exposes only the intended Traefik public entrypoints. ### 10. Security diagnostics substantially complete locally SecurityDiag local checks established a strong application/configuration baseline. Validated areas include: - supply-chain / Capsule checks; - production Django security; - local Docker exposure; - secret-leak logging correction; - production service exposure configuration. The remaining security diagnostics are intentionally Linux/deployment-specific and cannot be closed from the Windows development host. ## Closed blockers from previous assessments The following items should no longer be carried forward as active blockers: - backend zero-failure qualification for the targeted release slice; - frontend TypeScript production-build regression; - EkoH standalone mock/global-weight presentation; - Smart Vote `0005` migration uncertainty; - Smart Vote reading `method/version` metadata; - Smart Vote fabricated historical report series; - Celery unregistered EkoH task; - stale Smart Vote aggregation schedule; - public Flower exposure in production Compose; - local Django database-configuration secret logging; - core ethiKos/EkoH/Smart Vote delivery workflow evidence; - TeamBuilder + KonnectED Wave 1 targeted qualification; - keenKonnect + Kreative + Kontrol Wave 2 targeted qualification; - Wave 2 fake-success / missing-wiring blockers in the audited target set; - Playwright long-context renderer contamination that previously produced `Page crashed`. ## Remaining blockers before production promotion ### 1. Fresh VPS / Linux security qualification — BLOCKING This is now the most important gate. The prior security incident means the old compromised server must not become the trusted production base. Required target posture: ```text public: 80/tcp 443/tcp restricted: SSH not public: 3000 5555 5432 6379 8000 Docker TCP 2375/2376 ``` The fresh host must also validate: - SSH keys only; - root login disabled; - password / keyboard-interactive login disabled; - firewall enabled; - Fail2Ban active; - unattended security upgrades active; - no suspicious cron/systemd persistence; - no known incident IOCs; - Docker daemon not remotely exposed; - deployment user privilege kept minimal. ### 2. Secret rotation before production — BLOCKING The known credentials from the development/recovery period must be rotated before final delivery. This includes production-relevant: - SSH/deploy credentials; - Django secret; - database credentials; - Neon credentials; - admin/staff passwords; - provider/API tokens; - Git/deployment credentials. This work is intentionally deferred until the production delivery stage and should not be performed merely to make local tests pass. ### 3. Backup → isolated restore → validation drill — BLOCKING FOR FINAL RELEASE Backup tooling exists, but final evidence still needs: ```text backup → isolated restore → migrations/checks → application validation → evidence that DB/media recovery works ``` Do not use an old compromised full-disk image as a restore source. ### 4. Clean-target deployment reproducibility — BLOCKING FOR FINAL RELEASE A clean production target should prove: ```text clean source/release artifact → external production env → Docker build/start → migrations → HTTPS routing → application health → golden acceptance path ``` The result should be reproducible without depending on state inherited from the old VPS. ### 5. Version / release marker — READY The codebase is mature enough for a versioned prerelease checkpoint. Recommended marker: ```text v0.8.0-rc.1 ``` Interpretation: > First Release Candidate checkpoint for the qualified ethiKos/EkoH/Smart Vote delivery slice and the current platform-hardening baseline. Production promotion remains conditional on the VPS/security, secret-rotation, clean-deploy and restore gates. If this tag has not yet been created, it is the recommended next Git/GitHub marker. ### 6. Version 1 scope freeze / explicit deferrals — REQUIRED Secondary product surfaces should not delay the civic-decision release indefinitely. For Version 1, each incomplete surface should be explicitly classified as one of: ```text IN_SCOPE_AND_COMPLETE IN_SCOPE_READ_ONLY EXPLICIT_PREVIEW DEFERRED_POST_V1 ``` This is preferable to adding placeholder routes or fabricated persistence. ### 7. Remaining secondary/transversal breadth qualification — NON-BLOCKING FOR THE QUALIFIED CIVIC SLICE Wave 1 and Wave 2 are closed, but platform-wide qualification is not yet exhaustive. The next local campaign should focus on the remaining under-qualified/transversal areas, especially: ```text Konsensus Reports Search cross-surface navigation / shared contracts ``` These should be handled with the same rule used in Wave 2: ```text real backend contract exists → prove real behavior backend contract does not exist → explicit read-only / preview / deferred classification never invent persistence solely to satisfy a test ``` This work improves platform breadth and Version 1 scope confidence. It does not supersede the operational production blockers below, and it should not force unsupported secondary features into Version 1. ### 8. OpenAPI cleanup — NON-BLOCKING HARDENING drf-spectacular warnings remain technical-contract debt. They should be reduced before declaring the entire API surface polished/stable, but they are not currently evidence of a runtime failure in the qualified release slice. ## Release interpretation Konnaxion has crossed another material threshold. The core ethiKos/EkoH/Smart Vote application path is no longer the primary release risk. That slice now has: - real persistence; - canonical ownership boundaries; - green backend contract tests; - green production frontend build; - targeted browser smoke; - a green golden delivery workflow; - real Smart Vote reading identity and reproducibility metadata; - reconciled database schema; - local runtime hardening; - production application-security configuration. The surrounding platform now has materially stronger breadth evidence as well: - TeamBuilder + KonnectED Wave 1 closed green; - keenKonnect + Kreative + Kontrol Wave 2 closed green; - real secondary-surface writes proven where backend contracts exist; - unsupported writes explicitly disabled/read-only rather than simulated; - Wave 2 source audit at `blocking=0`; - Playwright runtime isolation hardened so one renderer failure cannot invalidate later module evidence. The dominant remaining risk is operational: > **Can the qualified application be deployed onto a clean, hardened, recoverable production host without reintroducing the conditions that enabled the previous compromise?** Until that is proven, the project should not be promoted to a final production release. ## Recommended current public status **Advanced Functional Beta — Final Release Candidate Qualification** Suggested short description: > Konnaxion is in final Release Candidate qualification. The core ethiKos, EkoH and Smart Vote civic-decision workflow is strongly validated across backend contracts, production frontend build, real browser workflows, database schema, derived-reading semantics and delivery automation. TeamBuilder, KonnectED, keenKonnect, Kreative and Kontrol have now completed targeted secondary-surface Bug Harvest qualification, including real persistence proofs where contracts exist and explicit read-only/deferred behavior where they do not. Remaining release risk is concentrated in fresh-VPS security qualification, secret rotation, reproducible clean deployment, backup/restore validation and final platform-breadth/scope closure. ## Recommended next sequence ```text 1. Freeze the current Wave 1/2 qualification evidence 2. Run the next local breadth campaign on Konsensus + Reports + Search/transversal surfaces 3. Finalize Version 1 scope classifications / explicit deferrals 4. Create/push v0.8.0-rc.1 prerelease checkpoint 5. Provision fresh VPS 6. Lock SSH + firewall before public exposure 7. Deploy clean release artifact 8. Rotate production credentials 9. Run Linux/VPS SecurityDiag gates 10. Validate only through 80/443 11. Run production golden acceptance workflow 12. Execute backup + isolated restore drill 13. Promote the validated artifact to the final production version ``` ## Bottom line ```text Core application: GREEN Frontend production build: GREEN ethiKos/EkoH/Smart Vote: GREEN Smart Vote schema/runtime: GREEN Golden delivery workflow: GREEN Local security/runtime: GREEN Wave 1 TeamBuilder/KonnectED: GREEN Wave 2 keenKonnect/Kreative/ Kontrol targeted qualification: GREEN Wave 2 source blockers: 0 Explicit unsupported surfaces: DECLARED READ-ONLY / PREVIEW / DEFERRED Harvest context isolation: GREEN Remaining local breadth: KONSENSUS / REPORTS / SEARCH / TRANSVERSAL Fresh VPS security: NOT YET QUALIFIED Backup/restore drill: NOT YET QUALIFIED Production promotion: BLOCKED ON OPERATIONS ``` **Engineering maturity:** ~93% **Release Candidate readiness:** ~88–91% **Recommended checkpoint:** `v0.8.0-rc.1` **Final production release:** not yet ================================================================================================ FILE: docs/status/2026-09-08-technical-maturity-assessment.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 5b5da75e2fad5c1775cd2e969c1ae252dd43625185a2d6a9fd5fb9ceffebfe29 CONTENT_BYTES: 15716 ================================================================================================ # Konnaxion Technical Maturity Assessment **Assessment date:** 2026-09-08 **Previous assessment:** 2026-09-06 — Wave 2 closed checkpoint **Current status:** Advanced Functional Beta — Final Release Candidate Qualification / Security Gate Hardening **Estimated engineering maturity:** ~94% **Estimated Release Candidate readiness:** ~89–92% **Recommended version checkpoint:** `v0.8.0-rc.1` (GitHub prerelease) **Production status:** Not yet approved for public production deployment **Checkpoint focus:** SecurityDiag hardening, repository security qualification, generated-artifact hygiene, and release-gate integrity > This assessment is a technical maturity checkpoint. Percentages are engineering estimates based on validated implementation and qualification evidence, not mathematical completion metrics. This document does not declare Konnaxion production-ready. ## Executive summary Konnaxion remains in **final Release Candidate qualification**, with another measurable improvement in local release-security assurance since the 2026-09-06 Wave 2 closure checkpoint. The principal product and qualification baseline from September 6 remains intact: - the core ethiKos → EkoH → Smart Vote release slice is strongly qualified; - the production frontend build is green; - Smart Vote schema and reading-contract reconciliation are closed; - the golden delivery workflow is green; - TeamBuilder + KonnectED Wave 1 is closed green; - keenKonnect + Kreative + Kontrol Wave 2 is closed green; - unsupported secondary writes remain explicit read-only / preview / deferred surfaces rather than fabricated persistence. The September 8 work did not materially expand product breadth. Instead, it improved the **integrity of the release-security tooling itself** and tightened repository hygiene. SecurityDiag was reviewed and hardened so that release evidence is more reliably fail-closed. The resulting repository campaign now reports: ```text S00 PASS Diagnostic Integrity S01 PASS Target & Security Context S02 WARN Repository Secrets & Artifact Hygiene S03 PASS Supply Chain, Capsule Integrity & Automation S04 PASS Application Production Security ``` The remaining S02 warnings are limited to machine-local `.env` / `.envs` secret material that is **not tracked by Git and is covered by ignore rules**. No tracked archive remains in the repository index, generated `.securitydiag/` evidence has been removed from tracking, and the previous scan-coverage false partial condition has been corrected. This increases confidence in the local release qualification path, but it does **not** close the operational production gates already identified on September 6. The dominant remaining risk is still: > **Can the qualified application be deployed onto a clean, hardened, recoverable production host without reintroducing the conditions that enabled the previous compromise?** Until that is proven, final production promotion remains blocked. ## Maturity by area | Area | Estimated maturity | |---|---:| | Product architecture | 94–96% | | Backend implementation | 94–96% | | Frontend implementation | 92–95% | | ethiKos | 97–98% | | EkoH | 96–98% | | Smart Vote | 97–98% | | TeamBuilder | 86–90% | | KonnectED | 84–88% | | Kontrol | 82–86% | | keenKonnect | 80–85% | | Kreative | 78–84% | | Automated testing | 94–96% | | End-to-end release workflow | 96–98% | | Application security configuration | 94–96% | | Repository / release-security qualification | 94–97% | | Local Docker/runtime hardening | 94–96% | | Deployed VPS security qualification | 55–65% | | Deployment / packaging | 84–88% | | CI / release qualification | 86–90% | | Backup / restore qualification | 50–60% | | Overall engineering maturity | ~94% | | Release Candidate readiness | ~89–92% | The small increase from the previous ~93% / ~88–91% checkpoint reflects stronger local security-gate integrity and cleaner release evidence. The lower deployed-security and backup/restore scores remain evidence gaps rather than demonstrated application defects. ## Qualification evidence added since 2026-09-06 ### 1. SecurityDiag release-gate integrity hardened The SecurityDiag review identified several cases where the diagnostic tool could produce evidence that was weaker than its documented fail-closed contract. The hardening work addressed the following classes of issues: - privileged remote probe values are no longer left as raw shell interpolations; - Capsule Security Gate evaluation rejects incomplete required evidence; - required `SKIPPED` checks do not satisfy SecurityDiag release qualification; - empty or incomplete Security Gate result sets cannot be treated as release-acceptable; - S14 release qualification checks expected campaign completeness instead of only evaluating result files that happen to exist; - strict Docker allowlist mode no longer silently passes with an empty allowlist; - declared supply-chain audits are constrained to the intended audit use case instead of being an unrestricted configured command surface; - secret-scan coverage now distinguishes binary files, oversized text candidates, read errors, and scan-bound exhaustion; - structured configuration output is defensively redacted before persistence. This work improves the diagnostic trust boundary rather than application feature breadth. ### 2. SecurityDiag scanner false-partial condition closed The previous S02 scan-coverage logic could classify large expected binary artifacts as incomplete secret-scan coverage and force a `PARTIAL` result. The scanner now samples content before treating oversized files as text evidence gaps. Validated effect: - large binary assets do not create false incomplete-coverage blockers; - oversized plausible text remains visible; - tracked incomplete text coverage remains capable of blocking; - untracked oversized text remains visible as warning evidence. After cleanup of the generated TypeScript build-info artifact, the repository campaign no longer reports a coverage warning. ### 3. Repository SecurityDiag campaign is non-blocking Current repository qualification: ```text SecurityDiag repo - WARN S00 PASS S01 PASS S02 WARN S03 PASS S04 PASS ``` The S02 WARN is intentional and evidence-based. Observed local sensitive files include: ```text backend/.env backend/.envs/.local/.postgres backend/.envs/.production/.django backend/.envs/.production/.postgres ``` Validation established that: - these files are not tracked by Git; - `.env` and `.envs/` are covered by backend ignore rules; - no tracked secret-pattern finding was reported; - no tracked oversized scan candidate remains. The correct interpretation is therefore **local secret awareness**, not a repository leak. ### 4. Generated diagnostics removed from Git tracking Historical `.securitydiag/` result files had previously been tracked in the repository. They have now been removed from the Git index while remaining available locally when generated. This aligns repository state with the existing ignore policy: ```text .securitydiag/ ``` Security diagnostics remain runtime/release evidence rather than source-controlled application artifacts. ### 5. Archived/generated artifacts removed from Git tracking Previously tracked ZIP artifacts and diagnostic/deployment archives were removed from the Git index. A subsequent tracked-archive query returned no remaining: ```text *.zip *.tar.gz *.tgz ``` This reduces accidental release contamination and prevents stale generated evidence from being treated as product source. ### 6. TypeScript generated build metadata confirmed ignored `frontend/tsconfig.tsbuildinfo` was the final oversized untracked text artifact affecting scan-coverage warning output. It is generated build metadata and is already covered by: ```text *.tsbuildinfo ``` The file was removed locally and is not part of the tracked release source. ## Qualification baseline carried forward The following previously validated evidence remains part of the current baseline unless invalidated by later code changes. ### Core application and delivery - ethiKos / EkoH / Smart Vote ownership boundaries are explicit and qualified; - the public baseline remains distinct from Smart Vote advisory readings; - the golden delivery workflow proves real authentication and canonical ethiKos writes; - Smart Vote exposes declared reading identity and reproducibility metadata; - frontend production build generates 115 / 115 static pages; - backend contract and targeted schema tests are green. ### Secondary-surface qualification Wave 1 remains closed green: ```text TeamBuilder KonnectED ``` Wave 2 remains closed green: ```text keenKonnect Kreative Kontrol ``` The Wave 2 source-gap audit previously reached: ```text blocking=0 ``` Unsupported product capabilities remain explicitly classified as read-only, preview, or deferred rather than being backed by invented contracts. ### Local application/runtime security Previously validated application-security controls remain part of the baseline: - production `DEBUG=False`; - production hosts configured; - HTTPS redirect enabled; - secure session/CSRF cookies; - HSTS enabled; - clickjacking/content-type protections enabled; - public Flower exposure removed; - local Docker/runtime hardening qualified; - production application configuration passes its targeted security checks. ## Remaining blockers before production promotion ### 1. Fresh VPS / Linux security qualification — BLOCKING This remains the most important production gate. A fresh Linux/VPS target must prove: ```text public: 80/tcp 443/tcp restricted: SSH not public: 3000 5555 5432 6379 8000 Docker TCP 2375/2376 ``` The target must also validate: - SSH keys only; - root login disabled; - password and keyboard-interactive login disabled; - firewall enabled; - Fail2Ban active; - unattended security upgrades active; - no suspicious cron/systemd persistence; - no known incident IOCs; - Docker daemon not remotely exposed; - minimal deployment-user privilege; - SecurityDiag Linux/VPS levels complete with usable evidence. ### 2. Secret rotation before production — BLOCKING Production-relevant credentials from the development/recovery period must be rotated before final delivery. This includes: - SSH/deploy credentials; - Django secret; - database credentials; - Neon credentials; - admin/staff passwords; - provider/API tokens; - Git/deployment credentials. Local `.env` files should remain machine-local and excluded from release artifacts. ### 3. Backup → isolated restore → validation drill — BLOCKING FOR FINAL RELEASE Required proof remains: ```text backup → isolated restore → migrations/checks → application validation → DB/media recovery evidence ``` An old compromised full-disk image must not be used as the trusted restore source. ### 4. Clean-target deployment reproducibility — BLOCKING FOR FINAL RELEASE A fresh target should prove: ```text clean source/release artifact → external production env → Docker build/start → migrations → HTTPS routing → application health → golden acceptance path ``` No inherited state from the old VPS should be required. ### 5. Version 1 scope freeze / explicit deferrals — REQUIRED Remaining incomplete surfaces should be classified explicitly as: ```text IN_SCOPE_AND_COMPLETE IN_SCOPE_READ_ONLY EXPLICIT_PREVIEW DEFERRED_POST_V1 ``` This is preferable to adding placeholder routes or fabricated persistence. ### 6. Remaining breadth qualification — NON-BLOCKING FOR THE QUALIFIED CIVIC SLICE The next local breadth work remains concentrated in: ```text Konsensus Reports Search cross-surface navigation / shared contracts ``` The same rule used during Wave 2 should remain mandatory: ```text real backend contract exists → prove real behavior backend contract does not exist → explicit read-only / preview / deferred classification ``` ### 7. OpenAPI cleanup — NON-BLOCKING HARDENING Remaining drf-spectacular warnings are technical-contract debt. They should be reduced before the complete API surface is described as polished/stable, but they do not currently invalidate the qualified release slice. ## Release interpretation Konnaxion has not materially changed product classification since September 6, but local release assurance is stronger. The codebase now has stronger evidence that: - generated diagnostics do not contaminate source control; - local secrets are visible to SecurityDiag without being treated as tracked release content; - repository artifacts are cleaner; - the SecurityDiag release gate is more fail-closed; - incomplete or skipped required security evidence is less likely to be misrepresented as green; - release qualification is better aligned with the documented security contract. The core application is therefore **not the dominant risk**. The dominant risk remains operational deployment qualification. ## Recommended current public status **Advanced Functional Beta — Final Release Candidate Qualification** Suggested short description: > Konnaxion is in final Release Candidate qualification. The core ethiKos, EkoH and Smart Vote civic-decision workflow is strongly validated across backend contracts, production frontend build, real browser workflows, database schema, Smart Vote reading semantics and delivery automation. TeamBuilder, KonnectED, keenKonnect, Kreative and Kontrol have completed targeted secondary-surface qualification, and the local release-security toolchain has now been hardened and requalified. Remaining release risk is concentrated in fresh-VPS security qualification, production secret rotation, reproducible clean deployment, backup/restore validation and final Version 1 scope closure. ## Recommended next sequence ```text 1. Commit the repository hygiene cleanup 2. Freeze the September 8 SecurityDiag repository evidence 3. Finalize Version 1 scope classifications / explicit deferrals 4. Create or confirm v0.8.0-rc.1 prerelease checkpoint 5. Provision fresh VPS 6. Lock SSH and firewall before public exposure 7. Deploy the clean release artifact 8. Rotate production credentials 9. Run the complete Linux/VPS SecurityDiag campaign 10. Validate public exposure only through 80/443 11. Run the production golden acceptance workflow 12. Execute backup + isolated restore drill 13. Promote only the validated artifact to final production ``` ## Bottom line ```text Core application: GREEN Frontend production build: GREEN ethiKos/EkoH/Smart Vote: GREEN Smart Vote schema/runtime: GREEN Golden delivery workflow: GREEN Wave 1 TeamBuilder/KonnectED: GREEN Wave 2 keenKonnect/Kreative/Kontrol: GREEN Local repository SecurityDiag: PASS/WARN (non-blocking) Tracked secret findings: 0 Tracked oversized scan gaps: 0 Tracked release/archive artifacts: 0 SecurityDiag release-gate hardening: COMPLETED Local security/runtime baseline: GREEN Remaining local breadth: KONSENSUS / REPORTS / SEARCH / TRANSVERSAL Fresh VPS security: NOT YET QUALIFIED Secret rotation: NOT YET COMPLETED Backup/restore drill: NOT YET QUALIFIED Clean production deployment: NOT YET QUALIFIED Production promotion: BLOCKED ON OPERATIONS ``` **Engineering maturity:** ~94% **Release Candidate readiness:** ~89–92% **Recommended checkpoint:** `v0.8.0-rc.1` **Final production release:** not yet ================================================================================================ FILE: docs/status/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 26aa7b6a22545f9ee17797ece94223e584ce887eb2774d66ed5630d1e20875a4 CONTENT_BYTES: 1659 ================================================================================================ # Konnaxion Status **Current status:** Advanced Functional Beta — Final Release Candidate Qualification / Security Gate Hardening **Engineering maturity:** ~94% **Release Candidate readiness:** ~89–92% **Assessment date:** 2026-09-08 Konnaxion's core ethiKos → EkoH → Smart Vote release slice remains strongly qualified, Wave 1 and Wave 2 secondary-surface campaigns are closed green, and the local SecurityDiag/repository qualification path has now been hardened and revalidated. The current repository SecurityDiag campaign is non-blocking: S00, S01, S03 and S04 pass; S02 remains WARN only for machine-local secret files that are not tracked by Git and are covered by ignore rules. Generated SecurityDiag evidence and tracked release/archive artifacts have been removed from the source index. Remaining work is concentrated in fresh-VPS/Linux security qualification, production secret rotation, clean-target deployment reproducibility, backup/restore validation, final Version 1 scope classification, and remaining transversal breadth qualification. This is not yet approved for final public production deployment. ## Current assessment [2026-09-08 Technical Maturity Assessment](./2026-09-08-technical-maturity-assessment.md) ## Previous assessments [2026-09-06 Technical Status Report — Wave 2 Closed](./2026-09-06-technical-status-report-wave2-closed.md) [2026-09-05 Technical Maturity Assessment](./2026-09-05-technical-maturity-assessment.md) [2026-08-28 Technical Maturity Assessment](./2026-08-28-technical-maturity-assessment.md) [2026-08-27 Technical Maturity Assessment](./2026-08-27-technical-maturity-assessment.md) ================================================================================================ FILE: docs/Technical-Reference/BOUNDARIES_AND_OWNERSHIP.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 16e1687c8efe23b88ca49c28e76b67fef97b85847b659e562d687f3dba956182 CONTENT_BYTES: 5750 ================================================================================================ # Konnaxion — Boundaries and Ownership ## 1. Konnaxion boundary Konnaxion owns its domain data and executes mutations through its own services/APIs. A foreign tool or ecosystem system may request work, provide an artifact, ask a query, or consume a result; it does not write Konnaxion internal tables directly. ## 2. Internal ownership ### ethiKos / Korum Owns the structured deliberation source state represented in the current code by objects including: - `EthikosTopic`; - `EthikosStance`; - `EthikosArgument`; - `EthikosCategory`; - `ArgumentSource`; - `ArgumentImpactVote`; - `ArgumentSuggestion`; - `DiscussionParticipantRole`; - `DiscussionVisibilitySetting`. Rules: - topic-level stance is distinct from argument-level impact/evaluation; - arguments and replies form deliberation state, not Smart Vote output; - moderation and visibility remain ethiKos-owned; - EkoH/Smart Vote may read declared inputs but do not mutate these records as part of a reading. ### Konsultations Logical owner of consultation/intake/formal decision source events where that product capability is used. Rules: - source ballots are recorded as source facts; - a Smart Vote lens may interpret them but does not replace them; - a consultation object is not automatically an Orgo Task; - decision protocol and workflow orchestration are different concepts. ### EkoH Canonical backend owner: `konnaxion.ekoh`. Owns: - `ExpertiseCategory` taxonomy; - `UserExpertiseScore`; - `UserEthicsScore`; - score configuration/history; - confidentiality; - rating visibility and scoped rating access; - contextual analysis records. Strong existing behavior to preserve: - contextual AI analysis is non-authoritative unless governed evidence actually updates score state; - rating disclosure is resolved through a dedicated deterministic access service; - expertise remains domain-bounded; - lack of expertise is not negative merit. ### Smart Vote Canonical backend owner: `konnaxion.smart_vote`. Owns: - `Consultation` as Smart Vote reading/ballot context; - `ConsultationRelevance`; - `SourceConsultationBinding`; - reading computation; - lens identity; - reading aggregation/presentation. For an ethiKos-bound reading, the current correct pattern is: ```text EthikosTopic / EthikosStance ↓ read only SourceConsultationBinding ↓ ConsultationRelevance + EkoH context ↓ Smart Vote reading ↓ baseline + declared advisory reading ``` The source stance remains owned by ethiKos. ### Kollective Intelligence `konnaxion.kollective_intelligence` is not a canonical data owner in the current architecture. New EkoH or Smart Vote functionality must not be added there. ### keenKonnect Owns project/collaboration state in its domain. External recommendations or EkoH displays do not transfer project ownership. ### KonnectED Owns learning/resources/certification/portfolio state in its domain. Offline packages in this domain are application content packages and must not be confused with Kristal Runtime Packs unless an explicit contract says otherwise. ### Kreative Owns creative works, galleries, collaboration sessions, traditions/archives and related domain state. ### TeamBuilder Owns its problem, builder-session, team and team-member state. It is a Konnaxion application/domain capability, not an Orgo Task engine. ### Kontrol Administrative application surface for Konnaxion moderation, roles/users, audit and platform-level views. Presentation in Kontrol does not move ownership of the underlying domain state. ## 3. Konnaxion ↔ Orgo There is no implemented Orgo integration in the current Konnaxion code snapshot. Therefore no current Konnaxion object is declared identical to an Orgo object. Required invariant for a future boundary: ```text Orgo Case ≠ Konnaxion Topic Orgo Task ≠ Konnaxion Consultation Orgo status ≠ civic decision status ``` When Orgo requests a Konnaxion operation: ```text Orgo intent → command/job/proposal → Konnaxion authentication + validation + domain rules → Konnaxion mutation → receipt/event/result → Orgo workflow reconciliation ``` When Konnaxion requires governed work in Orgo, it emits a request/event; it does not create or edit Orgo Case/Task rows directly. ## 4. Konnaxion ↔ Kristal No Kristal integration is implemented in the current Konnaxion code snapshot. If/when Konnaxion consumes a Kristal artifact: - Kristal owns artifact semantics, identity, epistemic metadata and integrity rules; - Konnaxion may present/query/transport only according to an explicit profile; - Konnaxion must not reinterpret assertion status, certainty, validation, authority recognition or Reader Policy; - Konnaxion does not acquire ownership of local kOA-Linux Runtime Pack activation merely because it can transport or display an artifact. ## 5. Konnaxion ↔ SemantiK Architect No SemantiK Architect integration is implemented in the current Konnaxion code snapshot. A future integration is a generation/presentation boundary: ```text Konnaxion structured input → Architect request → Architect NLG pipeline → surface output + trace/metadata ``` Architect does not write Konnaxion civic state. ## 6. Konnaxion ↔ kOA-Linux kOA-Linux may host/integrate Konnaxion as a subsystem from the kOA-Linux scope. Konnaxion keeps authority over Konnaxion domain behavior and data. Platform deployment, host privilege, resource governance and local runtime activation owned by kOA-Linux are not Konnaxion business capabilities. ## 7. K-Port K-Port is not a peer of Konnaxion. It is an EkoH evidence application/gateway. Evidence entering through K-Port becomes authoritative EkoH state only through EkoH's governed validation/update boundary. ================================================================================================ FILE: docs/Technical-Reference/CODE_ALIGNMENT_NOTES.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 58cc85463fce8c19b3f14b019b3e2b15e1625480efaa123a98943f735ab87dca CONTENT_BYTES: 7070 ================================================================================================ # Konnaxion — Code Alignment Notes ## Purpose This note identifies the code areas that should be changed so the implementation matches the current Konnaxion architecture. ## 1. Canonical EkoH taxonomy reference ### `backend/konnaxion/ethikos/models.py` `EthikosTopic.expertise_category` currently references: ```text kollective_intelligence.ExpertiseCategory ``` Canonical taxonomy is now: ```text ekoh.ExpertiseCategory ``` The relation and its data migration should be moved to the EkoH-owned taxonomy. New code should not introduce another expertise taxonomy. ## 2. Remove active canonical dependence on `kollective_intelligence` ### `backend/config/settings/base.py` `konnaxion.kollective_intelligence` is still installed as an active local app. ### `backend/config/api_router.py` The central router still exposes optional: ```text /api/kollective/votes/ /api/kollective/vote-results/ ``` ### `backend/konnaxion/kollective_intelligence/*` The package itself states that canonical EkoH and Smart Vote ownership has moved elsewhere. Active features should therefore resolve to `konnaxion.ekoh` and `konnaxion.smart_vote` rather than this compatibility package. Do not delete migrations blindly; the desired final runtime state is simply that this package no longer acts as a canonical service/API owner. ## 3. Konsensus frontend still uses the non-canonical vote API ### `frontend/modules/konsensus/hooks/usePoll.ts` Reads: ```text kollective/votes/ ``` ### `frontend/modules/konsensus/pages/PollPage.tsx` Posts to the same route and currently sends: ```text raw_value weighted_value ``` The client must not supply an authoritative `weighted_value`. Align this surface to the proper source-ballot contract and, when needed, request a Smart Vote reading separately. ## 4. Smart Vote stores derived weight on the ballot row ### `backend/konnaxion/smart_vote/serializers/ballot.py` `BallotSerializer.create()` computes `get_weight(...)` during cast and persists `raw_value * weight` into `Vote.weighted_value`. ### `backend/konnaxion/smart_vote/models/core.py` `Vote` contains `weighted_value`; `VoteResult` contains `sum_weighted_value`. ### `backend/konnaxion/smart_vote/tasks/aggregator.py` The aggregator sums persisted weighted values into `VoteResult`. These paths should be changed so that: ```text source ballot ≠ derived reading weight ≠ derived aggregate ``` If Smart Vote retains a native ballot store, store the source event independently and materialize a derived reading with explicit lens/version/snapshot metadata. ## 5. Preserve the good ethiKos reading path ### `backend/konnaxion/smart_vote/services/reading_service.py` This path is already strongly aligned: - reads `EthikosStance` without mutating it; - uses explicit `SourceConsultationBinding`; - keeps baseline separate; - hashes lens configuration; - hashes EkoH contextual inputs; - honors advisory-only exclusions without deleting source participation; - filters participant detail through EkoH rating access. Do not collapse this boundary into ballot-level `weighted_value` state. ## 6. Persist/recover snapshot inputs for durable published readings ### `backend/konnaxion/smart_vote/services/reading_service.py` The current endpoint computes `snapshot_ref` from an in-memory payload but no persisted snapshot artifact is evidenced in the inspected code. If readings are exposed as durable/published results, add a recoverable snapshot/materialized-reading boundary so the exact inputs behind `snapshot_ref` can be replayed. An on-demand current-state reading can remain ephemeral, but it should be described as such. ## 7. Validate consultation relevance vectors ### `backend/konnaxion/smart_vote/models/consultation_relevance.py` The model stores per-domain weights but does not itself demonstrate an invariant that the complete vector is normalized. Add boundary/service validation for the selected lens policy, including non-negative values and the required sum/normalization rule. ## 8. Remove global voting-power semantics from EkoH UI ### `frontend/app/ekoh/voting-influence/current-voting-weight/page.tsx` The current page uses simulated values and says a user's EkoH reputation gives a global Smart Vote influence percentage. That conflicts with the contextual model. Replace it with one of: - domain expertise display; - consultation-specific expertise alignment; - a declared Smart Vote reading weight tied to a specific lens/consultation; - educational explanation that no universal voting weight exists. Never display a universal `Smart Vote Weight` derived only from the person. ## 9. Update stale code comments around reading availability ### `frontend/services/decide.ts` The implementation already calls: ```text /api/v1/smart-vote/readings/ethikos-topic/<id>/ ``` Update the surrounding comments/documentation to match the active API while retaining the rule: never fabricate a reading from baseline. ## 10. Pulse/analytics should stop depending on compatibility vote rows Current frontend analytics code reads `kollective/votes/` in Pulse calculations. Move those reads to the canonical source/event contract appropriate to the metric being displayed. Do not mix ethiKos stances, Smart Vote ballots and Smart Vote derived readings into one untyped participation counter. ## 11. Use domain names in active code comments and API documentation Active router/admin comments and API documentation should name the actual domain responsibility (`structured deliberation`, `argument source`, `argument impact`, etc.). Database migration filenames do not need cosmetic rewriting. ## 12. External ecosystem boundaries are not implemented yet No active Konnaxion adapter was found for Orgo, Kristal or SemantiK Architect. When those are implemented, add dedicated boundary packages/adapters rather than importing their internal models. ### Orgo boundary Needs explicit command/query/event/receipt semantics and correlation/idempotency. No Case↔Topic or Task↔Consultation identity. ### Kristal boundary Only add when a concrete Kristal artifact use case exists. Preserve Kristal epistemic metadata and do not take ownership of kOA-Linux local activation. ### SemantiK Architect boundary Use a generation request/response adapter; Architect must not mutate Konnaxion source state. ### kOA-Linux integration Prefer deployment/component contracts at the platform boundary. Host privilege/resource/lifecycle concerns should not be implemented as Konnaxion business models. ## 13. Areas that are already architecturally strong Preserve these patterns: - `konnaxion.ekoh.services.contextual_analysis` is non-authoritative; - `konnaxion.ekoh.services.rating_access` centralizes disclosure policy; - `SourceConsultationBinding` is explicit; - ethiKos stance/argument ownership is local; - Smart Vote reading baseline and advisory result are separate; - privacy filtering is performed server-side; - frontend `decide.ts` does not copy the baseline into the reading when the endpoint returns no reading. ================================================================================================ FILE: docs/Technical-Reference/DEV_DOCKER_CHEATSHEET.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: fa25e913da4b5fd029e462d7b0d0a45a29aa9458e92bd2ec9a289ef2a24fad2a CONTENT_BYTES: 6250 ================================================================================================ Here is a compact cheat sheet tailored to your project (Docker + Django + migrations). Assumptions: * Services: `django`, `celeryworker`, `celerybeat`, `flower`, `postgres`, `redis`, `nginx` * Compose files: `docker-compose.local.yml`, `docker-compose.production.yml`, `docker-compose.docs.yml` * Stack is Cookiecutter‑Django style with Postgres + Redis. --- ## 1. Local Docker (docker-compose.local.yml) ### Start / stop ```bash # Start whole stack (foreground) docker compose -f docker-compose.local.yml up # Start whole stack (background) docker compose -f docker-compose.local.yml up -d # Stop and remove containers docker compose -f docker-compose.local.yml down ``` ### Common operations ```bash # Restart only Django docker compose -f docker-compose.local.yml restart django # See logs docker compose -f docker-compose.local.yml logs -f django docker compose -f docker-compose.local.yml logs -f celeryworker # Open a shell in the django container docker compose -f docker-compose.local.yml run --rm django bash # Run any Django management command docker compose -f docker-compose.local.yml run --rm django python manage.py <command> # Example: docker compose -f docker-compose.local.yml run --rm django python manage.py createsuperuser ``` ### Rebuild (when needed) Local code is mounted via volume, so: * Change only Python / templates → usually no rebuild, just restart if needed: ```bash docker compose -f docker-compose.local.yml restart django ``` * Change dependencies (`requirements*.txt`, system libs, Dockerfile) → rebuild: ```bash docker compose -f docker-compose.local.yml build django celeryworker celerybeat flower docker compose -f docker-compose.local.yml up -d django celeryworker celerybeat flower ``` --- ## 2. Production Docker (docker-compose.production.yml) ### Start / stop ```bash # Start or update in background docker compose -f docker-compose.production.yml up -d # Stop everything docker compose -f docker-compose.production.yml down ``` ### Rebuild after backend changes After you pull new code (including migrations): ```bash # Rebuild backend images docker compose -f docker-compose.production.yml build django celeryworker celerybeat flower # Bring them up with the new images docker compose -f docker-compose.production.yml up -d django celeryworker celerybeat flower ``` ### Logs and commands ```bash # Logs docker compose -f docker-compose.production.yml logs -f django docker compose -f docker-compose.production.yml logs -f celeryworker # Management commands (run once, then container exits) docker compose -f docker-compose.production.yml run --rm django python manage.py <command> # examples: docker compose -f docker-compose.production.yml run --rm django python manage.py migrate docker compose -f docker-compose.production.yml run --rm django python manage.py collectstatic --noinput ``` --- ## 3. Django migrations: concept + commands ### What migration files are * Located in each app: `app_name/migrations/0001_initial.py`, `0002_*.py`, etc. * Each file describes a change to the database schema: * create / delete tables * add / remove / rename fields * data migrations (`RunPython`) * Django stores which ones were applied in the `django_migrations` table. * Normal workflow: 1. Edit `models.py` 2. Generate migration files with `makemigrations` 3. Apply them to the DB with `migrate` ### Local: generate + apply migrations From project root: ```bash # 1) Create migrations from your model changes docker compose -f docker-compose.local.yml run --rm django python manage.py makemigrations # 2) Apply them to the local database docker compose -f docker-compose.local.yml run --rm django python manage.py migrate ``` Useful inspections: ```bash # See migration plan docker compose -f docker-compose.local.yml run --rm django python manage.py showmigrations # Only for one app docker compose -f docker-compose.local.yml run --rm django python manage.py showmigrations your_app_name ``` ### Production: apply existing migrations Best practice: * Generate migrations locally → commit to git → deploy → then migrate in production. On the server: ```bash # Apply all new migrations docker compose -f docker-compose.production.yml run --rm django python manage.py migrate ``` Run this after you’ve rebuilt and updated the containers with the new code. --- ## 4. “When do I run what?” quick matrix ### Code changes only (views, serializers, templates, etc.) * Local: * `up` already running → Django auto‑reload usually enough * If needed: `docker compose -f docker-compose.local.yml restart django` * Production: * Pull code → rebuild backend images → `up -d` → no extra migrate (unless models changed) ### Model changes (fields, new models) 1. Local: ```bash docker compose -f docker-compose.local.yml run --rm django python manage.py makemigrations docker compose -f docker-compose.local.yml run --rm django python manage.py migrate ``` 2. Commit and push migrations. 3. Production: ```bash docker compose -f docker-compose.production.yml build django celeryworker celerybeat flower docker compose -f docker-compose.production.yml up -d django celeryworker celerybeat flower docker compose -f docker-compose.production.yml run --rm django python manage.py migrate ``` ### You edited an existing migration file * If that migration is already applied in a DB (especially production): * Prefer: create a **new** migration that fixes things instead of editing the old one. * If it is not applied yet (e.g. new branch, fresh DB): * Just run `migrate`: ```bash # local docker compose -f docker-compose.local.yml run --rm django python manage.py migrate # production docker compose -f docker-compose.production.yml run --rm django python manage.py migrate ``` --- ## 5. Docs container (optional) If you want to run the docs stack: ```bash docker compose -f docker-compose.docs.yml up # foreground docker compose -f docker-compose.docs.yml up -d # background docker compose -f docker-compose.docs.yml down ``` --- If you want, I can turn this into a `docs/DEV_DOCKER_CHEATSHEET.md` you can drop directly into your repo. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Database Schema Reference (Custom Tables).md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: d7cd538a5f97c104635848378fcb64c62d5a3f440a85c7a8481c393f1779cc37 CONTENT_BYTES: 20225 ================================================================================================ # **Konnaxion v14 – Custom Database Tables (Canonical List)** *(Tables provided by Django or boilerplate (e.g. `auth_user`, `django_admin_log`, `socialaccount_*`) are omitted. Each entry lists the **Display Name → Model Class**, followed by a brief purpose and key columns (primary keys, foreign keys, enums, JSON fields; standard timestamps omitted unless notable). Structure and naming follow the v14 modular architecture as implemented.)* ## **Kollective Intelligence** ### **EkoH (Expertise & Reputation Domain)** * **Expertise Categories → ExpertiseCategory:** Catalog of knowledge domains used to classify expertise. **Key columns:** `id (PK)`, `name` (unique domain name). * **User Expertise Scores → UserExpertiseScore:** Each user’s current expertise score per domain. **Key columns:** `id (PK)`, `user` (FK to User), `category` (FK to ExpertiseCategory), `raw_score`, `weighted_score`. * **User Ethics Scores → UserEthicsScore:** Ethical weight multiplier applied to a user’s scores. **Key columns:** `user` (OneToOne FK to User, also PK), `ethical_score` (numeric value). * **Score Configurations → ScoreConfiguration:** Named weight parameters (global or field-specific) for score calculations. **Key columns:** `id (PK)`, `weight_name` (e.g. parameter name), `weight_value`, `field` (nullable, identifies which field the weight applies to). * **Context Analysis Logs → ContextAnalysisLog:** Log of AI-driven adjustments to scores in context. **Key columns:** `id (PK)`, `entity_type` (model or context identifier), `entity_id`, `field` (name of score field adjusted), `input_metadata` (JSON of context data), `adjustments_applied` (JSON of changes made). * **Confidentiality Settings → ConfidentialitySetting:** Per-user privacy level preference for displaying identity alongside scores. **Key columns:** `user` (OneToOne FK to User, also PK), `level` (ENUM – `public` / `pseudonym` / `anonymous`). * **Score History → ScoreHistory:** Audit trail of all score changes for transparency. **Key columns:** `id (PK)`, `merit_score` (FK to UserExpertiseScore), `old_value`, `new_value`, `change_reason`. ### **Smart Vote (Weighted Voting System)** * **Votes → Vote:** Records each user vote with both raw and weighted values. **Key columns:** `id (PK)`, `user` (FK), `target_type` (string identifier of the content/user being voted on), `target_id` (ID of target entity), `raw_value` (e.g. vote value before weighting), `weighted_value` (value after EkoH-based weighting). * **Vote Modalities → VoteModality:** Defines parameters for various voting modes (approval, ranking, rating, etc.). **Key columns:** `id (PK)`, `name` (unique modality name), `parameters` (JSON field storing settings for this voting mode). * **Emerging Experts → EmergingExpert:** Flags users who are rapidly gaining expertise (merit) scores. **Key columns:** `id (PK)`, `user` (FK), `detection_date` (date flagged), `score_delta` (recent increase in score). * **Vote Results → VoteResult:** Aggregated result of votes per target (e.g. total weighted score). **Key columns:** `id (PK)`, `target_type`, `target_id`, `sum_weighted_value` (cumulative weighted score), `vote_count` (number of votes aggregated). * **Integration Mappings → IntegrationMapping:** Links Smart Vote context to other modules’ objects for cross-module voting. **Key columns:** `id (PK)`, `module_name` (target module identifier), `context_type` (target object type), `mapping_details` (JSON with mapping info). ## **ethiKos** ### **Korum (Structured Debates Platform)** * **Debate Categories → EthikosCategory:** Thematic categories for debates (e.g. Politics, Ethics, etc.). **Key columns:** `id (PK)`, `name` (unique category name), `description` (optional). * **Debates → EthikosTopic:** High-level debate topics or questions created by users (one per debate). **Key columns:** `id (PK)`, `title` (debate question or title), `status` (ENUM – e.g. `open`/`closed`/`archived`), `start_date`, `end_date` (optional scheduling of debate period). * **Stances → EthikosStance:** Each user’s stated stance or position on a given debate topic. **Key columns:** `id (PK)`, `topic` (FK to EthikosTopic), `user` (FK), `value` (integer value representing stance, constrained between \-3 and \+3). * **Debate Arguments → EthikosArgument:** User-submitted arguments/posts within a debate thread. **Key columns:** `id (PK)`, `topic` (FK to EthikosTopic), `author` (FK to User), `content` (text of the argument), `parent` (FK to another EthikosArgument for threaded replies, nullable), `side` (optional ENUM flag like “pro”/“con”). *(The following planned tables for AI-driven debate features were outlined but are not present in the current implementation and are omitted in this list: AI Clones, Comparative Analysis Logs, Debate Archives, Debate Summaries.)* ### **Konsultations (Public Consultations & Feedback)** * **Consultations → Consultation:** Public consultation instance (e.g. a time-bound survey or call for feedback). **Key columns:** `id (PK)`, `title`, `open_date`, `close_date`, `status` (ENUM – `open`/`closed`/`archived`). * **Citizen Suggestions → CitizenSuggestion:** User-submitted ideas or proposals within a consultation. **Key columns:** `id (PK)`, `consultation` (FK to Consultation), `author` (FK to User), `content` (suggestion text). * **Consultation Votes → ConsultationVote:** Votes on consultation proposals, with raw and weighted values (if EkoH weighting applied). **Key columns:** `id (PK)`, `user` (FK), `consultation` (FK), `raw_value`, `weighted_value`. * **Consultation Results → ConsultationResult:** Stores aggregated voting outcomes for a consultation. **Key columns:** `id (PK)`, `consultation` (FK), `results_data` (JSONB snapshot of vote totals or statistics). * **Impact Track → ImpactTrack:** Post-consultation action log to track implementation of accepted proposals. **Key columns:** `id (PK)`, `consultation` (FK), `action` (description of follow-up action), `status` (status of the action), `date` (when logged). *Here is a **ready-to-paste documentation table** for all actual `keenkonnect` models found in your backend code. This is structured for easy integration into your canonical reference file and aligns with Django best practices. Each model includes its **purpose**, main fields (with PK/FK/ENUM/constraints), and notes.* --- ## ***KeenKonnect Module – Canonical Database Table Reference (Fully Synced to Code)*** ***Note:** Fields like `created_at`/`updated_at` are omitted unless nonstandard. All ForeignKeys are to `users.User` unless otherwise noted.* --- ### ***Project*** ***Purpose:*** *Container for a collaborative project workspace (formerly “CollaborationSpace”).* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *title* | *CharField(255)* | *Project title* | | *description* | *TextField* | *Optional project description* | | *creator* | *FK(User)* | *Who created this project* | | *category* | *CharField(120)* | *e.g. “Energy”, “Education”, etc.* | | *status* | *CharField(16, ENUM)* | *e.g. draft, active, completed, archived* | | *created\_at* | *DateTimeField* | *Auto-added* | | *updated\_at* | *DateTimeField* | *Auto-updated* | --- ### ***ProjectResource*** ***Purpose:*** *Links documents, files, or resources to a project.* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *project* | *FK(Project)* | *Parent project* | | *title* | *CharField(255)* | *Resource name* | | *url* | *URLField* | *Resource URL/path* | | *added\_by* | *FK(User)* | *Uploader* | | *created\_at* | *DateTimeField* | | --- ### ***ProjectTask*** ***Purpose:*** *A task, to-do, or milestone in a project (Kanban or similar).* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *project* | *FK(Project)* | *Parent project* | | *title* | *CharField(255)* | *Task summary* | | *description* | *TextField* | *Task details* | | *assignee* | *FK(User, nullable)* | *Assigned user* | | *status* | *CharField(16, ENUM)* | *e.g. todo, in\_progress, done, blocked* | | *due\_date* | *DateField (nullable)* | *Optional due date* | | *created\_at* | *DateTimeField* | | | *updated\_at* | *DateTimeField* | | --- ### ***ProjectMessage*** ***Purpose:*** *A message in a project chat/thread.* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *project* | *FK(Project)* | *Parent project* | | *sender* | *FK(User)* | *Message author* | | *content* | *TextField* | *Message text* | | *created\_at* | *DateTimeField* | | --- ### ***ProjectTeam*** ***Purpose:*** *Defines project team membership and roles.* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *project* | *FK(Project)* | *Parent project* | | *user* | *FK(User)* | *Team member* | | *role* | *CharField(32)* | *e.g. owner, member, advisor, etc.* | | *joined\_at* | *DateTimeField* | | --- ### ***ProjectRating*** ***Purpose:*** *Stores ratings/reviews for a project.* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *project* | *FK(Project)* | *Rated project* | | *user* | *FK(User)* | *Reviewer* | | *rating* | *IntegerField* | *e.g. 1–5* | | *comment* | *TextField* | *Optional feedback* | | *created\_at* | *DateTimeField* | | --- ### ***Tag*** ***Purpose:*** *Reusable keyword for projects or tasks.* | *Field* | *Type* | *Notes* | | ----- | ----- | ----- | | *id* | *BigAutoField (PK)* | *Primary key* | | *name* | *CharField(64, uniq)* | *Tag label (unique)* | --- ## ***Notes*** * *Models like `RealTimeDocument`, `ChatMessage`, `VideoSession`, and `AIInteractionLog` are not present in the current codebase (under these names). If you require them for future features, add them to both code and doc.* * *If you use ManyToMany relationships (e.g., tags on projects/tasks), document them in the canonical file.* * *Each model’s “purpose” should be updated as your platform evolves.* ## **KonnectED** ### **CertifiKation (Skills & Certification)** * **Certification Paths → CertificationPath:** Defines a structured learning or certification path (a sequence of skills/lessons to master). **Key columns:** `id (PK)`, `name` (name of the certification or learning path), `description` (textual description of the path). * **Evaluations → Evaluation:** Stores results of an automated or manual evaluation for a user on a certification path. **Key columns:** `id (PK)`, `user` (FK), `path` (FK to CertificationPath), `raw_score` (numeric score achieved), `metadata` (JSON field with additional details, e.g. answers or scoring breakdown). * **Peer Validations → PeerValidation:** Records a peer mentor’s validation decision on a user’s submitted evidence for a skill (part of the certification). **Key columns:** `id (PK)`, `evaluation` (FK to Evaluation being reviewed), `peer` (FK to User acting as validator), `decision` (ENUM – `approved` or `rejected`). --- ### **Module: KonnectED** #### **Portfolios → Portfolio** **Purpose:** User skill showcase. Each portfolio is a curated collection of KnowledgeResources that demonstrate a user’s skills, achievements, or project evidence. **Fields:** | Field | Type | Notes | | ----- | ----- | ----- | | id | BigAutoField (PK) | Primary key | | user | ForeignKey(User) | Owner of the portfolio | | title | CharField(255) | Portfolio title | | description | TextField (optional) | Description of the portfolio | | items | ManyToManyField(KnowledgeResource, blank=True, related\_name="portfolios") | Collection of evidence artefacts (documents, videos, etc.) | | created\_at | DateTimeField (auto\_now\_add) | Timestamp | | updated\_at | DateTimeField (auto\_now) | Timestamp | **Notes:** * `items` links to existing KnowledgeResource objects. * To support ad-hoc/loose artefacts in future, consider an auxiliary JSONField or Attachment model (not currently present). **Example Table Structure (for documentation):** | id | user | title | description | items (M2M) | created\_at | updated\_at | | ----- | ----- | ----- | ----- | ----- | ----- | ----- | | 1 | 12 | Data Viz | DS work | \[3, 7, 12\] | ... | ... | --- * **Interop Mappings → InteropMapping:** Mapping of internal certifications to external systems’ identifiers (for LMS interoperability). **Key columns:** `id (PK)`, `local_certification` (FK to CertificationPath), `external_system` (name of external platform), `external_id` (identifier of equivalent certification on external system). ### **Knowledge (Collaborative Learning Library)** * **Knowledge Resources → KnowledgeResource:** Metadata for a shared learning resource (article, video, course, etc.) in the KonnectED library. **Key columns:** `id (PK)`, `title`, `type` (ENUM – e.g. video, doc, course, other), `url` (link or location of the resource), `author` (FK to User who added it, nullable). * **Knowledge Recommendations → KnowledgeRecommendation:** Records that a particular resource was recommended to a user (often by an ML algorithm or expert). **Key columns:** `id (PK)`, `user` (FK – recommendation recipient), `resource` (FK to KnowledgeResource), `recommended_at` (timestamp of recommendation). * **Learning Progress → LearningProgress:** Tracks a user’s progress/completion percentage for a given learning resource. **Key columns:** `id (PK)`, `user` (FK), `resource` (FK to KnowledgeResource), `progress_percent` (progress as a percentage) (unique per user-resource pair). ### **Co-Creation (Community Content Creation)** * **Co‑Creation Projects → CoCreationProject:** A collaborative content creation project (e.g. creating a course or document together). **Key columns:** `id (PK)`, `title`, `status` (ENUM – e.g. draft, active, archived). * **Co‑Creation Contributions → CoCreationContribution:** An individual contribution or edit made by a user to a co-creation project. **Key columns:** `id (PK)`, `project` (FK to CoCreationProject), `user` (FK to contributor), `content` (text/content of the contribution). ### **Forums (Discussion Boards for Learning)** * **Forum Topics → ForumTopic:** A discussion topic/thread in the educational forums (usually tied to a subject or question). **Key columns:** `id (PK)`, `title`, `category` (free-text or predefined category of the topic), `creator` (FK to User who started the topic). * **Forum Posts → ForumPost:** Posts or replies within a forum topic thread. **Key columns:** `id (PK)`, `topic` (FK to ForumTopic), `author` (FK to User), `content` (text of the post). ## **Kreative (+ Kontact)** ### **Konservation (Creative Content & Cultural Preservation)** * **Tags → Tag:** Global tagging vocabulary for artworks (and other content). **Key columns:** `id (PK)`, `name` (unique tag name). *(This tag list is shared and reused in multiple creative contexts.)* * **Artworks → KreativeArtwork:** A single piece of art or creative work uploaded by a user (image, video, audio, etc.). **Key columns:** `id (PK)`, `artist` (FK to User, creator of the artwork), `title`, `description` (optional), `media_file` (file path for the content), `media_type` (ENUM – image/video/audio/other), `year` (optional year of creation), `medium` (text field for medium/material, e.g. “oil on canvas”), `style` (text field for artistic style). *(Each artwork can have multiple tags; see ArtworkTag below.)* * **Artwork Tags → ArtworkTag:** Join table linking Artworks with Tags (many-to-many). **Key columns:** `id (PK)`, `artwork` (FK to KreativeArtwork), `tag` (FK to Tag). *(Enforces uniqueness per artwork-tag pair.)* * **Galleries → Gallery:** A curated gallery or collection of artworks, often for virtual exhibition purposes. **Key columns:** `id (PK)`, `title` (gallery name), `description` (optional), `created_by` (FK to User curator, nullable), `theme` (optional theme name), `created_at` (timestamp). *(Each Gallery can contain many artworks; see GalleryArtwork below.)* * **Gallery Artworks → GalleryArtwork:** Through-table for artworks included in a gallery, preserving order and uniqueness. **Key columns:** `id (PK)`, `gallery` (FK to Gallery), `artwork` (FK to KreativeArtwork), `order` (position of the artwork in the gallery). * **Tradition Entries → TraditionEntry:** A submission of cultural heritage content (e.g. photos, videos, descriptions of traditions) for preservation in the “Konservation” archive. **Key columns:** `id (PK)`, `title` (name of the tradition or entry), `description` (text description), `region` (region/culture identifier, text), `media_file` (uploaded media file showcasing the tradition), `submitted_by` (FK to User, nullable), `submitted_at` (timestamp), `approved` (boolean flag if approved for archive), `approved_by` (FK to User who approved, nullable), `approved_at` (timestamp). ### **Kontact (Collaboration & Networking)** * **Collaboration Sessions → CollabSession:** Real-time collaborative sessions for artists (e.g. joint painting, jam sessions). **Key columns:** `id (PK)`, `name` (session title), `host` (FK to User who started the session), `session_type` (ENUM – e.g. painting, music, mixed media), `started_at`, `ended_at` (timestamps for session duration), `final_artwork` (FK to KreativeArtwork created as the outcome, nullable). ## **Insights (Reporting & Analytics Module)** ### **Dimension Tables (Analytical Reference Data)** * **Date Dimension → dim\_date:** Canonical calendar dates for aggregations. **Key columns:** `date_id` (PK, surrogate key), `calendar_date` (actual date), `year`, `month`, `week`, `day`, `iso_week`, etc. (Pre-populated with a range of dates for analysis). * **Domain Dimension → dim\_domain:** Enumerates high-level domain contexts (module or functional domains) for analytics. **Key columns:** `domain_id` (PK), `domain_code` (ENUM of domain codes). *(Matches the module/domain identifiers used in the OLTP system.)* * **API Endpoint Dimension → dim\_endpoint:** Lists backend API endpoints for performance analytics. **Key columns:** `endpoint_id` (PK), `path` (URL path or endpoint name). ### **Fact Tables (Partitioned Event/Metric Data)** * **Smart Vote Fact → smart\_vote\_fact:** Records of votes cast, for analytics of voting patterns. **Key columns:** `id` (PK, UUID), `date_id` (FK to dim\_date), `domain_id` (FK to dim\_domain, e.g. which module the vote is in), `question_id` (UUID of the voted content/question), `user_id` (UUID hash or anonymized user ID), `vote_value` (numeric vote value), `score_normalised` (normalized score used in vote). *(Partitioned monthly by date; indexed by domain and date.)* * **Usage MAU Fact → usage\_mau\_fact:** Monthly active user metrics and content creation counts per domain. **Key columns:** `id` (PK, UUID), `month_id` (FK to dim\_date, points to first day of month), `domain_id` (FK to dim\_domain), `mau` (count of monthly active users), `projects_created`, `docs_uploaded` (counts of content created in that month/domain). *(Partitioned by year; B-tree indexed by month and domain.)* * **API Performance Fact → api\_perf\_fact:** Daily API performance metrics (per endpoint, per hour). **Key columns:** `id` (PK, UUID), `date_id` (FK to dim\_date), `hour_of_day` (0–23), `endpoint_id` (FK to dim\_endpoint), `p95_latency_ms` (95th percentile latency in ms), `error_rate_pct` (error percentage), `request_count` (total requests). *(Partitioned by month via date; indexed by endpoint, date, hour.)* --- **Note:** The above list is derived from the Konnaxion v14 documentation and the latest Django models and migration definitions. It is structured by module and sub-module for clarity, and is intended to replace the outdated canonical tables list with an accurate, developer-friendly reference. Each table’s purpose and key schema details have been verified against the implementation and v14 specifications for completeness and correctness. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Database Schema Reference.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 7fc886985ca3a70c61f6e1f35dae3ec678b91f0070b8e7721dc66b137cb8bbb7 CONTENT_BYTES: 4698 ================================================================================================ # Konnaxion v14 — Database Schema Reference ## Purpose This reference identifies **canonical ownership and major current model families**. It does not duplicate every migration field; the Django models and migrations remain the executable physical schema. ## 1. users Canonical owner: `konnaxion.users`. Shared user identity is referenced by Konnaxion domain models through `AUTH_USER_MODEL = users.User`. ## 2. ethiKos Canonical owner: `konnaxion.ethikos`. Current models: | Model | Role | |---|---| | `EthikosCategory` | topic classification | | `EthikosTopic` | civic/deliberation topic | | `EthikosStance` | one user's topic-level stance | | `EthikosArgument` | argument/reply node | | `ArgumentSource` | source/evidence attached to argument | | `ArgumentImpactVote` | argument-level impact evaluation | | `ArgumentSuggestion` | proposed structured change/contribution | | `DiscussionParticipantRole` | participant role in a discussion | | `DiscussionVisibilitySetting` | discussion visibility policy | | `DemoScenarioImport` | demo-import tracking | Key invariants: - `EthikosStance.value` is constrained to `-3..+3`; - one stance per `(user, topic)`; - `ArgumentImpactVote` is distinct from `EthikosStance`; - Smart Vote readings do not rewrite these source rows. ### Alignment issue `EthikosTopic.expertise_category` currently targets `kollective_intelligence.ExpertiseCategory`; the canonical EkoH taxonomy is `ekoh.ExpertiseCategory`. This relation must be realigned in code/data migrations. ## 3. EkoH Canonical owner: `konnaxion.ekoh`. Current model families: | Model | Role | |---|---| | `ExpertiseCategory` | hierarchical expertise taxonomy | | `UserExpertiseScore` | user/domain expertise score | | `UserEthicsScore` | governed ethics/reliability context | | `ScoreConfiguration` | score configuration | | `ScoreHistory` | score change trace | | `ConfidentialitySetting` | identity privacy | | `RatingVisibilitySetting` | rating visibility policy | | `RatingAccessScope` | hierarchical access scope | | `RatingScopeSubject` | subject membership in access scope | | `RatingAccessGrant` | viewer access grant | | `ContextAnalysisLog` | non-authoritative contextual analysis record | The EkoH taxonomy and scores are the canonical source for EkoH/Smart Vote contextual expertise. New code must not use `kollective_intelligence` compatibility equivalents as source of truth. ## 4. Smart Vote Canonical owner: `konnaxion.smart_vote`. Current models: | Model | Role | |---|---| | `Consultation` | Smart Vote consultation/reading context | | `ConsultationRelevance` | consultation → EkoH domain relevance | | `SourceConsultationBinding` | explicit source object → consultation binding | | `VoteModality` | ballot modality definition | | `Vote` | current Smart Vote ballot row | | `VoteResult` | current aggregate row | | `VoteLedger` | vote ledger record | ### Architectural interpretation For ethiKos-bound readings, the source of civic truth is `EthikosStance`; `SourceConsultationBinding` references it indirectly through the topic and Smart Vote computes a separate reading. The fields `Vote.weighted_value` and `VoteResult.sum_weighted_value` must not be treated as universal/canonical civic truth. The code path that creates them requires alignment with the source-fact/derived-reading separation. ## 5. keenKonnect Canonical owner: `konnaxion.keenkonnect`. Current model families include projects, project resources, tasks, messages, teams, ratings and tags. ## 6. KonnectED Canonical owner: `konnaxion.konnected`. Current model families include: - certification paths; - evaluations; - peer validations; - portfolios; - interoperability mappings; - knowledge resources; - recommendations; - learning progress; - offline packages; - mentorship; - co-creation; - forums. ## 7. Kreative Canonical owner: `konnaxion.kreative`. Current model families include: - tags; - artworks; - gallery relations; - collaboration sessions; - traditions; - virtual exhibitions; - digital archives/documents; - AI catalogue entries; - cultural partners. ## 8. TeamBuilder Canonical owner: `konnaxion.teambuilder`. Models: - `Problem`; - `ProblemChangeEvent`; - `BuilderSession`; - `Team`; - `TeamMember`. ## 9. Shared/admin models Konnaxion also contains moderation, trust, Kontrol and shared user/platform state. These remain Konnaxion-owned and should not be merged into Orgo/Kristal models merely for integration convenience. ## 10. Physical database scope The current settings register EkoH and Smart Vote separately and use the `ekoh_smartvote,public` search path for their tables. Physical schema placement does not merge their logical ownership. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Documentation Index.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: bf4fb4433c43b55442ae1aead746b69d4edd56178cd3e81afde7155d0b364983 CONTENT_BYTES: 1422 ================================================================================================ # Konnaxion v14 — Documentation Index ## Architecture - `Konnaxion v14 - Full-Stack Technical Specification.md` — system identity, domains, runtime shape and external boundaries. - `Konnaxion v14 - Database Schema Reference.md` — canonical model ownership and major schema families. - `Konnaxion v14 - Site Navigation Map.md` — actual App Router surface from the current code snapshot. - `Konnaxion v14 - Insights UI Reference.md` — detailed reporting/analytics UI reference. ## Cross-cutting contracts - `../GLOSSARY.md` — terminology and category rules. - `../BOUNDARIES_AND_OWNERSHIP.md` — domain ownership and external boundaries. - `../CONTRACTS.txt` — current API contract surface. - `../CODE_ALIGNMENT_NOTES.md` — code areas that still need architectural alignment. - `../GENERALinstructionsForAI.txt` — compact implementation rules for AI/code generation. ## EkoH / Smart Vote - `../EkoH Smart Vote/EkoH and Smart Vote - Technical Specification.md` - `../EkoH Smart Vote/EkoH - System Overview.md` - `../EkoH Smart Vote/Smart Vote - Reading Contract.md` - `../EkoH Smart Vote/EkoH and Smart Vote - Data Model.md` ## User flows - `../../Konnaxion_User_Workflows.md` - `../../demo-scenarios/ethikos/ETHIKOS_DEMO_IMPORTER.md` ## Operations - `../DEV_DOCKER_CHEATSHEET.md` - `../Konnaxion_Frontend_Deployment_Runbook.md` - `../UpdateBackendAndMigrateAndDocker.md` - `../namecheap-vps.md` ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Full-Stack Technical Specification.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: d476204db3043cd1036c38e8b5761f321d04883410829471957f5bb1b9bcfdeb CONTENT_BYTES: 12495 ================================================================================================ # Konnaxion v14 — Full-Stack Technical Specification ## 1. Architectural identity Konnaxion is an **ecosystem system** in the kOA Digital Ecosystem and a **platform** in its own product scope. It is implemented as a shared product composed of multiple domain/application surfaces rather than a collection of isolated standalone apps. Current stack: - frontend: Next.js + React + TypeScript, App Router; - backend: Django + Django REST Framework; - primary relational store: PostgreSQL; - asynchronous execution: Celery + Redis; - API documentation: drf-spectacular/OpenAPI; - EkoH/Smart Vote tables use the dedicated `ekoh_smartvote` search-path scope in the current backend settings. Konnaxion owns Konnaxion domain state. External ecosystem systems integrate through explicit contracts. ## 2. Terminology Within product/UI language, Konnaxion may call named areas `modules`. In architecture, this document distinguishes: - **domain** — authoritative business semantics/state; - **application surface** — user-facing capability; - **service** — executable capability/API/task; - **gateway** — boundary adapter; - **external ecosystem system** — independently owned system such as Orgo, Kristal, SemantiK Architect or kOA-Linux. `Kollective Intelligence` is a product/navigation umbrella. It is not the canonical backend owner for EkoH or Smart Vote data. ## 3. System shape ```text Konnaxion │ ├── shared platform │ ├── users/auth/session │ ├── moderation/audit │ ├── shared navigation/search │ └── common frontend/runtime infrastructure │ ├── civic domain │ └── ethiKos │ ├── Korum logical structured deliberation │ └── Konsultations logical consultation/decision source boundary │ ├── contextual intelligence │ ├── EkoH expertise / ethics / privacy / rating access │ └── Smart Vote declared derived readings │ ├── collaboration │ └── keenKonnect │ ├── learning / credentials │ └── KonnectED │ ├── creative / cultural │ └── Kreative │ ├── TeamBuilder ├── Kontrol ├── Konsensus UI └── Reports / Insights ``` The diagram is a responsibility map, not a claim that every logical sub-domain has a separate Django app. ## 4. Global invariants ### 4.1 One owner per authoritative state A domain mutates its own state. Other domains/systems use APIs, services, commands, queries, events or artifact references. ### 4.2 Single Truth, Multiple Readings ```text source facts ↓ baseline ↓ optional declared lens + snapshot context ↓ derived reading ``` The reading does not rewrite the source. ### 4.3 EkoH is context, not sovereignty Expertise and ethics signals are contextual and bounded. They do not become a universal rank or a fixed global voting power. ### 4.4 Presentation does not own the domain A page may combine results from several domains. That does not transfer write ownership to the UI or aggregation layer. ## 5. Backend platform ### 5.1 Django apps Current local apps include: - `konnaxion.users`; - `konnaxion.ethikos`; - `konnaxion.ekoh`; - `konnaxion.smart_vote`; - `konnaxion.keenkonnect`; - `konnaxion.konnected`; - `konnaxion.kreative`; - `konnaxion.moderation`; - `konnaxion.trust`; - `konnaxion.kontrol`; - `konnaxion.teambuilder`. `konnaxion.kollective_intelligence` remains present in the codebase but is not the canonical owner for EkoH/Smart Vote functionality. Active runtime references to it are an alignment concern documented in `CODE_ALIGNMENT_NOTES.md`. ### 5.2 API routing The central router lives in `backend/config/api_router.py`; project-level URL composition lives in `backend/config/urls.py`. Primary current route families: ```text /api/ethikos/* /api/v1/ekoh/* /api/v1/smart-vote/* /api/keenkonnect/* /api/konnected/* /api/kreative/* /api/teambuilder/* /api/admin/* /api/reports/* ``` Compatibility aliases under `/api/deliberate/*` map to ethiKos and do not create a second civic owner. ## 6. ethiKos / civic domain ### 6.1 Current physical implementation Primary backend package: ```text backend/konnaxion/ethikos/ ``` Primary frontend family: ```text frontend/app/ethikos/ ``` ### 6.2 Current source objects `EthikosTopic` - title/description/status; - category; - creator; - total-vote/activity metadata; - current code still carries an expertise-category relation that must be aligned to canonical EkoH taxonomy. `EthikosStance` - one user stance per topic; - integer value constrained to -3..+3; - source participation state. `EthikosArgument` - structured argument/reply; - parent relation; - pro/con side where declared; - moderation visibility flag. Additional implemented deliberation objects: - `ArgumentSource`; - `ArgumentImpactVote`; - `ArgumentSuggestion`; - `DiscussionParticipantRole`; - `DiscussionVisibilitySetting`. Together these form the implemented Korum-style structured deliberation surface. ### 6.3 Korum Korum is the logical structured-deliberation sub-domain. In the current code it is implemented inside `konnaxion.ethikos` rather than as a separate persistence owner. Pattern mapping: ```text Discussion → EthikosTopic Claim/argument → EthikosArgument Reply relation → parent Pro/con relation → side Evidence/source → ArgumentSource Argument impact → ArgumentImpactVote Participation role → DiscussionParticipantRole Visibility policy → DiscussionVisibilitySetting ``` ### 6.4 Konsultations Konsultations is the logical consultation/intake/decision source boundary. Formal civic source ballots must remain distinguishable from deliberation stances and from Smart Vote readings. No automatic identity is allowed between: ```text Konsultation ≠ Orgo Task EthikosTopic ≠ Orgo Case EthikosStance ≠ Smart Vote reading ``` ## 7. EkoH Canonical backend package: ```text backend/konnaxion/ekoh/ ``` EkoH owns: - `ExpertiseCategory`; - `UserExpertiseScore`; - `UserEthicsScore`; - `ScoreConfiguration`; - `ScoreHistory`; - `ConfidentialitySetting`; - `RatingVisibilitySetting`; - `RatingAccessScope`; - `RatingScopeSubject`; - `RatingAccessGrant`; - `ContextAnalysisLog`. ### 7.1 Expertise Expertise is a domain vector, not a single global rank. The current multidimensional scoring service normalizes evidence axes and persists a bounded `0..1` domain score. Lack of expertise does not create negative merit. ### 7.2 AI/context analysis The current contextual-analysis service correctly records analysis as **non-authoritative**. It does not silently mutate `UserExpertiseScore`. This behavior is architectural and should be preserved. ### 7.3 Rating access `konnaxion.ekoh.services.rating_access` is the server-side authority for rating disclosure. It distinguishes self/staff, explicit scope grants, public policy and deny behavior. Identity confidentiality and rating visibility remain separate contracts. ## 8. Smart Vote Canonical backend package: ```text backend/konnaxion/smart_vote/ ``` ### 8.1 Current implemented reading path The current code implements: ```text GET /api/v1/smart-vote/readings/ethikos-topic/<topic_id>/ ``` The reading service: 1. resolves `SourceConsultationBinding`; 2. loads `ConsultationRelevance`; 3. reads canonical `EthikosStance` rows; 4. reads EkoH expertise/ethics context; 5. computes a lens hash; 6. computes a baseline from source stances; 7. computes a separate `ekoh_weighted_v1` advisory reading; 8. returns baseline and derived reading separately. This is the correct source/reading separation to preserve. ### 8.2 Reading envelope Current payload shape includes: ```text target_type target_id smart_vote_consultation_id baseline.reading_key baseline.computed_at baseline.results_payload readings[].reading_key readings[].lens_hash readings[].snapshot_ref readings[].computed_at readings[].results_payload ``` ### 8.3 Reproducibility requirement A `snapshot_ref` is only sufficient for a published/replayable reading if the referenced input snapshot can actually be recovered or reconstructed. Current on-demand hashing is useful identity evidence but should not be confused with durable snapshot persistence. ### 8.4 Source ballot separation Target architecture requires raw source participation and weighted/derived interpretation to remain separate. Current Smart Vote `Vote.weighted_value` / `VoteResult.sum_weighted_value` paths require code alignment; see `CODE_ALIGNMENT_NOTES.md`. ## 9. keenKonnect Current backend package: ```text backend/konnaxion/keenkonnect/ ``` Canonical API families include projects, resources, tasks, messages, teams, ratings and tags under `/api/keenkonnect/*`. KeenKonnect state remains owned by its domain. EkoH context displayed in collaboration surfaces does not make EkoH the project owner. ## 10. KonnectED Current backend package: ```text backend/konnaxion/konnected/ ``` Implemented model families include: - knowledge resources; - recommendations/progress; - certification paths/evaluations; - peer validation; - portfolios; - offline packages; - mentorship; - co-creation; - forums. A KonnectED `OfflinePackage` is a Konnaxion learning/content artifact. It is not a Kristal Runtime Pack unless an explicit integration contract adopts that semantics. ## 11. Kreative Current backend package: ```text backend/konnaxion/kreative/ ``` Implemented model families include artworks, galleries, collaboration sessions, traditions, digital archives, archive documents, virtual exhibitions, AI catalogue entries and cultural partners. ## 12. TeamBuilder Current backend package: ```text backend/konnaxion/teambuilder/ ``` Core implemented state includes: - `Problem`; - `ProblemChangeEvent`; - `BuilderSession`; - `Team`; - `TeamMember`. TeamBuilder is a Konnaxion problem/team application. Its session/task semantics are not Orgo Case/Task semantics unless an explicit boundary is added. ## 13. Kontrol Kontrol is the Konnaxion administrative application surface for platform-level moderation, users/roles, audit and configuration views. It may aggregate multiple Konnaxion domains, but every domain mutation remains subject to the domain's actual backend service/authorization path. ## 14. Reports / Insights Reports is a cross-domain read/analytics surface under `/reports/*` and `/api/reports/*` where implemented. Reporting does not become an authoritative state owner simply because it aggregates data. ## 15. Frontend architecture The current product uses Next.js App Router under `frontend/app` with shared providers/layout plus domain page shells. Major route families include: ```text /ethikos/* /ekoh/* /keenkonnect/* /konnected/* /kreative/* /konsensus/* /kontrol/* /reports/* /teambuilder/* /search ``` The exact current route inventory is maintained in `Konnaxion v14 - Site Navigation Map.md`. ## 16. External boundaries ### 16.1 Orgo No current code adapter is present. Future integration must use explicit command/query/event/artifact/receipt contracts. No shared database write is permitted. ### 16.2 Kristal No current code adapter is present. Konnaxion may eventually consume/present Kristal artifacts, but Kristal owns their epistemic semantics and kOA-Linux owns local Runtime Pack activation state when that platform is used. ### 16.3 SemantiK Architect No current code adapter is present. A future integration is a generation/presentation boundary, not a Konnaxion state owner. ### 16.4 kOA-Linux When Konnaxion is deployed under kOA-Linux, kOA-Linux owns the local host/platform boundary while Konnaxion retains its domain authority. ### 16.5 K-Port K-Port is an EkoH evidence gateway/application, not a peer ecosystem system. It may submit normalized evidence into EkoH's governed boundary; EkoH remains the score owner. ## 17. Security and privacy - Konnaxion server-side authorization controls mutations. - EkoH rating access is server-side and scope-aware. - identity confidentiality and rating visibility are separate. - AI proposals do not silently mutate EkoH authoritative scores. - UI code must not reconstruct private scores or weights from hidden inputs. ## 18. Code alignment The architecture above is the target Konnaxion contract. Known code areas that still diverge are listed without project-management machinery in `Technical-Reference/CODE_ALIGNMENT_NOTES.md`. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Insights UI Reference.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: e9fb72cb4bec884a301cc392bd12a7d417cb8df05d4081decf5cabef393883b3 CONTENT_BYTES: 25777 ================================================================================================ ### **Konnaxion v14 – Insights Module UI Spec (Reporting & Analytics Front-end)** *(fully updated, implementation-aligned)* ### --- ## **Document 5.1 – Reporting & Analytics · Frontend layer** ### --- ### **1. Scope** Describes the currently implemented **frontend slice** of the Konnaxion **Insights / Reporting & Analytics** module. This document covers the **user-facing React / Next.js App Router pages** that expose read-only analytical views and a beta custom report-building experience under the **`/reports`** namespace. It includes: - the Reports landing / hub page - the Smart Vote dashboard - the Usage dashboard - the Performance dashboard - the beta Custom Report Builder page - their shared shell, filters, navigation, preview state, and data-access expectations This document is limited to the **frontend layer**. The backend service contract is described in **Document 5.2**, the analytical schema in **Document 5.3**, and infrastructure / operations in **Document 5.4**. ### **Implementation status note** The Reports frontend is an implemented Konnaxion surface. The current codebase contains implemented routes and page files for: - `/reports` - `/reports/custom` - `/reports/smart-vote` - `/reports/usage` - `/reports/perf` The current frontend workspace has also passed both: - `tsc --noEmit` - `pnpm build` Accordingly, this document is written as an **implementation-aligned frontend specification**, not as a speculative package design. ### --- ### **2. Routes & Navigation** | Route | Page | Current role | Consumed API(s) / runtime dependency | | ----- | ----- | ----- | ----- | | `/reports` | `ReportsHomePage` | Overview / hub page for Insights surfaces | none required for initial shell | | `/reports/smart-vote` | `SmartVoteDashboard` | Smart Vote / consensus analytics | `GET /api/reports/smart-vote` | | `/reports/usage` | `UsageDashboard` | MAU / projects / docs / adoption | `GET /api/reports/usage` | | `/reports/perf` | `PerfDashboard` | Latency, throughput, error, uptime views | `GET /api/reports/perf` | | `/reports/custom` | `CustomReportBuilderPage` | Beta builder / preview workflow | current frontend preview, optional `WS /ws/reports/custom` | ### **Navigation rules** - The **`/reports`** namespace is reserved for the Insights module. - The frontend uses a shared **`ReportsPageShell`** to provide title, subtitle, actions, and consistent page framing. - The Reports hub page acts as a **navigation entry point**, not as a replacement for the dedicated dashboards. - No other module may claim `/reports/*` or `/ws/reports/*` without a formal routing-reference update. ### **Current route ownership** The Reports / Insights slice remains a **global analytics surface** rather than an Ethikos-only or module-local sub-area. It may visualize data from multiple modules, but its route namespace remains distinct and reserved. ### --- ### **3. Primary UI Surfaces** | Surface / Component | Current role | Notes | | ----- | ----- | ----- | | `ReportsPageShell` | Shared page shell for all Reports pages | Standardized title, subtitle, actions, page framing | | Reports overview cards | Entry-point KPI / navigation cards on `/reports` | Directs users to dedicated dashboards | | Time-range controls | Quick-range + absolute date controls | Used where page semantics require filtering | | Dashboard KPI cards | Large summary metrics | Reused across dashboards | | Dashboard charts | Visual render of trends, KPIs, and distributions | Charting library remains implementation-defined | | Report shortcut list | Quick navigation from hub page | Links to Smart Vote / Usage / Perf | | Builder configuration form | Interactive builder UI on `/reports/custom` | Ant Design Pro form flow | | Builder preview panel | Live local preview / optional realtime preview | Current implementation is frontend-led / beta | | Export actions | Optional report export triggers | Governed by backend permissions and export limits | ### **Important correction vs older spec language** This frontend specification does **not** freeze the Reports slice to a single mandatory charting library. The current codebase already uses page-level implementation choices, and the authoritative contract is: - route ownership - shell/layout consistency - data-access contract - accessibility and testing expectations not a hard requirement that every dashboard must use one charting package. ### --- ### **4. Shared Layout, Shell, and UX Pattern** All Reports pages must render inside the shared **Reports page shell**, which provides: - a page title - a short descriptive subtitle - optional primary and secondary actions - consistent visual spacing and width behavior - compatibility with the broader platform design system The shell is the canonical wrapper for this slice and replaces any earlier assumptions that reports pages would live in a separate frontend package or an isolated micro-frontend shell. ### **Shell expectations** Each Reports page should supply: - `title` - `subtitle` - optional `metaTitle` - optional action buttons - page content as children ### **Design constraints** - no hard-coded visual palette outside approved design tokens - no bespoke top-level shell invented for one report page - no inline raw-fetch orchestration in chart components - all page-level analytics behavior must remain compatible with the global platform layout ### --- ### **5. State & Data Handling** ### **5.1 Current frontend data model** The current Reports frontend relies on a small number of predictable patterns: #### **A. Dashboard REST query pattern** Pages load report data from canonical read-only endpoints under: - `/api/reports/smart-vote` - `/api/reports/usage` - `/api/reports/perf` These are frontend-consumed as dashboard datasets with KPI summaries and chart-ready structures. #### **B. Custom builder preview pattern** The custom builder page manages: - local form state - preview configuration state - preview rendering state The builder currently behaves as a **beta preview surface**. Realtime preview can optionally be connected through: - `WS /ws/reports/custom` but the page must still function as a valid frontend experience even when realtime orchestration is not yet fully enabled end-to-end. ### **5.2 Cache expectations** The Reports frontend may cache request results using a client-side query cache or equivalent wrapper behavior. Minimum expectations: - endpoint + params determine cache identity - cache must invalidate on relevant filter changes - dashboard views should avoid unnecessary repeat fetches during short user interactions ### **5.3 State-management expectations** No Redux requirement is imposed for this slice. The current architecture is satisfied by: - local component state - query-hook state - shell/action props - optional stream state for builder preview ### **5.4 Data-orchestration rule** Report components and charts **must not** become orchestration layers for multiple unrelated raw HTTP calls. Aggregation and composition belong in a service layer or report-specific data hook. ### --- ### **6. Current Page Definitions** ### **6.1 `/reports` — ReportsHomePage** Purpose: - act as the landing page for Insights - present an overview of the available report families - expose quick-range or summary context - route users to the deeper dashboards Current UX responsibilities: - display high-level cards / KPI summaries - present quick links to Smart Vote, Usage, and Performance - explain how to use the Reports area - remain readable even before deeper dashboards are opened This page is a **hub**, not a full analytical substitute for the dedicated report routes. --- ### **6.2 `/reports/smart-vote` — SmartVoteDashboard** Purpose: - visualize Smart Vote outcomes, trends, and correlations - support time-range filtering - expose read-only analytical views of voting behavior Expected content: - KPI summary cards - time-series trend visuals - consensus / participation / polarization indicators - page-level filters where applicable - optional export / admin-only advanced actions --- ### **6.3 `/reports/usage` — UsageDashboard** Purpose: - show adoption and platform usage signals such as: - active users - projects - documents / resources - domain-level activity Expected content: - module/domain comparisons - adoption over time - usage summary cards - segment or domain breakdowns - optional export / admin-oriented analytics actions --- ### **6.4 `/reports/perf` — PerfDashboard** Purpose: - expose reliability and service-health analytics for the platform Expected content: - latency KPIs - throughput trends - error-rate series - uptime / SLO summaries - endpoint or service-level breakdowns - operational views relevant to approved audiences --- ### **6.5 `/reports/custom` — CustomReportBuilderPage** Purpose: - provide a configurable report composition interface - let users choose metrics, dimensions, ranges, and options - preview how a custom analytical view would look Current status: - **beta** - currently frontend-led / preview-oriented - valid and implemented as a page - may optionally connect to a realtime builder stream via WebSocket Important note: This page should be documented as a **builder / preview surface**, not as proof that full report persistence, scheduling, or saved-query lifecycle is complete. ### --- ### **7. User Flows** ### **7.1 Overview → dashboard flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant API as Reports API U->>F: Open /reports F-->>U: Render overview / cards / shortcuts U->>F: Open specific dashboard F->>API: GET /api/reports/<endpoint> API-->>F: JSON dataset F-->>U: Render charts + KPI cards ```` --- ### **7.2 Smart Vote dashboard flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant API as Reports API U->>F: Open /reports/smart-vote F->>API: GET /api/reports/smart-vote?range=30d API-->>F: JSON dataset F-->>U: Charts render U->>F: Change filter / range F->>API: GET updated query API-->>F: JSON dataset F-->>U: Dashboard refreshes ``` --- ### **7.3 Custom builder flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant WS as Realtime stream U->>F: Open /reports/custom F-->>U: Render configuration form + preview area U->>F: Set metric / dimensions / range / options F-->>U: Preview updates locally opt Realtime preview enabled F->>WS: Connect /ws/reports/custom WS-->>F: Preview payload / stream updates F-->>U: Enhanced preview updates end ``` ### **Flow rule** Even where realtime is available, the page should degrade gracefully to a non-streaming preview experience. ### --- ### **8. Accessibility, i18n, and UX Quality** The Reports slice must conform to the platform accessibility baseline. Minimum expectations: * charts must not be the only carrier of meaning * labels and summaries must remain readable without visual decoding alone * color usage must satisfy WCAG AA expectations * report pages must remain navigable via keyboard * all user-facing labels should remain localisable under the Reports / Insights namespace Recommended pattern: * pair charts with summaries, legends, tooltips, or compact tabular cues * avoid visually dense dashboards that collapse on smaller screens * prefer progressive disclosure over showing every metric at once ### --- ### **9. Tests & Quality Gate** | Level | Current expectation | | ---------------- | --------------------------------------------------------------------- | | Unit | page helpers, formatting helpers, no-data states, component rendering | | Integration | query/filter changes and API-state transitions | | Type safety | `tsc --noEmit` must pass | | Production build | `pnpm build` must pass | | Runtime QA | manual verification of `/reports*` routes after deployment | | Contract QA | route/API assumptions must remain aligned with backend contract docs | ### **Current quality status** The current frontend implementation has passed: * TypeScript validation * production build validation Runtime verification is still required after deployment or after any API-contract change. ### --- ### **10. Dependencies (frontend layer)** * **Next.js App Router** * **React** * **Ant Design 5** * **`@ant-design/pro-components`** * charting libraries as used by the current page implementation * frontend service wrappers for `/api/reports/*` * optional realtime connection to `/ws/reports/custom` ### **Dependency policy** This document specifies the **contract**, not a mandatory lock-in to one visualization library. Chart-library choices may evolve so long as: * route structure stays consistent * data contracts stay consistent * accessibility expectations stay satisfied * shell/layout patterns remain shared ### --- ### **11. Folder Structure (implementation-oriented)** ```text frontend/ app/ reports/ ReportsPageShell.tsx page.tsx smart-vote/ page.tsx usage/ page.tsx perf/ page.tsx custom/ page.tsx ``` Additional service / hook logic may live outside `app/` in shared frontend modules, but route ownership remains with the structure above. ### --- ## **Document 5.2 – Reporting & Analytics · Backend layer** ### --- ### **1. Scope** Defines the backend service contract for the **read-only Reports / Insights API** used by the frontend dashboards and, where applicable, the custom builder preview flow. This layer is responsible for: * validating query params * enforcing access control * orchestrating analytical queries * caching common read paths * exporting report datasets * returning JSON datasets suitable for the frontend dashboards ### **Service boundary** The Reports backend is conceptually a **read-only analytics service**. It should not own primary OLTP business entities such as Ethikos topics, KeenKonnect projects, or KonnectED resources. It reads and aggregates from analytical or derived sources. ### --- ### **2. Canonical backend endpoints** Canonical backend HTTP paths: * `GET /api/reports/smart-vote` * `GET /api/reports/usage` * `GET /api/reports/perf` Optional / evolving channel: * `WS /ws/reports/custom` Additional export or builder endpoints may be added later, but the frontend contract above is the minimum current slice. ### **Route invariants** * `/api/reports/*` is reserved for the Reports backend service contract. * `/ws/reports/*` is reserved for Reports realtime use. * These prefixes must not be repurposed by another module without a documentation and routing-reference update. ### --- ### **3. Backend responsibilities** The Reports backend must: 1. validate request parameters (range, filters, dimensions, export flags) 2. normalize request defaults 3. authorize access to requested report data 4. query analytical sources or materialized views 5. optionally hydrate labels / dimensions from domain-aware reference data 6. cache repeatable hot queries where useful 7. serialize dashboard-friendly JSON 8. enforce export limits and privacy protections ### **Non-responsibilities** The Reports backend should not become a generic cross-platform write API. Write ownership stays with the module that owns the original business entity. ### --- ### **4. AuthZ and data access** Reports endpoints are **read-only**, but not necessarily public. Expected backend controls include: * role-based permissions * privacy-safe aggregation * restricted export access for larger datasets * exclusion of sensitive or small-cohort datasets where policy requires it Where the analytics source is derived from sensitive user activity, the backend must return only approved aggregated shapes. ### --- ### **5. Caching and query execution** The Reports API may use Redis or equivalent short-lived caching for frequently requested report datasets. Backend cache expectations: * cache key derived from endpoint + params * cache TTL appropriate to report freshness expectations * hot-path queries should avoid repeated analytical DB load where response reuse is safe * cache invalidation policy must remain consistent with the parameter reference and ETL freshness model ### --- ### **6. Export behavior** Exports are permitted only within backend-enforced limits. Expected backend duties: * enforce row-count ceiling * verify user/role authorization for larger exports * stream or stage files safely * ensure exported datasets preserve privacy rules and omit prohibited detail Frontend buttons alone must never be treated as sufficient security. ### --- ### **7. Unit-of-work sequence (Smart Vote report)** ```mermaid sequenceDiagram participant U as User participant API as Reports API participant Cache as Redis participant DB as Analytics DB U->>API: GET /api/reports/smart-vote?range=7d API->>Cache: GET cache key alt cache hit Cache-->>API: dataset else cache miss Cache-->>API: null API->>DB: read analytical view / query DB-->>API: rows API->>Cache: SET cached dataset end API-->>U: 200 JSON ``` ### **Implementation note** Exact internal query objects, serializers, and cache decorators may change, but the service responsibilities above remain stable. ### --- ### **8. Tests & quality gate** | Level | Requirement | | -------------- | ------------------------------------------------------------ | | Unit | request validation, serializer stability, cache-key behavior | | Integration | endpoint query → analytical source → JSON shape | | Contract | stable response shape for frontend consumers | | Perf | protect hot paths with realistic cache-enabled baselines | | Access control | unauthorized access and export-policy tests | ### --- ### **9. Dependencies** * Python 3.12 * Django 4.2 * Django REST Framework * Redis-compatible cache layer * PostgreSQL analytical store * optional WebSocket / Channels layer for custom-builder realtime flows ### --- ## **Document 5.3 – Reporting & Analytics · Database & Storage layer** ### --- ### **1. Scope** Defines the analytical relational objects that power the Reports / Insights slice. This layer covers: * analytical fact tables * dimensions * materialized views / derived datasets * indexes * retention assumptions * privacy and access constraints This storage layer is conceptually separate from OLTP application tables. ### --- ### **2. Analytical model** The Reports slice is based on a **star-schema style** analytical design. #### **Typical dimensions** * `dim_date` * `dim_domain` * `dim_endpoint` * any other approved descriptive dimensions required for reporting #### **Typical facts** * `smart_vote_fact` * `usage_mau_fact` * `api_perf_fact` These support the core frontend dashboards: * Smart Vote * Usage / adoption * API performance ### --- ### **3. Materialized / derived datasets** The frontend dashboards should generally consume data through: * curated analytical queries * materialized views * service-owned derived datasets rather than raw fact-table joins emitted directly from the browser contract. This keeps: * response times predictable * privacy rules enforceable * API shapes stable * report queries maintainable ### --- ### **4. Retention and freshness** Analytical retention and refresh behavior are governed by the Insights parameter reference. At minimum, the Reports storage layer must support: * historical Smart Vote analytics * medium-term usage history * shorter-term API performance data * refreshable derived views for dashboard consumption ### **Freshness model** Some dashboards are naturally near-real-time, while others are refreshed on ETL or materialization cadence. The frontend must not assume all report datasets are realtime unless the backend contract explicitly says so. ### --- ### **5. Privacy and security rules** The analytical storage layer must enforce: * privacy-preserving user identifiers * minimum cohort thresholds where applicable * separation between ETL/service privileges and read-only query roles * auditability of analytical access patterns The Reports DB must not become an unrestricted replica of raw user activity. ### --- ### **6. Access model** A read-only analytical role (or equivalent restricted access model) should be used for report-serving workloads. Principles: * report-serving accounts read dimensions / approved views * raw fact access is restricted where policy requires * export flows remain subject to authorization and auditing ### --- ### **7. Performance expectations** The database layer should support: * hot-path report queries at dashboard-friendly latency * predictable performance on recent time-window lookups * partition-aware retention and maintenance * efficient endpoint/time or domain/time filtering ### --- ### **8. Storage-layer alignment rule** The analytical schema must remain aligned with: * backend report-service contracts (Document 5.2) * frontend page/data expectations (Document 5.1) * parameter and privacy invariants documented elsewhere ### --- ## **Document 5.4 – Reporting & Analytics · DevOps / Infrastructure layer** ### --- ### **1. Objective** Defines the operational and infrastructure expectations for the Reports / Insights slice. This includes: * runtime services * ETL / Airflow support * deployment behavior * environment-variable expectations * observability * backups * alerting * scaling expectations Common platform-wide infrastructure is documented elsewhere; this section covers Reports-specific needs. ### --- ### **2. Runtime components** Typical Reports runtime components include: * `reports-api` * ETL / worker process for analytical refresh tasks * Airflow scheduler / workers for ETL orchestration * migration or initialization job for report-service deployment * Redis cache layer * analytical PostgreSQL store * optional object storage for exports ### **Scaling note** The Reports service should scale independently enough to handle dashboard bursts without forcing scaling policy onto unrelated OLTP services. ### --- ### **3. ETL / Airflow** The Reports slice depends on periodic ETL or refresh jobs for derived analytical datasets. Typical duties include: * ingesting or transforming source data * refreshing materialized analytical views * pruning expired data per retention policy * validating freshness and partition health * supporting export or downstream audit/report operations where required ### **Operational rule** Frontend pages must not assume ETL freshness beyond what the backend contract and job schedule guarantee. ### --- ### **4. Environment variables and config** Reports-specific config belongs in the Insights parameter reference and must remain consistent with deployment values. Typical configuration areas: * analytical DB connection * Redis/cache configuration * export limits * retention or cleanup controls * ETL schedules * stream / WebSocket settings where used * alert thresholds and observability hooks ### --- ### **5. Observability** Minimum operational observability for the Reports slice includes: * structured logs for API requests * metrics for query latency, error rate, and cache behavior * health checks for service readiness * ETL / Airflow job monitoring * alert rules for report-service degradation Recommended focus areas: * high latency on hot report endpoints * repeated cache misses on common dashboards * ETL freshness lag * export failures * WebSocket or preview stream failures where enabled ### --- ### **6. Backup, restore, and disaster readiness** Operational policy must cover: * analytical DB backup schedule * restore drills * retention of backup artifacts * safe handling of staged export files if applicable * treatment of Redis as ephemeral cache unless explicitly stated otherwise ### --- ### **7. CI / deployment quality gate** The Reports slice should pass, at minimum: * service tests * migration safety checks * environment-variable validation where applicable * frontend typecheck/build * deployment health verification * ETL / report-job readiness checks where applicable ### **Frontend gate note** Because the Reports frontend is now implemented, changes affecting `/reports*` should be treated as part of the production quality gate rather than as placeholder documentation-only surfaces. ### --- ### **8. Security and governance** Reports infrastructure must respect: * route invariants * least-privilege access * privacy-safe analytical exposure * auditability of sensitive access * operational separation between ETL privileges and read-only serving privileges ### --- ### **9. Current implementation status note** This Document 5 set should now be interpreted as follows: * **5.1 Frontend** → implemented and build-clean * **5.2 Backend** → canonical report-service contract * **5.3 Database** → canonical analytical storage contract * **5.4 DevOps** → canonical operating model for the slice The frontend section has been updated to reflect the current implemented `/reports*` pages, while the backend, storage, and DevOps sections remain the authoritative contract layers for the broader analytics slice. ### --- ## **End of Document 5 – Reporting & Analytics slice** ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 - Site Navigation Map.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 08da5ac8ab74c81bb3eb990f9c67cc6c321a88640f79803678eb269049c6de37 CONTENT_BYTES: 4714 ================================================================================================ # Konnaxion v14 — Site Navigation Map This list is generated from the current `frontend/app/**/page.tsx` paths in the supplied code snapshot. A route is an interface surface, not an ownership declaration. ## ekoh - `/ekoh/achievements-badges/earned-badges-display` - `/ekoh/dashboard` - `/ekoh/expertise-areas/view-current-expertise` - `/ekoh/overview-analytics/current-ekoh-score` - `/ekoh/voting-influence/current-voting-weight` ## ethikos - `/ethikos/admin/audit` - `/ethikos/admin/demo-importer` - `/ethikos/admin/moderation` - `/ethikos/admin/roles` - `/ethikos/decide/elite` - `/ethikos/decide/methodology` - `/ethikos/decide/public` - `/ethikos/decide/results` - `/ethikos/deliberate/[topic]` - `/ethikos/deliberate/elite` - `/ethikos/deliberate/guidelines` - `/ethikos/impact/feedback` - `/ethikos/impact/outcomes` - `/ethikos/impact/tracker` - `/ethikos/insights` - `/ethikos/learn/changelog` - `/ethikos/learn/glossary` - `/ethikos/learn/guides` - `/ethikos/pulse/health` - `/ethikos/pulse/live` - `/ethikos/pulse/overview` - `/ethikos/pulse/trends` - `/ethikos/trust/badges` - `/ethikos/trust/credentials` - `/ethikos/trust/profile` ## keenkonnect - `/keenkonnect/ai-team-matching/find-teams` - `/keenkonnect/ai-team-matching/match-preferences` - `/keenkonnect/ai-team-matching/my-matches` - `/keenkonnect/dashboard` - `/keenkonnect/knowledge/browse-repository` - `/keenkonnect/knowledge/document-management` - `/keenkonnect/knowledge/search-filter-documents` - `/keenkonnect/knowledge/upload-new-document` - `/keenkonnect/projects/browse-projects` - `/keenkonnect/projects/create-new-project` - `/keenkonnect/projects/my-projects` - `/keenkonnect/projects/project-workspace` - `/keenkonnect/sustainability-impact/submit-impact-reports` - `/keenkonnect/sustainability-impact/sustainability-dashboard` - `/keenkonnect/sustainability-impact/track-project-impact` - `/keenkonnect/user-reputation/account-preferences` - `/keenkonnect/user-reputation/manage-expertise-areas` - `/keenkonnect/user-reputation/view-reputation-ekoh` - `/keenkonnect/workspaces/browse-available-workspaces` - `/keenkonnect/workspaces/launch-new-workspace` - `/keenkonnect/workspaces/my-workspaces` ## konnected - `/konnected/certifications/certification-programs` - `/konnected/certifications/exam-dashboard-results` - `/konnected/certifications/exam-preparation` - `/konnected/certifications/exam-registration` - `/konnected/community-discussions/active-threads` - `/konnected/community-discussions/moderation` - `/konnected/community-discussions/start-new-discussion` - `/konnected/dashboard` - `/konnected/knowledge/contribute` - `/konnected/learning-library/[resourceId]` - `/konnected/learning-library/browse-resources` - `/konnected/learning-library/offline-content` - `/konnected/learning-library/recommended-resources` - `/konnected/learning-library/search-filters` - `/konnected/learning-paths/create-learning-path` - `/konnected/learning-paths/manage-existing-paths` - `/konnected/learning-paths/my-learning-path` - `/konnected/mentorship` - `/konnected/teams-collaboration/activity-planner` - `/konnected/teams-collaboration/my-teams` - `/konnected/teams-collaboration/project-workspaces` - `/konnected/teams-collaboration/team-builder` ## konsensus - `/konsensus/activity-feed` - `/konsensus/admin` - `/konsensus/dashboard` - `/konsensus/leaderboards` - `/konsensus` ## kontrol - `/kontrol/audit-log` - `/kontrol/dashboard` - `/kontrol/konsensus` - `/kontrol/moderation/community` - `/kontrol/moderation/queue` - `/kontrol/roles` - `/kontrol/users/all` ## kreative - `/kreative/collaborative-spaces/find-spaces` - `/kreative/collaborative-spaces/my-spaces` - `/kreative/collaborative-spaces/start-new-space` - `/kreative/community-showcases/featured-projects` - `/kreative/community-showcases/submit-to-showcase` - `/kreative/community-showcases/top-creators` - `/kreative/creative-hub/explore-ideas` - `/kreative/creative-hub/inspiration-gallery` - `/kreative/creative-hub/submit-creative-work` - `/kreative/dashboard` - `/kreative/idea-incubator/collaborate-on-ideas` - `/kreative/idea-incubator/create-new-idea` - `/kreative/idea-incubator/my-ideas` - `/kreative/mentorship` - `/kreative/traditions-archive` ## reports - `/reports/custom` - `/reports` - `/reports/perf` - `/reports/smart-vote` - `/reports/usage` ## root - `/` ## search - `/search` ## teambuilder - `/teambuilder/[sessionId]` - `/teambuilder/create` - `/teambuilder/humans/conflicts` - `/teambuilder/humans/constraints` - `/teambuilder/humans/modes` - `/teambuilder/humans` - `/teambuilder` - `/teambuilder/problems/[problemId]` - `/teambuilder/problems/create` - `/teambuilder/problems` - `/teambuilder/problems/taxonomy` ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Full-Stack Technical Specification.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 9a67097a9f40e31cadaf4392f04e938e09d8740b2b7e3fb543a6dd8545f7a420 CONTENT_BYTES: 15909 ================================================================================================ # Konnaxion Platform Technical Specification v14 ## Updated implementation-aligned edition This document specifies the Konnaxion Platform architecture and components, aligned with the current v14 codebase and the present implementation state. The platform comprises five primary modules — **Kollective intelligence**, **ethiKos**, **keenKonnect**, **KonnectED**, **Kreative** — plus a common core and a cross-module **Insights / Reports** slice. The specification preserves the branded Konnaxion nomenclature while distinguishing clearly between: - **implemented and build-clean functionality** - **current backend canonical models and endpoints** - **planned or target-state capabilities not yet fully realized** The platform currently uses a **Next.js frontend** for the rich product UI, a **Django + DRF backend** for module APIs, **PostgreSQL** as the primary relational store, and **Celery + Redis** for background processing. --- # 1. Common / Core Platform ## 1.1 Frontend (Common) - **Next.js App Router frontend** The main product UI is implemented in Next.js with TypeScript. Module UIs live in the frontend application and share a common shell, page layout pattern, and module-specific page shells. - **Shared shell and layout system** Global navigation, search, user context, notifications, and page framing are shared across modules. Each major module plugs into the global shell rather than acting as a separate top-level app. - **Reusable design system** The implementation uses Ant Design and shared layout primitives to keep page composition consistent. Module pages are built from shared containers, cards, tables, forms, and chart components. - **Unified session and profile context** Authentication, profile identity, and permissions flow through the shared frontend application rather than being duplicated per module. - **Cross-module reporting surface** The analytics slice is implemented as routes under `/reports`, with separate pages for the report hub, custom builder, Smart Vote, Usage, and API performance. ## 1.2 Backend (Common) - **Django modular monolith** The backend is a Django project composed of local apps: - `users` - `kollective_intelligence` - `ethikos` - `keenkonnect` - `konnected` - `kreative` - **REST API with DRF** The frontend consumes JSON APIs exposed through the central DRF router under `/api/...`. - **Canonical API routing** Common examples: - `/api/users/...` - `/api/ethikos/topics/` - `/api/ethikos/stances/` - `/api/ethikos/arguments/` - `/api/ethikos/categories/` (when available) - `/api/keenkonnect/projects/` - `/api/kollective/votes/` - `/api/konnected/resources/` - `/api/kreative/artworks/` - **Compatibility aliases** Ethikos is also exposed through compatibility route families: - `/api/deliberate/...` - `/api/deliberate/elite/...` - **Shared services** Authentication, user profile APIs, notifications, background tasks, and common moderation infrastructure are shared at the core layer. ## 1.3 Database (Common) - **Primary PostgreSQL database** PostgreSQL stores user accounts, module entities, moderation metadata, and shared reference data. - **Unified user model** A custom `users.User` model is used throughout the platform. - **Shared domain references** Common taxonomies, moderation records, notifications, and search-related indices belong to the cross-module core. - **Search support** Global search is backed by shared indexing patterns and/or PostgreSQL search features, allowing discovery across multiple modules. ## 1.4 DevOps (Common) - **Containerized deployment** The platform is structured for Docker-based development and production deployment. - **Background processing** Celery and Redis support asynchronous jobs such as notification delivery, media processing, indexing, and export tasks. - **Monitoring and release pipeline** Health checks, build pipelines, and standard deployment flows are part of the baseline stack. - **Production build validation** The current frontend build completes successfully in production mode, including the Ethikos and Reports routes. --- # 2. Kollective Intelligence ## 2.1 Purpose Kollective intelligence provides the merit-weighted, cross-module decision and reputation substrate of Konnaxion. It includes **EkoH**, **Smart Vote**, and **Konsensus** concepts. ## 2.2 Frontend - Shared dashboards and result surfaces for weighted participation - Reputation and influence visibility - Cross-module aggregation views used by decision-centric modules ## 2.3 Backend - Weighted voting and reputation logic - Expertise and ethics weighting - Vote aggregation and result persistence - Cross-module influence and analytics support ## 2.4 Database Representative tables include: - `UserExpertiseScore` - `UserEthicsScore` - `ExpertiseCategory` - `Vote` - `VoteResult` - `IntegrationMapping` ## 2.5 Notes Kollective intelligence remains the cross-module intelligence substrate rather than an isolated content module. --- # 3. ethiKos ethiKos is the platform’s structured deliberation and consultation module. In the current implementation, the canonical backend core is centered on **topics, stances, arguments, and categories**. More advanced or AI-assisted features remain target-state capabilities rather than the current canonical implementation. ## 3.1 Frontend (Implemented Route Surface) The current Ethikos frontend is implemented under `/ethikos/...` with the following page groups: ### Debate / Decision routes - `/ethikos/decide/elite` - `/ethikos/decide/public` - `/ethikos/decide/results` - `/ethikos/decide/methodology` ### Deliberation routes - `/ethikos/deliberate/elite` - `/ethikos/deliberate/[topic]` - `/ethikos/deliberate/guidelines` ### Trust routes - `/ethikos/trust/profile` - `/ethikos/trust/badges` - `/ethikos/trust/credentials` ### Pulse routes - `/ethikos/pulse/overview` - `/ethikos/pulse/live` - `/ethikos/pulse/health` - `/ethikos/pulse/trends` ### Impact routes - `/ethikos/impact/feedback` - `/ethikos/impact/outcomes` - `/ethikos/impact/tracker` ### Learning and analytics routes - `/ethikos/learn/changelog` - `/ethikos/learn/glossary` - `/ethikos/learn/guides` - `/ethikos/insights` ### Admin routes - `/ethikos/admin/audit` - `/ethikos/admin/moderation` - `/ethikos/admin/roles` ### Frontend implementation notes - The Ethikos frontend uses `EthikosPageShell` and `PageContainer` consistently. - The route structure is deeper and more explicit than the older simplified navigation concept that referred only to `/debate`, `/consult`, or `/reputation`. - Decision, deliberation, pulse, trust, impact, learning, and admin are all first-class implemented page groups. ## 3.2 Backend (Canonical Current Scope) The current canonical Ethikos backend is exposed under: - `/api/ethikos/topics/` - `/api/ethikos/stances/` - `/api/ethikos/arguments/` - `/api/ethikos/categories/` (when registered) Compatibility aliases also exist: - `/api/deliberate/...` - `/api/deliberate/elite/...` ### Current backend semantics - **Topics** are the main debate / consultation objects. - **Stances** store one user’s numeric position on a topic. - **Arguments** store threaded discussion entries and replies. - **Categories** group topics thematically. ### Current participation rule notes The user model already contains Ethikos-specific semantics such as `is_ethikos_elite`, and the backend code documents `can_participate_in_ethikos` rules for staff, klones, and explicitly flagged elite users. ## 3.3 Database (Canonical Current Models) Current canonical Ethikos tables: - `EthikosCategory` - `EthikosTopic` - `EthikosStance` - `EthikosArgument` ### Key semantics - `EthikosTopic` - debate / consultation prompt - status such as `open`, `closed`, `archived` - `EthikosStance` - linked to a topic and a user - integer stance value constrained to **-3 … +3** - `EthikosArgument` - linked to a topic - text body - optional `parent` for threaded replies - optional side / moderation flags depending on serializer configuration ### Important implementation note The following were described in broader concept documents but are **not** part of the current canonical implementation set: - AI clones - comparative analysis logs - debate archives - automated summaries ## 3.4 Functional Frontend Interpretation ### Decide The current Decide surfaces derive decisions and results from Ethikos topics and stances, including closed-topic result views and methodology pages explaining weighted and nuanced participation. ### Deliberate The current Deliberate surfaces render structured topic threads, threaded arguments, and stance capture around the `-3 … +3` model. ### Pulse Pulse acts as the analytics and participation-monitoring layer for Ethikos, with dedicated overview, live, health, and trend pages. ### Trust Trust covers profile credibility, badges, and credentials in the context of debate legitimacy and expertise signaling. ### Impact Impact translates consultations / debates into feedback, outcomes, and tracker views. ### Learn Learn provides static or semi-static educational and explanatory material: - changelog - glossary - guides ### Admin Admin currently includes: - audit - moderation - role management ## 3.5 DevOps / Operational Notes - Ethikos participates in the standard frontend production build and now builds cleanly. - Ethikos frontend pages are part of successful static generation / route preparation in the production build. - Runtime verification is still required for live API-backed behavior even after build success. --- # 4. keenKonnect keenKonnect remains the project collaboration and resource-sharing module. ## 4.1 Frontend It includes project browsing, workspaces, team matching, document/resource access, and sustainability-related project views. ## 4.2 Backend Canonical backend routes include: - `/api/keenkonnect/projects/` - `/api/keenkonnect/resources/` - `/api/keenkonnect/tasks/` - `/api/keenkonnect/messages/` - `/api/keenkonnect/teams/` - `/api/keenkonnect/ratings/` - `/api/keenkonnect/tags/` ## 4.3 Database Representative entities include: - project - project resource - task - message - team membership - rating - tag ## 4.4 DevOps Object storage, collaboration performance, and media handling remain central operational concerns for this module. --- # 5. KonnectED KonnectED is the learning, certification, and mentorship module. ## 5.1 Frontend The frontend includes: - knowledge resources - certification flows - exam / evaluation interfaces - portfolios - mentorship and learning-path experiences ## 5.2 Backend Canonical routes include: - `/api/konnected/resources/` - `/api/konnected/offline-packages/` (optional) - `/api/konnected/certifications/paths/` - `/api/konnected/certifications/evaluations/` - `/api/konnected/certifications/peer-validations/` - `/api/konnected/portfolios/` - `/api/konnected/certifications/exam-attempts/` ## 5.3 Database Representative entities include: - knowledge content - course / path - certification - user progress - user certification - mentorship records ## 5.4 DevOps Offline package generation, content delivery, and scaling for educational content remain important to this module. --- # 6. Kreative Kreative is the arts, archive, collaboration, and showcase module. ## 6.1 Frontend The frontend includes: - dashboards - galleries and showcases - archives - collaborative spaces - mentorship-oriented creative surfaces ## 6.2 Backend Canonical routes include: - `/api/kreative/artworks/` - `/api/kreative/galleries/` - `/api/kreative/collab-sessions/` - related supportive APIs depending on feature group ## 6.3 Database Representative entities include: - artwork - gallery - collaboration session - archive / tradition entry - comments / likes / tags where implemented ## 6.4 DevOps Media storage, CDN delivery, and optional real-time collaboration are the major operational concerns. --- # 7. Insights / Reports (Cross-Module Analytics Slice) Insights / Reports is currently implemented as a separate route family under `/reports` and should be treated as a cross-module analytics slice rather than an informal add-on. ## 7.1 Frontend (Implemented Routes) Current implemented report routes: - `/reports` - `/reports/custom` - `/reports/smart-vote` - `/reports/usage` - `/reports/perf` ### Current page roles - `/reports` Hub / overview page for the analytics slice - `/reports/custom` Custom report builder UI - `/reports/smart-vote` Smart Vote dashboard - `/reports/usage` Usage and adoption dashboard - `/reports/perf` API / platform performance dashboard ## 7.2 Frontend implementation notes - Reports pages use a dedicated `ReportsPageShell` - The route family is now production-build clean - The custom report builder and report dashboards are part of the current implemented frontend surface ## 7.3 Backend The current frontend expects report-oriented APIs of the form: - `GET /reports/smart-vote` - `GET /reports/usage` - `GET /reports/perf` The reports frontend also includes hook-based analytics access patterns and a custom-report flow. ## 7.4 Database / Storage The reports slice is documentation-defined as a distinct reporting and analytics layer with its own storage, retention, and aggregation rules. The implementation should continue to distinguish: - frontend reporting UI - read-only analytics API - reporting database / storage layer - orchestration / monitoring layer ## 7.5 DevOps This slice should be operated as a reporting-focused subsystem with clear observability, refresh cadence, and retention behavior. UI readiness does not by itself guarantee analytics pipeline completeness; runtime validation remains necessary. --- # 8. Current Implementation Status Summary ## 8.1 Frontend status The frontend is currently in a strong implementation state for: - Ethikos route surfaces - Reports / Insights route surfaces - shared shell-based module composition - production build integrity ## 8.2 Backend status The backend is canonical and stable at the core model / API level for several modules, but implementation breadth still varies by module. In Ethikos specifically, the canonical core is narrower than the total frontend surface. ## 8.3 Documentation rule From this version onward, architecture documentation should distinguish explicitly between: - **canonical implemented models and endpoints** - **implemented frontend route surfaces** - **planned / target-state features not yet in the canonical codebase** This distinction is especially important for: - ethiKos - Insights / Reports - any target-state AI or summary features --- # 9. Authoritative Route / API Alignment Notes ## 9.1 Ethikos Use: - `/ethikos/...` for frontend routes - `/api/ethikos/...` for canonical backend routes - `/api/deliberate/...` and `/api/deliberate/elite/...` only as compatibility aliases Do not document Ethikos as if only `/debate` and `/consult` existed when the implemented UI is now a larger route family. ## 9.2 Reports Use: - `/reports` - `/reports/custom` - `/reports/smart-vote` - `/reports/usage` - `/reports/perf` These are real implemented routes and should be reflected consistently in navigation, UI specs, and technical references. --- # 10. Conclusion Konnaxion v14 is now best understood as: - a shared Next.js + Django modular platform - with canonical backend entities and route contracts - with a richer implemented frontend route surface in Ethikos - and with a now-clean, implemented Reports / Insights frontend slice This specification should be treated as the implementation-aligned baseline until a later revision expands the canonical backend scope or formalizes additional target-state features into production code. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Functional Code-Name Inventory (Services & Hooks).md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: bf59813f623f7172292f2ff19988830446247a975d9dc5063a6a5de33cdb0fa8 CONTENT_BYTES: 14248 ================================================================================================ # **Inventory of platform-specific functionalities** > **Update note** > > This inventory now distinguishes between: > > - **Current implemented / surfaced functionality** — reflected in the current frontend route structure and UI specs > - **Target-state / roadmap functionality** — still valid as product intent, but not necessarily represented as a fully implemented surface today | Module | Sub-module | Display Name → Code Name | Purpose / Behaviour | Status / Current Surface | | ----- | ----- | ----- | ----- | ----- | | **Kollective Intelligence** | **EkoH** | Multidimensional Scoring → `multidimensional_scoring` | Compute per-user/content scores along axes (quality, frequency, relevance, expertise). | Target-state / canonical capability | | | | Criteria Customization → `configuration_weights` | Admin/community adjust weighting parameters for each scoring axis. | Target-state / canonical capability | | | | Automatic Contextual Analysis → `contextual_analysis` | AI adjusts sub-scores in real time based on topic, history, complexity. | Target-state / canonical capability | | | | Dynamic Privacy → `privacy_settings` | Apply anonymity / pseudonym modes while still displaying merit scores. | Target-state / canonical capability | | | | History & Traceability → `score_history` | Persist every score recalculation & configuration change for audit. | Target-state / canonical capability | | | | Interactive Visualizations → `score_visualization` | Serve aggregated data for live dashboards, skill-maps, matrices. | Target-state / canonical capability | | | | Expertise Classification by Field → `expertise_field_classification` | Bind each sub-score to a formal domain (Agronomy, HR, etc.). | Target-state / canonical capability | | | **Smart Vote** | Dynamic Weighted Voting → `dynamic_weighted_vote` | Re-weights every vote in real time using the voter’s EkoH score. | Target-state / canonical capability | | | | Flexible Voting Modalities → `voting_modalities` | Supports approval, ranking, rating, preferential ballots. | Target-state / canonical capability | | | | Emerging Expert Detection → `emerging_expert_detection` | Flags users whose EkoH score is rising sharply. | Target-state / canonical capability | | | | Transparency of Results → `vote_transparency` | Publishes raw + weighted values and context (no private data). | Target-state / canonical capability | | | | Advanced Result Visualizations → `vote_result_visualization` | Generates histograms, network graphs, interactive maps of outcomes. | Target-state / canonical capability | | | | Cross-Module Integration → `cross_module_vote_integration` | Makes Smart Vote accessible from all modules (KonnectED, et al.). | Target-state / canonical capability | | **ethiKos** | **Deliberate** | Elite Agora / Expert Deliberation → `elite_deliberation` | Expert-oriented debate listing and entry into topic threads. | **Current implemented surface** (`/ethikos/deliberate/elite`) | | | | Topic Thread / Debate Thread → `debate_thread` | Topic detail, threaded arguments, and stance participation on the canonical −3…+3 scale. | **Current implemented surface** (`/ethikos/deliberate/[topic]`) | | | | Participation Guidelines → `deliberation_guidelines` | Explain rules, norms, and expected debate quality. | **Current implemented surface** (`/ethikos/deliberate/guidelines`) | | | **Decide** | Public Consultations → `public_consultation` | Open public consultations with participation and stance capture. | **Current implemented surface** (`/ethikos/decide/public`) | | | | Elite Decisions → `elite_decision_flow` | Expert / elite decision participation surface. | **Current implemented surface** (`/ethikos/decide/elite`) | | | | Results Archive → `decision_results_archive` | Review aggregated decision outcomes and historical result views. | **Current implemented surface** (`/ethikos/decide/results`) | | | | Methodology → `decision_methodology` | Explain the scoring / consultation / weighting logic used in decide flows. | **Current implemented surface** (`/ethikos/decide/methodology`) | | | **Trust** | Trust Profile → `trust_profile` | Show reputation, trust, and debate-relevant profile indicators. | **Current implemented surface** (`/ethikos/trust/profile`) | | | | Badges → `trust_badges` | Display recognitions / trust markers tied to user standing. | **Current implemented surface** (`/ethikos/trust/badges`) | | | | Credentials → `credential_management` | Upload and manage credentials that support expertise visibility in debates. | **Current implemented surface** (`/ethikos/trust/credentials`) | | | **Pulse** | Health Dashboard → `debate_health_dashboard` | Show quality / participation / health signals for debate activity. | **Current implemented surface** (`/ethikos/pulse/health`) | | | | Live Feed → `debate_live_feed` | Near-real-time participation/activity feed for debate flows. | **Current implemented surface** (`/ethikos/pulse/live`) | | | | Overview Analytics → `opinion_overview` | Summarize participation and debate metrics. | **Current implemented surface** (`/ethikos/pulse/overview`) | | | | Trends Analytics → `opinion_trends` | Show time-based participation / sentiment / activity trends. | **Current implemented surface** (`/ethikos/pulse/trends`) | | | **Impact** | Feedback Loop → `feedback_loop` | Capture structured user feedback on Ethikos debates / outcomes. | **Current implemented surface** (`/ethikos/impact/feedback`) | | | | Outcomes → `impact_outcomes` | Summarize implementation / result KPIs flowing from debates and decisions. | **Current implemented surface** (`/ethikos/impact/outcomes`) | | | | Tracker → `impact_tracking` | Track implementation / follow-up state for debate-linked decisions. | **Current implemented surface** (`/ethikos/impact/tracker`) | | | **Learn** | Changelog → `ethikos_changelog` | Explain recent changes to Ethikos rules, structure, or experience. | **Current implemented surface** (`/ethikos/learn/changelog`) | | | | Glossary → `ethikos_glossary` | Define concepts, categories, and debate vocabulary. | **Current implemented surface** (`/ethikos/learn/glossary`) | | | | Guides → `ethikos_guides` | Practical guidance for using deliberation, decision, and impact flows. | **Current implemented surface** (`/ethikos/learn/guides`) | | | **Admin** | Audit Log → `ethikos_audit_log` | Review administrative actions and operational traceability. | **Current implemented surface** (`/ethikos/admin/audit`) | | | | Moderation → `ethikos_moderation` | Review reports and moderate debate content. | **Current implemented surface** (`/ethikos/admin/moderation`) | | | | Roles → `ethikos_role_admin` | Manage Ethikos-specific administrative access toggles. | **Current implemented surface** (`/ethikos/admin/roles`) | | | **Insights** | Opinion Analytics → `opinion_analytics` | Cross-cutting analytics across debates, participation, outcomes, and live metrics. | **Current implemented surface** (`/ethikos/insights`) | | | **Roadmap / Target-state** | AI Clones → `ai_clone_management` | Spawn or retire AI agents emulating experts for continuity. | **Target-state / roadmap capability** | | | | Comparative Analysis → `comparative_argument_analysis` | AI compares arguments to surface convergences/divergences. | **Target-state / roadmap capability** | | | | Public Archiving → `public_debate_archive` | Stores immutable snapshots of every debate for transparency. | **Target-state / roadmap capability** | | | | Automated Summaries → `automated_debate_summary` | Generates concise, structured digests of debate outcomes. | **Target-state / roadmap capability** | | **Reporting & Analytics** | **Insights / Reports** | Insights Home → `insights_home` | Card hub for global analytics entry points. | **Current documented + implemented surface** (`/reports`) | | | | Smart Vote Dashboard → `smart_vote_dashboard` | Voting trends, correlations, and Smart Vote analytics. | **Current documented + implemented surface** (`/reports/smart-vote`) | | | | Usage Dashboard → `usage_dashboard` | MAU / projects / documents / activity views. | **Current documented + implemented surface** (`/reports/usage`) | | | | Performance Dashboard → `performance_dashboard` | API latency, error-rate, and SLO monitoring views. | **Current documented + implemented surface** (`/reports/perf`) | | | | Custom Report Builder → `custom_report_builder` | Compose custom report views from metrics, dimensions, filters, and layout choices. | **Current documented + implemented surface** (`/reports/custom`) | | **keenKonnect** | **Konstruct** | Virtual Collaboration Spaces → `collaboration_space` | Dedicated project rooms with membership & roles. | Target-state / canonical capability | | | | Project Management Tools → `project_task_management` | Kanban / tasks / milestones inside each space. | Target-state / canonical capability | | | | Real-Time Editing → `real_time_document_editing` | Synchronous co-editing with conflict resolution. | Target-state / canonical capability | | | | Integrated Chat & Video → `integrated_communication` | In-socket messaging and video conferencing per space. | Target-state / canonical capability | | | | AI Collaborative Analysis → `ai_collaboration_analysis` | Summaries & action suggestions generated live during work. | Target-state / canonical capability | | | **Stockage** | Secure Repository → `secure_document_storage` | Encrypted file hosting with role-based access. | Target-state / canonical capability | | | | Automatic Versioning → `document_versioning` | Stores every file revision, enables rollback. | Target-state / canonical capability | | | | Intelligent Indexing → `intelligent_indexing` | Auto-tag & keyword extraction for fast search. | Target-state / canonical capability | | | | Real-Time Sync → `real_time_sync` | Pushes file updates instantly to all collaborators. | Target-state / canonical capability | | | | Fine Grained Permissions → `granular_permissions` | Read/write/admin rules per user per document. | Target-state / canonical capability | | **KonnectED** | **CertifiKation** | Certification Paths → `certification_path_management` | Define modular learning paths linked to competencies. | Target-state / canonical capability | | | | Automated Evaluation → `automated_evaluation` | AI/rule-based tests & auto-grading. | Target-state / canonical capability | | | | Peer Validation → `peer_validation` | Qualified peers approve or reject skill evidence. | Target-state / canonical capability | | | | Skills Portfolio → `skills_portfolio` | Personal showcase of validated competencies & artifacts. | Target-state / canonical capability | | | | Interoperability (LMS) → `certification_interoperability` | Map/import/export certifications with external systems. | Target-state / canonical capability | | | **Knowledge** | Collaborative Library → `library_resource_management` | CRUD and classify shared learning resources. | Target-state / canonical capability | | | | Personalized Recommendations → `personalized_recommendation` | ML recommends relevant resources per learner profile. | Target-state / canonical capability | | | | Co-Creation Tools → `content_co_creation` | Real-time authoring/versioning of lessons & media. | Target-state / canonical capability | | | | Thematic Forums → `thematic_forum` | Subject-based discussion boards with moderation. | Target-state / canonical capability | | | | Learning Progress Tracking → `learning_progress_tracking` | Dashboards showing completion %, strengths, goals. | Target-state / canonical capability | | **Kreative** | **Konservation** | Digital Archives → `digital_archive_management` | Long-term storage of digitized artworks / media. | Target-state / canonical capability | | | | Virtual Exhibitions → `virtual_exhibition` | Interactive online galleries & VR rooms. | Target-state / canonical capability | | | | Documentation Base → `archive_documentation` | Store bios, provenance, supplemental docs. | Target-state / canonical capability | | | | AI Enriched Catalogue → `ai_enriched_catalogue` | Auto-classification & metadata generation for art. | Target-state / canonical capability | | | | Cultural Partners Integration → `cultural_partner_integration` | Sync external museum/heritage collections. | Target-state / canonical capability | | | **Kontact** | Professional Profiles → `professional_profile` | Rich artist/diffuser profiles (bio, portfolio, skills). | Target-state / canonical capability | | | | Intelligent Matching → `intelligent_matching` | Recommends contacts/collaborations via skills & style. | Target-state / canonical capability | | | | Collaboration Workspaces → `collaboration_workspace` | Shared project rooms (specific to networking context). | Target-state / canonical capability | | | | Opportunities Board → `opportunity_announcement` | Post & search residencies, exhibitions, calls, jobs. | Target-state / canonical capability | | | | Reviews & Endorsements → `partner_recommendation` | Rate & endorse partners after collaborations. | Target-state / canonical capability | --- ## **How to Use These Code Names** - **Backend (Django)** — code names map to services, serializers, viewsets, model workflows, or background jobs. - **Frontend (Next.js / React)** — code names map to page surfaces, hooks, dashboards, or interaction flows. - **Documentation / roadmap tracking** — treat the **Status / Current Surface** column as the source of truth for whether a capability is already surfaced in the current app or still belongs to target-state planning. ## **Status Semantics** - **Current implemented surface** — visible in the present route structure and frontend module surfaces. - **Current documented + implemented surface** — explicitly present both in code and in the current UI spec. - **Target-state / roadmap capability** — valid architectural/product intent, but not treated as a fully verified surfaced feature in the current implementation. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Global Parameter Reference.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 5e3fb000bd1692b5a7b587ba207ae42f890df2b2ec9d598aa4b91ebc4621d9a9 CONTENT_BYTES: 8119 ================================================================================================ [0  Global / Core (shared by all apps)](#0  global-/-core-\(shared-by-all-apps\)) [1  Kollective Intelligence](#1  kollective intelligence) [1.1 EkoH (engine)](#1.1 ekoh \(engine\)) [1.2 Smart Vote (engine)](#1.2 smart vote \(engine\)) [2  ethiKos](#2  ethikos) [3  keenKonnect](#3  keenkonnect) [4  KonnectED](#4  konnected) [5  Kreative](#5  kreative) [6  Navigation & Route Invariants](#6  navigation-&-route-invariants) [7  Environment‑variable Matrix (cookiecutter‑compatible)](#7  environment‑variable-matrix-\(cookiecutter‑compatible\)) [How this document will be maintained](#how-this-document-will-be-maintained) **Konnaxion Platform – Definitive Parameter Reference (v14‑stable)** *All TBD values are now fixed; names follow Cookiecutter‑Django conventions (UPPER\_SNAKE for `settings.py`, `DJANGO_…`/`APP_…` for `.envs` files, `choices=` enums in models). Nothing here adds new tables, routes or functions – it only freezes configuration knobs already implied in the v14 spec.* --- ## **0  Global / Core (shared by all apps)** {#0  global-/-core-(shared-by-all-apps)} | Parameter | Location | Final value | Rationale | | ----- | ----- | ----- | ----- | | `SEARCH_BACKEND` | `settings.BASE` | `"postgres"` | Choose PostgreSQL `tsvector`‑based full‑text search as the default; ElasticSearch can be added later if needed | | `CHANNEL_LAYERS["default"]["BACKEND"]` | `settings.local` | `"channels_redis.core.RedisChannelLayer"` | Re‑uses the Redis container already present in the Cookiecutter stack | | `DEFAULT_FROM_EMAIL` | `.envs/.local/.django` | `noreply@konnaxion.local` | Aligns with cookiecutter pattern | | `MEDIA_ROOT` | `settings.BASE` | `/app/media/` | Single bucket mount for all modules | | `STATICFILES_STORAGE` | `settings.production` | `"whitenoise.storage.CompressedManifestStaticFilesStorage"` | Matches cookiecutter production preset | | `LANGUAGES` | `settings.BASE` | `en`, `fr`, `es`, `ar` | Four‑language baseline for i18n | | `TIME_ZONE` | `settings.BASE` | `"UTC"` | Keeps server‑side consistency (users set own TZ) | --- ## **1  Kollective Intelligence** {#1  kollective intelligence} ### **1.1 EkoH (engine)** {#1.1 ekoh (engine)} | Parameter | Model / Setting | Type / Range | Default | | ----- | ----- | ----- | ----- | | `raw_weight_quality` | `ScoreConfiguration` | `Decimal(4,3)` | **1.000** | | `raw_weight_expertise` | `ScoreConfiguration` | `Decimal(4,3)` | **1.500** | | `raw_weight_frequency` | `ScoreConfiguration` | `Decimal(4,3)` | **0.750** | | `ethical_multiplier_floor` | `settings.EKOH` | float 0‑1 | **0.20** | | `ethical_multiplier_cap` | `settings.EKOH` | float 1‑2 | **1.50** | | `EXPERTISE_DOMAIN_CHOICES` | `ExpertiseCategory` | enum of 26 ISO‑based domains | frozen list in fixtures | These weights are the initial coefficients for the **multidimensional\_scoring** service and correspond 1‑for‑1 with “quality, frequency, relevance, expertise” axes defined in the functionality inventory . ### **1.2 Smart Vote (engine)** {#1.2 smart vote (engine)} | Parameter | Setting | Value / Enum | | ----- | ----- | ----- | | `VOTE_MODALITY_CHOICES` | `VoteModality` | `"approval"`, `"ranking"`, `"rating"`, `"preferential"` | | `EMERGING_EXPERT_THRESHOLD` | `settings.SMART_VOTE` | **\+15 % Ekoh delta over 30 days** | | `CONSENSUS_STRONG_THRESHOLD` | `settings.SMART_VOTE` | **≥ 75 % weighted agreement** | --- ## **2  ethiKos** {#2  ethikos} | Parameter | Location | Final value | | ----- | ----- | ----- | | **Stance scale mapping** | `EthikosStance.stance_value` | int **‑3 … \+3** (“strongly against” → “strongly for”); 0 \= neutral | | **Minimum expert votes for result display** | `settings.ETHIKOS` | **12 distinct experts** (Ekoh \> 75th percentile in topic domain) | | **Moderation auto‑hide threshold** | `DebateArgument.is_hidden` flag | **3 independent reports** | | **AI clone training batch size** | `.envs/.local/.django` → `ETHIKOS_AI_BATCH` | **128** | These close every “TBD” noted in the ethiKos spec (stance granularity, expert quorum, moderation trigger) . --- ## **3  keenKonnect** {#3  keenkonnect} | Parameter | Location | Final value | | ----- | ----- | ----- | | `MAX_BLUEPRINT_UPLOAD_MB` | `settings.STORAGE` | **150 MB** | | `ALLOWED_BLUEPRINT_TYPES` | constant in `ProjectResource` | `[".pdf", ".png", ".jpg", ".glb", ".gltf", ".stl"]` | | `COLLAB_SPACE_MEMBER_CAP` | `CollaborationSpace` | **40** | | `AI_SUGGESTION_TOP_N` | `settings.KEENKONNECT` | **8** user suggestions per request | | `VIDEO_SESSION_PROVIDER` | env var `KC_VIDEO_PROVIDER` | `"livekit"` (self‑hosted) | All map directly to features in the technical spec and functionalities table . --- ## **4  KonnectED** {#4  konnected} | Parameter | Location | Final value | | ----- | ----- | ----- | | `OFFLINE_PACKAGE_CRON` | Celery Beat | `0 3 * * SUN` (every Sunday at 03:00 UTC) | | `CERT_PASS_PERCENT` | `CertificationPath` | **80 %** | | `QUIZ_RETRY_COOLDOWN_MIN` | `settings.KONNECTED` | **30** minutes | | `CONTENT_TYPES_ALLOWED` | `KnowledgeResource.type` enum | `"article"`, `"video"`, `"lesson"`, `"quiz"`, `"dataset"` | | `MAX_CONTRIBUTION_DRAFTS` | per user | **10** pending submissions | --- ## **5  Kreative** {#5  kreative} | Parameter | Location | Final value | | ----- | ----- | ----- | | `ARTWORK_MAX_IMAGE_MB` | `settings.KREATIVE` | **50 MB** | | `ARTWORK_RESOLUTIONS` | image processing task | `[256, 1024, 2048]` px longest side | | `VIRTUAL_GALLERY_CAPACITY` | `VirtualExhibition` | **24 artworks / room** | | `COLLAB_CANVAS_MAX_USERS` | `CollabSession` | **6** simultaneous editors | | `NSFW_FLAG_REQUIRED` | upload form | boolean, default `False` | --- ## **6  Navigation & Route Invariants** {#6  navigation-&-route-invariants} The **24 routes** enumerated in the Navigation Map are locked; any new path must be added via RFC process. Route‑to‑app ownership table: | Route prefix | Owning Django app | | ----- | ----- | | `/konsensus`, `/ekoh` | `kollective_intelligence` | | `/debate`, `/consult`, `/ethikos` | `ethikos` | | `/projects`, `/impact` | `keenkonnect` | | `/learn`, `/course`, `/certs` | `konnected` | | `/kreative`, `/art`, `/archive`, `/connect`, `/profile` | `kreative` | | `/chat`, `/team`, `/admin` | core / `django.contrib.admin` | No additional frontend pages may claim these prefixes without amending this reference . --- ## **7  Environment‑variable Matrix (cookiecutter‑compatible)** {#7  environment‑variable-matrix-(cookiecutter‑compatible)} | Env var | Used by | Default (.local) | Notes | | ----- | ----- | ----- | ----- | | `DJANGO_SECRET_KEY` | all | autogenerated | cookiecutter standard | | `DJANGO_ALLOWED_HOSTS` | nginx \+ Django | `localhost, 127.0.0.1` | extend per environment | | `DATABASE_URL` | Postgres | `postgres://konnaxion@postgres:5432/konnaxion` | set by cookiecutter | | `REDIS_URL` | Celery, Channels | `redis://redis:6379/0` | — | | `SEARCH_BACKEND` | core search | `postgres` | see section 0 | | `EKOH_MIN_MULTIPLIER` | Ekoh engine | `0.20` | editable in prod | | `EKOH_MAX_MULTIPLIER` | Ekoh engine | `1.50` | — | | `KC_VIDEO_PROVIDER` | keenKonnect | `livekit` | adjust if using Jitsi | | `OFFLINE_PACKAGE_CRON` | KonnectED | `0 3 * * SUN` | must stay UTC | Add these to `.envs/.local/.django`; production overrides live in `.envs/.production/.django`. --- ### **How this document will be maintained** {#how-this-document-will-be-maintained} * **Immutable commit rule:** Once merged into `docs/parameter_reference.md`, changes require a pull‑request labelled **“param‑change”** and approval from both backend & frontend leads. * **CI guard:** A lint step asserts that `settings.*` and model enums keep the values defined here. * **Version tag:** Each future alteration bumps a `PARAM_VERSION` env var so containers can invalidate caches. --- ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Insights Module Config Parameters.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c3719b824a95ebe8edfdaad6cffbf1bfdb9f629462fd6a232aabc4721b43f474 CONTENT_BYTES: 11014 ================================================================================================ # **Insights Module – Parameter Reference (Konnaxion v14)** ## **Configuration Parameters and Invariants** * **Analytical data retention:** All fact tables in the Insights (Reporting & Analytics) module use time-partitioning with fixed retention periods. For example, **Smart Vote** vote history is kept for **5 years**, **Usage** (MAU/projects/docs) for **10 years**, and **API performance** metrics for **2 years** – older partitions are dropped on a rolling basis. Materialized summary views always query only recent data (e.g. last 24 h or 30 d) and are refreshed rather than retaining historical states. * **Backup policy:** The analytics PostgreSQL database ( “Reports” DB) is backed up with **nightly full dumps** plus **30‑minute incremental snapshots**, retained for **14 days**. (The Airflow metadata DB is included in these backups.) DAG definitions (code) are versioned in Git, and the **Redis** cache is **not** backed up (ephemeral usage). Quarterly restore drills are performed to ensure disaster-recovery readiness. * **Cache TTL:** The Insights module leverages the same Redis cache service as the core platform for temporary analytics data. Cached query results (e.g. for dashboards) expire after **12 hours**, and a daily cleanup job purges any stale keys older than this TTL. This ensures the analytics caches stay fresh without manual intervention. * **Export size limit:** Data exports (CSV downloads) are capped at **100,000 rows** per request. This limit is enforced by the `EXPORT_MAX_ROWS` configuration and CI tests (an **export-guard** step fails any build if an export would exceed this). Additionally, only **administrators** can initiate large exports from the Insights API, preventing regular users from pulling excessive data. * **Privacy protections:** All user identifiers in the analytics database are stored as **SHA-256 hashes** (with a secret salt) instead of raw IDs. This one-way hashing ensures that personal data in analytics cannot be reverse-engineered. The ETL pipeline also **excludes small cohorts** – any aggregated result representing fewer than 10 users is dropped – to enforce *k*\-anonymity and prevent re-identification of individuals in low-count data. * **Access control & auditing:** A dedicated database role (`reports_reader`) is used for read-only access to Insights data. This role is restricted to querying **dimension tables and materialized views only**; direct selects on raw fact tables require the ETL service’s privileged account. All API requests to the Insights service are logged to a central audit index (shipped via Fluent Bit to OpenSearch) with a **6 month retention** for compliance. These measures ensure sensitive analytical data is tightly governed and auditable. * **Routing invariants:** The `/reports` URL namespace is reserved exclusively for the Insights module’s UI and API endpoints. Frontend routes such as `/reports/smart-vote`, `/reports/usage`, `/reports/perf` etc., map to the Insights dashboards, and the backend serves corresponding `/api/reports/*` endpoints. This prefix has been added to the platform’s navigation map invariants, so no other module may use `/reports` (or its WebSocket channel `/ws/reports/*`) without an official change to the reference. ## **ETL & Airflow Job Configuration** The Insights module includes a suite of **Airflow DAGs** that perform periodic extract-transform-load (ETL) tasks and maintenance. Key jobs and their schedules are summarized below (in an `etl_config.yml` style format): etl\_dags: \- id: etl\_smart\_vote schedule: "\*/10 \* \* \* \*" \# every 10 minutes task: "Load new votes from OLTP into smart\_vote\_fact" \- id: etl\_usage schedule: "0 \* \* \* \*" \# hourly task: "Update usage\_mau\_fact (MAU, projects, docs counts)" \- id: etl\_perf schedule: "\*/15 \* \* \* \*" \# every 15 minutes task: "Ingest Prometheus API metrics into api\_perf\_fact" \- id: refresh\_mat\_views schedule: "5 \* \* \* \*" \# every hour at :05 task: "REFRESH all analytics materialized views (vw\_\*)" \- id: cleanup\_cache schedule: "@hourly" \# every hour task: "Purge Redis analytics cache keys older than 12h" \- id: purge\_old\_partitions schedule: "0 4 \* \* 0" \# every Sunday 04:00 UTC task: "Drop any fact table partitions past retention window" Each DAG uses Vault-managed connections for the analytics Postgres and Redis (no credentials are hard-coded). The schedules and logic align with the data retention policy – for instance, `purge_old_partitions` runs weekly to cull expired partitions. The ETL jobs ensure that analytical facts are kept up-to-date in near real-time (e.g. new votes reflected in metrics within 10 minutes) and that supporting structures (materialized views, caches) are maintained automatically. ## **Environment Variables and Secrets** Several new environment variables (and mounted secrets) are introduced for the Insights module. These are defined following the Cookiecutter Django conventions and are split between **in-code `.env` settings**, **Kubernetes ConfigMaps**, and **Vault secrets** as appropriate: | Environment Variable | Used By | Default (Dev) / Example | Source & Notes | | ----- | ----- | ----- | ----- | | **`REPORTS_DB_URL`** | Reports API & ETL | *none* (set per environment) | Vault secret `analytics/pg/url` (PostgreSQL connection string for the analytics DB, using a read-only user). In local/dev, this can point to the same Postgres with a separate schema or a dedicated analytics DB. | | **`REDIS_URL`** | Reports API & ETL | `redis://redis:6379/0` | Vault secret `common/redis/url`. Reuses the platform’s existing Redis instance for caching (TTL as above). No new Redis env var is needed if one is already configured globally. | | **`AIRFLOW__CORE__FERNET_KEY`** | Airflow scheduler | *none* (generated secret) | Vault secret `analytics/airflow/fernet`. Used to encrypt Airflow connection creds. Set by ops (not stored in code). | | **`PROMETHEUS_BASE_URL`** | ETL tasks | e.g. `http://prometheus:9090` | ConfigMap `analytics-settings`. Base URL for Prometheus API (provides metrics to the `etl_perf` DAG). In production, points to the cluster’s Prom service; in dev, can be left blank or pointed to a test endpoint. | | **`EXPORT_MAX_ROWS`** | Reports API & CI | `100000` | ConfigMap `analytics-settings`. Max rows allowed in any export query. The backend reads this to enforce the CSV limit (and tests use it to simulate large export scenarios). | All the above should be added to the appropriate environment config files or secret stores. For example, in local development they can reside in `.env.local` (or Django `.envs/.local/.django`), while in production the sensitive values come from **Vault** (for secrets) and a read-only **ConfigMap** (for non-sensitive settings). This separation ensures that default values are provided for development/CI, and that production deployments have the correct secure endpoints and credentials injected. No new global environment variables were introduced outside of the Insights context (existing ones like `REDIS_URL` are reused), avoiding duplication of already-declared values. ## **Deployment, Scaling and Monitoring** The Insights module is deployed as a set of dedicated services with resource limits aligned to its workload. It consists of a **reports API service**, a background **ETL worker service**, and an **Airflow** instance for orchestration (plus ancillary jobs). Key resource allocations and scaling parameters are as follows: * **Reports API:** Deployed as a container (image `ghcr.io/konnaxion/reports-api`) with **3 replicas** by default. An HPA (Horizontal Pod Autoscaler) is set between **2** and **6** pods based on load. Each pod requests **300 mCPU** (0.3 CPU) and can burst up to **600 mCPU**, with **384 MiB** base RAM (limit **768 MiB**). The HPA triggers scale-up when average CPU \> **60%** or when request latency P95 exceeds **400 ms** (as reported by Prometheus), ensuring the API meets its performance SLOs. * **ETL Worker:** Deployed as `reports-etl-worker` (image `ghcr.io/konnaxion/reports-etl`) with **2 pods** (fixed) for parallel data processing. Each worker has a **400 mCPU** baseline (up to 800 mCPU) and **512 MiB** of memory (up to 1 GiB) allocated. Auto-scaling is not enabled for ETL workers (scaling is manual or via future tuning), since ETL load is relatively predictable and contained. * **Airflow Scheduler & Workers:** The Airflow component (image `apache/airflow:2.9-python3.12`) runs with **1 scheduler pod** and **2 worker pods**. Each is given roughly **0.25 CPU** (250 mCPU, up to 500 mCPU) and **512 MiB** RAM (up to 1 GiB), sufficient for orchestrating the periodic jobs. The Airflow service ensures DAGs (as listed above) execute on schedule; its database (metadata DB) is a lightweight Postgres (which is included in the backup plan). * **Database migration job:** On each deployment, a one-time migration Job (`reports-db-migrate`) runs to apply any analytics DB schema changes. It uses the same image as the Reports API and is given a small resource slice (approx **0.25 CPU** and **256 MiB** RAM), since migrations are usually quick. This job ensures the analytics schema (tables, partitions, views) is up-to-date before the app/ETL start running. * **Monitoring & alerts:** Comprehensive metrics and alerting are in place for the Insights module. Custom **Prometheus** metrics track API performance (latency, error rates), ETL outcomes, and cache usage, feeding both the HPA and alerting system. For example, an alert triggers if the **95th percentile** API latency goes over **0.4 s** sustained or if the error rate exceeds **2%**. Likewise, any ETL DAG failure will raise a critical alert, and a warning is issued if a materialized view refresh exceeds **60 s**. These thresholds align with the module’s SLOs and ensure prompt attention to issues. Dashboards (e.g. *reports-api* and *reports-etl* Grafana boards) visualize throughput, cache hit ratios, and ETL runtimes. By monitoring these indicators and using the autoscaling policies above, the platform maintains the Insights service’s reliability and performance within defined limits. Every parameter for the Insights module – from environment variables to ETL schedules, resource limits, and alert thresholds – is now **finalized** and documented, with no remaining TBD values. This extension integrates cleanly with the existing v14 reference structure, complementing the global and module-specific settings already defined. Future changes to these parameters will follow the same rigorous change-control process as the rest of the platform documentation, ensuring consistency across CI/CD and production environments. All components of the “Insights” slice are thereby production-ready, with clear defaults and governance for configuration. ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Insights Module UI Spec (Reporting & Analytics Frontend).md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 32a4a26f9b48de6c45354412ee62c19cf1ac1966f88345029461b0c40fae17c0 CONTENT_BYTES: 25784 ================================================================================================ ### **Konnaxion v14 – Insights Module UI Spec (Reporting & Analytics Front-end)** *(fully updated, implementation-aligned)* ### --- ## **Document 5.1 – Reporting & Analytics · Frontend layer** ### --- ### **1. Scope** Describes the currently implemented **frontend slice** of the Konnaxion **Insights / Reporting & Analytics** module. This document covers the **user-facing React / Next.js App Router pages** that expose read-only analytical views and a beta custom report-building experience under the **`/reports`** namespace. It includes: - the Reports landing / hub page - the Smart Vote dashboard - the Usage dashboard - the Performance dashboard - the beta Custom Report Builder page - their shared shell, filters, navigation, preview state, and data-access expectations This document is limited to the **frontend layer**. The backend service contract is described in **Document 5.2**, the analytical schema in **Document 5.3**, and infrastructure / operations in **Document 5.4**. ### **Implementation status note** The Reports frontend is no longer a purely target-state concept. The current codebase contains implemented routes and page files for: - `/reports` - `/reports/custom` - `/reports/smart-vote` - `/reports/usage` - `/reports/perf` The current frontend workspace has also passed both: - `tsc --noEmit` - `pnpm build` Accordingly, this document is written as an **implementation-aligned frontend specification**, not as a speculative package design. ### --- ### **2. Routes & Navigation** | Route | Page | Current role | Consumed API(s) / runtime dependency | | ----- | ----- | ----- | ----- | | `/reports` | `ReportsHomePage` | Overview / hub page for Insights surfaces | none required for initial shell | | `/reports/smart-vote` | `SmartVoteDashboard` | Smart Vote / consensus analytics | `GET /api/reports/smart-vote` | | `/reports/usage` | `UsageDashboard` | MAU / projects / docs / adoption | `GET /api/reports/usage` | | `/reports/perf` | `PerfDashboard` | Latency, throughput, error, uptime views | `GET /api/reports/perf` | | `/reports/custom` | `CustomReportBuilderPage` | Beta builder / preview workflow | current frontend preview, optional `WS /ws/reports/custom` | ### **Navigation rules** - The **`/reports`** namespace is reserved for the Insights module. - The frontend uses a shared **`ReportsPageShell`** to provide title, subtitle, actions, and consistent page framing. - The Reports hub page acts as a **navigation entry point**, not as a replacement for the dedicated dashboards. - No other module may claim `/reports/*` or `/ws/reports/*` without a formal routing-reference update. ### **Current route ownership** The Reports / Insights slice remains a **global analytics surface** rather than an Ethikos-only or module-local sub-area. It may visualize data from multiple modules, but its route namespace remains distinct and reserved. ### --- ### **3. Primary UI Surfaces** | Surface / Component | Current role | Notes | | ----- | ----- | ----- | | `ReportsPageShell` | Shared page shell for all Reports pages | Standardized title, subtitle, actions, page framing | | Reports overview cards | Entry-point KPI / navigation cards on `/reports` | Directs users to dedicated dashboards | | Time-range controls | Quick-range + absolute date controls | Used where page semantics require filtering | | Dashboard KPI cards | Large summary metrics | Reused across dashboards | | Dashboard charts | Visual render of trends, KPIs, and distributions | Charting library remains implementation-defined | | Report shortcut list | Quick navigation from hub page | Links to Smart Vote / Usage / Perf | | Builder configuration form | Interactive builder UI on `/reports/custom` | Ant Design Pro form flow | | Builder preview panel | Live local preview / optional realtime preview | Current implementation is frontend-led / beta | | Export actions | Optional report export triggers | Governed by backend permissions and export limits | ### **Important correction vs older spec language** This frontend specification does **not** freeze the Reports slice to a single mandatory charting library. The current codebase already uses page-level implementation choices, and the authoritative contract is: - route ownership - shell/layout consistency - data-access contract - accessibility and testing expectations not a hard requirement that every dashboard must use one charting package. ### --- ### **4. Shared Layout, Shell, and UX Pattern** All Reports pages must render inside the shared **Reports page shell**, which provides: - a page title - a short descriptive subtitle - optional primary and secondary actions - consistent visual spacing and width behavior - compatibility with the broader platform design system The shell is the canonical wrapper for this slice and replaces any earlier assumptions that reports pages would live in a separate frontend package or an isolated micro-frontend shell. ### **Shell expectations** Each Reports page should supply: - `title` - `subtitle` - optional `metaTitle` - optional action buttons - page content as children ### **Design constraints** - no hard-coded visual palette outside approved design tokens - no bespoke top-level shell invented for one report page - no inline raw-fetch orchestration in chart components - all page-level analytics behavior must remain compatible with the global platform layout ### --- ### **5. State & Data Handling** ### **5.1 Current frontend data model** The current Reports frontend relies on a small number of predictable patterns: #### **A. Dashboard REST query pattern** Pages load report data from canonical read-only endpoints under: - `/api/reports/smart-vote` - `/api/reports/usage` - `/api/reports/perf` These are frontend-consumed as dashboard datasets with KPI summaries and chart-ready structures. #### **B. Custom builder preview pattern** The custom builder page manages: - local form state - preview configuration state - preview rendering state The builder currently behaves as a **beta preview surface**. Realtime preview can optionally be connected through: - `WS /ws/reports/custom` but the page must still function as a valid frontend experience even when realtime orchestration is not yet fully enabled end-to-end. ### **5.2 Cache expectations** The Reports frontend may cache request results using a client-side query cache or equivalent wrapper behavior. Minimum expectations: - endpoint + params determine cache identity - cache must invalidate on relevant filter changes - dashboard views should avoid unnecessary repeat fetches during short user interactions ### **5.3 State-management expectations** No Redux requirement is imposed for this slice. The current architecture is satisfied by: - local component state - query-hook state - shell/action props - optional stream state for builder preview ### **5.4 Data-orchestration rule** Report components and charts **must not** become orchestration layers for multiple unrelated raw HTTP calls. Aggregation and composition belong in a service layer or report-specific data hook. ### --- ### **6. Current Page Definitions** ### **6.1 `/reports` — ReportsHomePage** Purpose: - act as the landing page for Insights - present an overview of the available report families - expose quick-range or summary context - route users to the deeper dashboards Current UX responsibilities: - display high-level cards / KPI summaries - present quick links to Smart Vote, Usage, and Performance - explain how to use the Reports area - remain readable even before deeper dashboards are opened This page is a **hub**, not a full analytical substitute for the dedicated report routes. --- ### **6.2 `/reports/smart-vote` — SmartVoteDashboard** Purpose: - visualize Smart Vote outcomes, trends, and correlations - support time-range filtering - expose read-only analytical views of voting behavior Expected content: - KPI summary cards - time-series trend visuals - consensus / participation / polarization indicators - page-level filters where applicable - optional export / admin-only advanced actions --- ### **6.3 `/reports/usage` — UsageDashboard** Purpose: - show adoption and platform usage signals such as: - active users - projects - documents / resources - domain-level activity Expected content: - module/domain comparisons - adoption over time - usage summary cards - segment or domain breakdowns - optional export / admin-oriented analytics actions --- ### **6.4 `/reports/perf` — PerfDashboard** Purpose: - expose reliability and service-health analytics for the platform Expected content: - latency KPIs - throughput trends - error-rate series - uptime / SLO summaries - endpoint or service-level breakdowns - operational views relevant to approved audiences --- ### **6.5 `/reports/custom` — CustomReportBuilderPage** Purpose: - provide a configurable report composition interface - let users choose metrics, dimensions, ranges, and options - preview how a custom analytical view would look Current status: - **beta** - currently frontend-led / preview-oriented - valid and implemented as a page - may optionally connect to a realtime builder stream via WebSocket Important note: This page should be documented as a **builder / preview surface**, not as proof that full report persistence, scheduling, or saved-query lifecycle is complete. ### --- ### **7. User Flows** ### **7.1 Overview → dashboard flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant API as Reports API U->>F: Open /reports F-->>U: Render overview / cards / shortcuts U->>F: Open specific dashboard F->>API: GET /api/reports/<endpoint> API-->>F: JSON dataset F-->>U: Render charts + KPI cards ```` --- ### **7.2 Smart Vote dashboard flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant API as Reports API U->>F: Open /reports/smart-vote F->>API: GET /api/reports/smart-vote?range=30d API-->>F: JSON dataset F-->>U: Charts render U->>F: Change filter / range F->>API: GET updated query API-->>F: JSON dataset F-->>U: Dashboard refreshes ``` --- ### **7.3 Custom builder flow** ```mermaid sequenceDiagram participant U as User participant F as Frontend participant WS as Realtime stream U->>F: Open /reports/custom F-->>U: Render configuration form + preview area U->>F: Set metric / dimensions / range / options F-->>U: Preview updates locally opt Realtime preview enabled F->>WS: Connect /ws/reports/custom WS-->>F: Preview payload / stream updates F-->>U: Enhanced preview updates end ``` ### **Flow rule** Even where realtime is available, the page should degrade gracefully to a non-streaming preview experience. ### --- ### **8. Accessibility, i18n, and UX Quality** The Reports slice must conform to the platform accessibility baseline. Minimum expectations: * charts must not be the only carrier of meaning * labels and summaries must remain readable without visual decoding alone * color usage must satisfy WCAG AA expectations * report pages must remain navigable via keyboard * all user-facing labels should remain localisable under the Reports / Insights namespace Recommended pattern: * pair charts with summaries, legends, tooltips, or compact tabular cues * avoid visually dense dashboards that collapse on smaller screens * prefer progressive disclosure over showing every metric at once ### --- ### **9. Tests & Quality Gate** | Level | Current expectation | | ---------------- | --------------------------------------------------------------------- | | Unit | page helpers, formatting helpers, no-data states, component rendering | | Integration | query/filter changes and API-state transitions | | Type safety | `tsc --noEmit` must pass | | Production build | `pnpm build` must pass | | Runtime QA | manual verification of `/reports*` routes after deployment | | Contract QA | route/API assumptions must remain aligned with backend contract docs | ### **Current quality status** The current frontend implementation has passed: * TypeScript validation * production build validation Runtime verification is still required after deployment or after any API-contract change. ### --- ### **10. Dependencies (frontend layer)** * **Next.js App Router** * **React** * **Ant Design 5** * **`@ant-design/pro-components`** * charting libraries as used by the current page implementation * frontend service wrappers for `/api/reports/*` * optional realtime connection to `/ws/reports/custom` ### **Dependency policy** This document specifies the **contract**, not a mandatory lock-in to one visualization library. Chart-library choices may evolve so long as: * route structure stays consistent * data contracts stay consistent * accessibility expectations stay satisfied * shell/layout patterns remain shared ### --- ### **11. Folder Structure (implementation-oriented)** ```text frontend/ app/ reports/ ReportsPageShell.tsx page.tsx smart-vote/ page.tsx usage/ page.tsx perf/ page.tsx custom/ page.tsx ``` Additional service / hook logic may live outside `app/` in shared frontend modules, but route ownership remains with the structure above. ### --- ## **Document 5.2 – Reporting & Analytics · Backend layer** ### --- ### **1. Scope** Defines the backend service contract for the **read-only Reports / Insights API** used by the frontend dashboards and, where applicable, the custom builder preview flow. This layer is responsible for: * validating query params * enforcing access control * orchestrating analytical queries * caching common read paths * exporting report datasets * returning JSON datasets suitable for the frontend dashboards ### **Service boundary** The Reports backend is conceptually a **read-only analytics service**. It should not own primary OLTP business entities such as Ethikos topics, KeenKonnect projects, or KonnectED resources. It reads and aggregates from analytical or derived sources. ### --- ### **2. Canonical backend endpoints** Canonical backend HTTP paths: * `GET /api/reports/smart-vote` * `GET /api/reports/usage` * `GET /api/reports/perf` Optional / evolving channel: * `WS /ws/reports/custom` Additional export or builder endpoints may be added later, but the frontend contract above is the minimum current slice. ### **Route invariants** * `/api/reports/*` is reserved for the Reports backend service contract. * `/ws/reports/*` is reserved for Reports realtime use. * These prefixes must not be repurposed by another module without a documentation and routing-reference update. ### --- ### **3. Backend responsibilities** The Reports backend must: 1. validate request parameters (range, filters, dimensions, export flags) 2. normalize request defaults 3. authorize access to requested report data 4. query analytical sources or materialized views 5. optionally hydrate labels / dimensions from domain-aware reference data 6. cache repeatable hot queries where useful 7. serialize dashboard-friendly JSON 8. enforce export limits and privacy protections ### **Non-responsibilities** The Reports backend should not become a generic cross-platform write API. Write ownership stays with the module that owns the original business entity. ### --- ### **4. AuthZ and data access** Reports endpoints are **read-only**, but not necessarily public. Expected backend controls include: * role-based permissions * privacy-safe aggregation * restricted export access for larger datasets * exclusion of sensitive or small-cohort datasets where policy requires it Where the analytics source is derived from sensitive user activity, the backend must return only approved aggregated shapes. ### --- ### **5. Caching and query execution** The Reports API may use Redis or equivalent short-lived caching for frequently requested report datasets. Backend cache expectations: * cache key derived from endpoint + params * cache TTL appropriate to report freshness expectations * hot-path queries should avoid repeated analytical DB load where response reuse is safe * cache invalidation policy must remain consistent with the parameter reference and ETL freshness model ### --- ### **6. Export behavior** Exports are permitted only within backend-enforced limits. Expected backend duties: * enforce row-count ceiling * verify user/role authorization for larger exports * stream or stage files safely * ensure exported datasets preserve privacy rules and omit prohibited detail Frontend buttons alone must never be treated as sufficient security. ### --- ### **7. Unit-of-work sequence (Smart Vote report)** ```mermaid sequenceDiagram participant U as User participant API as Reports API participant Cache as Redis participant DB as Analytics DB U->>API: GET /api/reports/smart-vote?range=7d API->>Cache: GET cache key alt cache hit Cache-->>API: dataset else cache miss Cache-->>API: null API->>DB: read analytical view / query DB-->>API: rows API->>Cache: SET cached dataset end API-->>U: 200 JSON ``` ### **Implementation note** Exact internal query objects, serializers, and cache decorators may change, but the service responsibilities above remain stable. ### --- ### **8. Tests & quality gate** | Level | Requirement | | -------------- | ------------------------------------------------------------ | | Unit | request validation, serializer stability, cache-key behavior | | Integration | endpoint query → analytical source → JSON shape | | Contract | stable response shape for frontend consumers | | Perf | protect hot paths with realistic cache-enabled baselines | | Access control | unauthorized access and export-policy tests | ### --- ### **9. Dependencies** * Python 3.12 * Django 4.2 * Django REST Framework * Redis-compatible cache layer * PostgreSQL analytical store * optional WebSocket / Channels layer for custom-builder realtime flows ### --- ## **Document 5.3 – Reporting & Analytics · Database & Storage layer** ### --- ### **1. Scope** Defines the analytical relational objects that power the Reports / Insights slice. This layer covers: * analytical fact tables * dimensions * materialized views / derived datasets * indexes * retention assumptions * privacy and access constraints This storage layer is conceptually separate from OLTP application tables. ### --- ### **2. Analytical model** The Reports slice is based on a **star-schema style** analytical design. #### **Typical dimensions** * `dim_date` * `dim_domain` * `dim_endpoint` * any other approved descriptive dimensions required for reporting #### **Typical facts** * `smart_vote_fact` * `usage_mau_fact` * `api_perf_fact` These support the core frontend dashboards: * Smart Vote * Usage / adoption * API performance ### --- ### **3. Materialized / derived datasets** The frontend dashboards should generally consume data through: * curated analytical queries * materialized views * service-owned derived datasets rather than raw fact-table joins emitted directly from the browser contract. This keeps: * response times predictable * privacy rules enforceable * API shapes stable * report queries maintainable ### --- ### **4. Retention and freshness** Analytical retention and refresh behavior are governed by the Insights parameter reference. At minimum, the Reports storage layer must support: * historical Smart Vote analytics * medium-term usage history * shorter-term API performance data * refreshable derived views for dashboard consumption ### **Freshness model** Some dashboards are naturally near-real-time, while others are refreshed on ETL or materialization cadence. The frontend must not assume all report datasets are realtime unless the backend contract explicitly says so. ### --- ### **5. Privacy and security rules** The analytical storage layer must enforce: * privacy-preserving user identifiers * minimum cohort thresholds where applicable * separation between ETL/service privileges and read-only query roles * auditability of analytical access patterns The Reports DB must not become an unrestricted replica of raw user activity. ### --- ### **6. Access model** A read-only analytical role (or equivalent restricted access model) should be used for report-serving workloads. Principles: * report-serving accounts read dimensions / approved views * raw fact access is restricted where policy requires * export flows remain subject to authorization and auditing ### --- ### **7. Performance expectations** The database layer should support: * hot-path report queries at dashboard-friendly latency * predictable performance on recent time-window lookups * partition-aware retention and maintenance * efficient endpoint/time or domain/time filtering ### --- ### **8. Storage-layer alignment rule** The analytical schema must remain aligned with: * backend report-service contracts (Document 5.2) * frontend page/data expectations (Document 5.1) * parameter and privacy invariants documented elsewhere ### --- ## **Document 5.4 – Reporting & Analytics · DevOps / Infrastructure layer** ### --- ### **1. Objective** Defines the operational and infrastructure expectations for the Reports / Insights slice. This includes: * runtime services * ETL / Airflow support * deployment behavior * environment-variable expectations * observability * backups * alerting * scaling expectations Common platform-wide infrastructure is documented elsewhere; this section covers Reports-specific needs. ### --- ### **2. Runtime components** Typical Reports runtime components include: * `reports-api` * ETL / worker process for analytical refresh tasks * Airflow scheduler / workers for ETL orchestration * migration or initialization job for report-service deployment * Redis cache layer * analytical PostgreSQL store * optional object storage for exports ### **Scaling note** The Reports service should scale independently enough to handle dashboard bursts without forcing scaling policy onto unrelated OLTP services. ### --- ### **3. ETL / Airflow** The Reports slice depends on periodic ETL or refresh jobs for derived analytical datasets. Typical duties include: * ingesting or transforming source data * refreshing materialized analytical views * pruning expired data per retention policy * validating freshness and partition health * supporting export or downstream audit/report operations where required ### **Operational rule** Frontend pages must not assume ETL freshness beyond what the backend contract and job schedule guarantee. ### --- ### **4. Environment variables and config** Reports-specific config belongs in the Insights parameter reference and must remain consistent with deployment values. Typical configuration areas: * analytical DB connection * Redis/cache configuration * export limits * retention or cleanup controls * ETL schedules * stream / WebSocket settings where used * alert thresholds and observability hooks ### --- ### **5. Observability** Minimum operational observability for the Reports slice includes: * structured logs for API requests * metrics for query latency, error rate, and cache behavior * health checks for service readiness * ETL / Airflow job monitoring * alert rules for report-service degradation Recommended focus areas: * high latency on hot report endpoints * repeated cache misses on common dashboards * ETL freshness lag * export failures * WebSocket or preview stream failures where enabled ### --- ### **6. Backup, restore, and disaster readiness** Operational policy must cover: * analytical DB backup schedule * restore drills * retention of backup artifacts * safe handling of staged export files if applicable * treatment of Redis as ephemeral cache unless explicitly stated otherwise ### --- ### **7. CI / deployment quality gate** The Reports slice should pass, at minimum: * service tests * migration safety checks * environment-variable validation where applicable * frontend typecheck/build * deployment health verification * ETL / report-job readiness checks where applicable ### **Frontend gate note** Because the Reports frontend is now implemented, changes affecting `/reports*` should be treated as part of the production quality gate rather than as placeholder documentation-only surfaces. ### --- ### **8. Security and governance** Reports infrastructure must respect: * route invariants * least-privilege access * privacy-safe analytical exposure * auditability of sensitive access * operational separation between ETL privileges and read-only serving privileges ### --- ### **9. Current implementation status note** This Document 5 set should now be interpreted as follows: * **5.1 Frontend** → implemented and build-clean * **5.2 Backend** → canonical report-service contract * **5.3 Database** → canonical analytical storage contract * **5.4 DevOps** → canonical operating model for the slice The frontend section has been updated to reflect the current implemented `/reports*` pages, while the backend, storage, and DevOps sections remain the authoritative contract layers for the broader analytics slice. ### --- ## **End of Document 5 – Reporting & Analytics slice** ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion v14 – Site Navigation Map (Top-Level Routes).md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: c5982e1ba1b43a364aae1b596fe4e05dd2a770913d4d7084cd0a3f106a76869e CONTENT_BYTES: 8297 ================================================================================================ # Navigation Map The list below presents **every top-level page (route)** that a user can reach from the main sidebar, module hubs, or intent cards, grouped by module and sub-module. Nested **tabs, drawers or modals** are noted → they do **not** create extra routes but keep related tasks together. All names preserve the K-branding where still relevant and avoid duplicating boilerplate authentication or error screens. > **Revision note:** The **ethiKos** and **Insights / Reports** sections below were updated to reflect the currently implemented frontend routes. Other module sections are carried forward from the previous navigation map and should be audited module-by-module in a later doc pass. --- ## Global & Cross-Module Shell | Route | Page name | What a user achieves | | ----- | ----- | ----- | | `/` | **Home / Explore** | Choose an intent card (*Debate*, *Build*, *Learn*, *Showcase*, *Connect*) and see a personalised activity feed drawn from all modules. | | `/my-work` | **My Work** | Timeline of all debates, projects, certificates and artworks in which the user is involved, with quick-resume links. | | `/reports` | **Insights Hub** | Entry point to analytics dashboards: Smart Vote, Usage, API Performance, and Custom Reports. | | `/search` | **Global Search** | Unified keyword search across all content types using the common index. | --- ## Kollective Intelligence | Route | Page name | In-page tabs / functions | User value | | ----- | ----- | ----- | ----- | | `/konsensus` | **Konsensus Center** | *Results* · *Leaderboards* · *Smart Vote* | Observe collective metrics, join merit-weighted polls, inspect influence of expertise. | | `/ekoh` | **Ekoh Dashboard** | *Score Analytics* · *Voting Weight* · *Expertise Areas* · *Badges* | Understand and explain one’s reputation and influence. | --- ## ethiKos ### Deliberate | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/deliberate/elite` | **Deliberate · Elite Agora** | Browse and start expert-only structured debates. | | `/ethikos/deliberate/[topic]` | **Deliberate · Topic** | Read a topic thread, post arguments, and submit a stance on the −3…+3 scale. | | `/ethikos/deliberate/guidelines` | **Deliberate · Guidelines** | Read participation rules and debate methodology before contributing. | ### Decide | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/decide/public` | **Decide · Public** | Participate in public consultation-style decisions. | | `/ethikos/decide/elite` | **Decide · Elite** | Review expert-scoped decision topics and previews. | | `/ethikos/decide/results` | **Decide · Results** | View aggregated decision outcomes. | | `/ethikos/decide/methodology` | **Decide · Methodology** | Read how weighted and nuanced decision logic works. | ### Pulse | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/pulse/health` | **Pulse · Health** | Inspect participation health and balance indicators. | | `/ethikos/pulse/live` | **Pulse · Live** | Watch live activity and recent participation signals. | | `/ethikos/pulse/overview` | **Pulse · Overview** | View summary metrics for debate and stance activity. | | `/ethikos/pulse/trends` | **Pulse · Trends** | Analyse changes in participation and sentiment over time. | ### Impact | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/impact/feedback` | **Impact · Feedback** | Submit and review structured feedback tied to Ethikos flows. | | `/ethikos/impact/outcomes` | **Impact · Outcomes** | Inspect aggregated outcomes and participation KPIs. | | `/ethikos/impact/tracker` | **Impact · Tracker** | Track topic/project-like impact items and status progress. | ### Trust | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/trust/badges` | **Trust · Badges** | View earned trust / badge signals. | | `/ethikos/trust/credentials` | **Trust · Credentials** | View and manage credentials-related trust records. | | `/ethikos/trust/profile` | **Trust · Profile** | Inspect the user’s debate reputation and trust profile. | ### Learn | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/learn/changelog` | **Learn · Changelog** | Review release notes and product changes. | | `/ethikos/learn/glossary` | **Learn · Glossary** | Browse core terminology and category vocabulary. | | `/ethikos/learn/guides` | **Learn · Guides** | Read practical guides for using Ethikos flows. | ### Admin | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/admin/audit` | **Admin · Audit** | Review audit events and traceability records. | | `/ethikos/admin/moderation` | **Admin · Moderation** | Moderate topic and contribution flows. | | `/ethikos/admin/roles` | **Admin · Roles** | Review and manage role-related access within Ethikos. | ### Analytics | Route | Page name | What the user does | | ----- | ----- | ----- | | `/ethikos/insights` | **Opinion Analytics** | Analyse stance shifts, participation metrics, and cross-cutting Ethikos analytics. | --- ## Insights / Reports | Route | Page name | What the user does | | ----- | ----- | ----- | | `/reports` | **Insights** | Open the analytics hub for Smart Vote, Usage, and API Performance. | | `/reports/custom` | **Custom Report Builder** | Compose ad hoc analytics views by choosing metrics, dimensions, filters, and layout. | | `/reports/smart-vote` | **Smart Vote Dashboard** | Analyse weighted voting trends and related participation metrics. | | `/reports/usage` | **Usage Dashboard** | Review adoption, activity, and usage volume metrics. | | `/reports/perf` | **API Performance Dashboard** | Monitor latency, reliability, and error-rate trends. | --- ## keenKonnect | Route | Page name | Tabs | User value | | ----- | ----- | ----- | ----- | | `/projects` | **Project Studio** | *Browse* · *Create* · *My Projects* | Discover or start collaboration spaces. | | `/projects/[slug]` | **Workspace** | *Overview* · *Tasks* · *Blueprints* · *Chat* · *AI Insights* · *Settings* | End-to-end project execution with real-time tools. | | `/impact` | **Impact Dashboard** | Single view | Track sustainability and social-impact metrics across projects. | --- ## KonnectED | Route | Page name | Tabs | User value | | ----- | ----- | ----- | ----- | | `/learn` | **Learning Library** | *Catalog* · *Recommendations* · *Offline Download* | Browse or cache educational content. | | `/course/[slug]` | **Course Player** | *Lessons* · *Assessments* · *Progress* | Follow sequenced learning and quizzes. | | `/certs` | **CertifiKation Center** | *Programs* · *My Certificates* | Earn, view and download credentials. | --- ## Kreative (+ Kontact) | Route | Page name | Tabs | User value | | ----- | ----- | ----- | ----- | | `/kreative` | **Creativity Hub** | *Gallery* · *Incubator* · *Virtual Exhibitions* | Showcase art, propose ideas, attend immersive shows. | | `/art/[id]` | **Artwork Sheet** | *Details* · *Comments* · *Metadata* | Deep dive into a single piece, applaud, discuss. | | `/archive` | **Konservation Archive** | *Heritage* · *Partners* | Explore cultural-heritage assets. | | `/connect` | **Connect Center** | *People* · *Opportunities* · *Workspace* | Network with creators, join residencies, open collaboration rooms. | | `/profile/[user]` | **Public Profile** | *Portfolio* · *Reviews* | View another user’s artistic résumé. | --- ## Communication & Administration | Route | Page name | Purpose | | ----- | ----- | ----- | | `/chat` | **Messenger** | Direct / group chat, video toggle. | | `/team` | **Team Manager** | Invite members, assign roles. | | `/admin` | **Admin Console** | Moderation queue, user and stats management. | --- ## Top-Level Route Count | Module or area | Distinct routes | | ----- | ----- | | Global shell & search | 4 | | Kollective Intelligence | 2 | | ethiKos | 24 | | Insights / Reports | 5 | | keenKonnect | 3 | | KonnectED | 3 | | Kreative / Kontact | 5 | | Communication & Admin | 3 | | **Total** | **49** | *(This revision replaces the older compact Ethikos route model with the currently implemented route surface and adds the implemented Reports dashboards.)* ================================================================================================ FILE: docs/Technical-Reference/DocV14/Konnaxion  v14 - Documentation INDEX.docx.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 5c7fc4bf11461a75ccf4ce14fecbc98955943066ee352457e4ed3c8631c50e24 CONTENT_BYTES: 5319 ================================================================================================ **Konnaxion v14 — Documentation Index** *Use this as a directory: each entry tells you **which file** answers a given class of question and **where inside** that file the relevant details live. All filenames below are aligned with the current **DocV14** documentation set.* --- ### **1 System-wide references** | What you will find | File | Look under these headings / anchors | | ----- | ----- | ----- | | **Frozen configuration values** (env-vars, settings constants, route ownership, invariants) | *Konnaxion v14 – Global Parameter Reference (v14-stable).docx.md* | “0 Global / Core (shared by all apps)”, module sections, “6 Navigation & Route Invariants”, “7 Environment-variable Matrix …” | | **Complete top-level route list** (pages grouped by module) | *Konnaxion v14 – Site Navigation Map (Top-Level Routes).docx.md* | “Global & Cross-Module Shell”, then each module block | | **Every custom Django / platform table** (model name, purpose, key columns) | *Konnaxion v14 – Database Schema Reference (Custom Tables).docx.md* | Module headings → sub-module table lists | | **Functional capability catalogue** (code-names, one-line purpose, service/hook naming) | *Konnaxion v14 – Functional Code-Name Inventory (Services & Hooks).docx.md* | Module → Sub-module matrix | --- ### **2 Module technical specifications** *All major module architecture details live in the platform-wide technical specification. Use the module heading, then jump to the layer you need.* | Module | File | Sections / layer anchors | | ----- | ----- | ----- | | **Kollective Intelligence** | *Konnaxion v14 – Full-Stack Technical Specification.docx.md* | “Kollective Intelligence → Frontend …”, “Backend …”, “Database …”, “DevOps …” | | **ethiKos** | same file | “ethiKos → Frontend …”, “Backend …”, “Database …”, “DevOps …” | | **keenKonnect** | same file | “keenKonnect → Frontend …”, “Backend …”, “Database …”, “DevOps …” | | **KonnectED** | same file | “KonnectED → Frontend …”, “Backend …”, “Database …”, “DevOps …” | | **Kreative (+ Kontact)** | same file | “Kreative → Frontend …”, “Backend …”, “Database …”, “DevOps …” | --- ### **3 Reporting & Analytics / Insights slice** | What you need | File | Look under these headings / anchors | | ----- | ----- | ----- | | **Frontend UI / route spec** | *Konnaxion v14 – Insights Module UI Spec (Reporting & Analytics Frontend).docx.md* | “1. Scope”, “2. Routes & Navigation”, page/component sections | | **Configuration parameters and invariants** | *Konnaxion v14 – Insights Module Config Parameters.docx.md* | “Configuration Parameters and Invariants” | | **Shared platform architecture context** | *Konnaxion v14 – Full-Stack Technical Specification.docx.md* | Common/core frontend/backend sections and any Reporting / Analytics references | | **Global environment-variable and route invariants** | *Konnaxion v14 – Global Parameter Reference (v14-stable).docx.md* | “6 Navigation & Route Invariants”, “7 Environment-variable Matrix …” | *These references collectively cover the current Insights / Reports surface, including routes under `/reports` and the wider platform constraints that govern them.* --- ### **4 How to use this index** 1. **Need a setting, constant, route invariant, or env var?** Open the **Global Parameter Reference** and jump to the relevant numbered section. 2. **Need module architecture (frontend / backend / DB / DevOps)?** Open the **Full-Stack Technical Specification** and search for the module name, then the layer heading. 3. **Need Reporting / Insights frontend behavior or route definitions?** Open the **Insights Module UI Spec**. 4. **Need Reporting / Insights configuration rules or operational invariants?** Open the **Insights Module Config Parameters**. 5. **Need to know which module owns a route or which routes exist at top level?** Check the **Site Navigation Map (Top-Level Routes)**. 6. **Need to know which table or model stores something?** Check the **Database Schema Reference (Custom Tables)**. 7. **Need to decode a code-name or functional label?** Check the **Functional Code-Name Inventory (Services & Hooks)**. --- ### **5 Notes on source-of-truth usage** - The **Global Parameter Reference** is the source of truth for shared invariants, route ownership, and configuration-style constants. - The **Full-Stack Technical Specification** is the source of truth for layered module architecture. - The **Insights Module UI Spec** is the source of truth for the Reporting / Analytics frontend surface. - The **Insights Module Config Parameters** file is the source of truth for Reporting / Analytics configuration and invariants. - The **Site Navigation Map** is the source of truth for top-level reachable routes. - The **Database Schema Reference** is the source of truth for custom tables and storage ownership. - The **Functional Code-Name Inventory** is the source of truth for module capability names and code-name mapping. This mapping removes ambiguity: each architectural, implementation, route, or reporting question has a concrete file and section to start from. ================================================================================================ FILE: docs/Technical-Reference/GLOSSARY.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: d1fac795507201143ad7354eb2f19d6c1b69b64641e3faef3b68541dcba53d1b CONTENT_BYTES: 4438 ================================================================================================ # Konnaxion — Architectural Glossary ## Konnaxion **Konnaxion** is an **ecosystem system** in the kOA Digital Ecosystem. In its own scope it is also a **platform** because it contains multiple product domains, applications, services and shared capabilities. When hosted or integrated by kOA-Linux, Konnaxion may be called a **subsystem from the kOA-Linux scope**. That host-relative term does not transfer Konnaxion's internal authority. ## Module `module` is a generic product/UI word, not a sufficient architecture category. Within Konnaxion, existing UI and documentation may use `module` for named product areas. In normative architecture text, prefer the exact category: ```text module → domain → application → service → component → gateway → interface surface ``` Examples: - Konnaxion: ecosystem system / platform. - ethiKos: Konnaxion civic domain and application surface. - EkoH: Konnaxion domain/service boundary for expertise, ethics, privacy and rating access. - Smart Vote: Konnaxion derived-reading/aggregation boundary. - Kontrol: Konnaxion administrative application surface. - Reports: cross-domain reporting application surface. - K-Port: EkoH evidence application/gateway; not a peer of Konnaxion. ## Domain A **domain** owns a coherent set of business semantics and authoritative state. A domain can be physically implemented by one Django app, several apps, or shared infrastructure. Logical domain boundaries do not require one database per domain, but they require explicit write ownership. ## Application An **application** is a bounded software/user-facing capability. It can present or mediate a domain without owning every state it displays. ## Service A **service** is an executable capability with an API/function/task boundary. A service should mutate only state owned by its domain. ## Gateway A **gateway** accepts/transforms/transports data at a declared boundary. A gateway does not become the owner of the downstream authoritative state. ## Source fact A **source fact** is an authoritative event/state owned by the domain that captured it. Examples include an ethiKos stance or a consultation ballot. ## Baseline A **baseline** is the direct, declared aggregation/view of the relevant source facts without a contextual Smart Vote lens silently replacing them. ## Reading A **reading** is a derived interpretation of source facts under an explicit method/lens. ```text Reading = f(SourceFacts, LensDeclaration, SnapshotContext?) ``` A reading should identify its target, method/lens, input snapshot when applicable, computation time and result payload. ## Lens A **lens** declares the method and contextual assumptions used to produce a reading. A lens is not truth and does not transfer ownership of source facts. ## EkoH snapshot A content-identifiable set of EkoH contextual inputs used for a reading. If a reading is presented as published/replayable, the referenced snapshot must itself be retrievable or otherwise reproducible. ## Korum **Korum** is the logical structured-deliberation sub-domain inside ethiKos. Current physical implementation is primarily inside `konnaxion.ethikos` rather than a separate Django app. ## Konsultations **Konsultations** is the logical consultation/intake/decision sub-domain inside the Konnaxion civic surface. It owns formal source participation/ballot semantics when such a protocol is used. It must not be equated automatically with an Orgo Task or with a Smart Vote reading. ## EkoH **EkoH** owns contextual expertise, ethics/reliability, confidentiality/rating visibility, evidence-derived score state and related access policy. It does not own civic ballots or final decision protocols. ## Smart Vote **Smart Vote** owns declared derived readings, lens semantics and reading aggregation. It may consume EkoH context and source participation facts through explicit bindings. It must not silently rewrite those sources. ## Kollective Intelligence **Kollective Intelligence** is retained as a product/navigation umbrella. It is **not the canonical backend owner** for EkoH or Smart Vote state. Canonical code ownership is split between `konnaxion.ekoh` and `konnaxion.smart_vote`. ## External ecosystem system Orgo, Kristal, SemantiK Architect and kOA-Linux are external ecosystem systems relative to the Konnaxion domain. Integration does not give them direct write access to Konnaxion internal state. ================================================================================================ FILE: docs/Technical-Reference/HowToNest-wrap-shell.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: de14a3778f86768bf11cf478b961df287529c349ac5d2302e2bdf82be19903d6 CONTENT_BYTES: 12233 ================================================================================================ # Layout shells — How to nest Konnaxion product domains Objectif : Standardiser le layout des pages dans les 5 modules principaux, en utilisant **un shell par module** : * KeenKonnect → `KeenPageShell` * Ekoh → `EkohPageShell` * Ethikos → `EthikosPageShell` * KonnectED → `KonnectedPageShell` * Kreative → `KreativePageShell` Chaque page d’un module doit : 1. Être enveloppée par le **shell du module**. 2. Ne **pas** redéfinir son propre “gros header” (`h1`, titre principal, etc.) en dehors du shell. 3. Ne **pas** gérer de breadcrumb local (géré par le layout global, si nécessaire). --- ## 1. Récap des shells par module ### 1.1. KeenKonnect * **Fichier** : `app/keenkonnect/KeenPageShell.tsx` * **Composant** : `KeenPageShell` (export par défaut) * **Usage typique dans une page** : ```tsx import KeenPageShell from '@/app/keenkonnect/KeenPageShell'; export default function SomeKeenPage() { return ( <KeenPageShell title="My KeenKonnect Page" description="One-line description of what this page does." toolbar={( /* optionnel : boutons d’action à droite du titre */ )} > {/* contenu de la page */} </KeenPageShell> ); } ``` ### 1.2. Ekoh * **Fichier** : `app/ekoh/EkohPageShell.tsx` (nom exact à vérifier dans le repo, mais pattern = `EkohPageShell`) * **Composant** : `EkohPageShell` (export par défaut) * **Usage typique** : ```tsx import EkohPageShell from '@/app/ekoh/EkohPageShell'; export default function EkohSomethingPage() { return ( <EkohPageShell title="Ekoh · Voting Influence" description="View and understand your current voting weight in Ekoh." > {/* contenu Ekoh (PageContainer, Card, ProCard, etc.) */} </EkohPageShell> ); } ``` ### 1.3. Ethikos * **Fichier** : `app/ethikos/EthikosPageShell.tsx` * **Composant** : `EthikosPageShell` * **Usage** : ```tsx import EthikosPageShell from '@/app/ethikos/EthikosPageShell'; export default function EthikosAnalyticsPage() { return ( <EthikosPageShell title="Ethikos Analytics" description="Ethical impact analytics and scorecards." > {/* contenu Ethikos */} </EthikosPageShell> ); } ``` ### 1.4. KonnectED * **Fichier** : `app/konnected/KonnectedPageShell.tsx` * **Composant** : `KonnectedPageShell` * **Usage** : ```tsx import KonnectedPageShell from '@/app/konnected/KonnectedPageShell'; export default function KonnectedDashboardPage() { return ( <KonnectedPageShell title="KonnectED Dashboard" description="Overview of learning journeys and cohorts." > {/* contenu KonnectED */} </KonnectedPageShell> ); } ``` ### 1.5. Kreative * **Fichier** : `app/kreative/KreativePageShell.tsx` * **Composant** : `KreativePageShell` * **Usage** : ```tsx import KreativePageShell from '@/app/kreative/KreativePageShell'; export default function KreativeSpacePage() { return ( <KreativePageShell title="Collaborative Spaces" description="Find or start creative collaboration spaces." > {/* contenu Kreative */} </KreativePageShell> ); } ``` --- ## 2. Implémentation de référence – KeenKonnect (`KeenPageShell`) Pour KeenKonnect, le shell est un **layout central** déjà présent sous `app/keenkonnect/KeenPageShell.tsx`. Il gère : * le `<title>` dans l’onglet navigateur, * le gros `<h1>`, * la description sous le titre, * la toolbar à droite, * la largeur/padding du contenu. Exemple d’implémentation (référence, à garder alignée avec ton fichier réel) : ```tsx // app/keenkonnect/KeenPageShell.tsx 'use client'; import React from 'react'; import Head from 'next/head'; import usePageTitle from '@/hooks/usePageTitle'; export type KeenPageShellProps = { /** Gros titre de la page, affiché en <h1> */ title: string; /** Sous-titre / description sous le titre */ description?: string; /** Titre <title> du navigateur. Si non fourni, on génère "KeenKonnect · {title}" */ metaTitle?: string; /** Contenu principal de la page */ children: React.ReactNode; /** * Élément(s) à droite du titre (boutons d’action, filtres, etc.) * ex: <Button type="primary">New</Button> */ toolbar?: React.ReactNode; /** Largeur max de la zone centrale */ maxWidth?: number | string; }; export default function KeenPageShell({ title, description, metaTitle, children, toolbar, maxWidth = 1200, }: KeenPageShellProps) { const finalMetaTitle = metaTitle ?? `KeenKonnect · ${title}`; // Synchronise le titre de l’onglet (hook existant dans ton codebase) usePageTitle(finalMetaTitle); return ( <> <Head> <title>{finalMetaTitle}
{/* Header de page standardisé */}

{title}

{description && (

{description}

)}
{toolbar &&
{toolbar}
}
{/* Contenu spécifique à la page */} {children}
); } ``` **Règles associées (KeenKonnect)** : * ✅ **Toujours** utiliser `KeenPageShell` pour les pages KeenKonnect (sauf cas ultra-spéciaux type page système). * ✅ Titre principal **toujours** en `h1.text-2xl.font-bold` (fourni par le shell). * ✅ Padding global **toujours** `container mx-auto p-5`. * ✅ Toolbar → prop `toolbar`. * 🚫 **Pas** de breadcrumb local (géré au niveau `app/keenkonnect/layout.tsx` si nécessaire). * 🚫 **Pas** de `` local ni de `usePageTitle` local dans les pages KeenKonnect. --- ## 3. Page de référence KeenKonnect Exemple basé sur `knowledge/search-filter-documents` : ```tsx 'use client'; import React from 'react'; import { Card, Alert } from 'antd'; import type { PaginationProps } from 'antd'; import { ProTable, QueryFilter, ProFormText, ProFormSelect, ProFormDateRangePicker, } from '@ant-design/pro-components'; import KeenPageShell from '@/app/keenkonnect/KeenPageShell'; // ... types + données (DocumentResource, sampleDocuments, etc.) export default function SearchFilterDocumentsPage(): JSX.Element { // ... state, filtres, useMemo, columns, paginationProps, etc. return ( {/* Bloc filtres */} {/* ... champs de filtre */} {/* Résumé + table */} {/* Pagination externe */} ); } ``` 👉 C’est ce pattern qu’il faut viser pour **toutes les pages KeenKonnect**. --- ## 4. Patterns par type de page (communs aux 5 modules) Les types de pages sont similaires dans les 5 modules, seul le shell change (`KeenPageShell`, `EkohPageShell`, etc.). ### 4.1. Pages “form wizard” (StepsForm) Ex : * KeenKonnect : `create-new-project`, `submit-impact-reports`, `match-preferences` * Kreative : `create-new-idea` * KonnectED : onboarding / course setup Pattern : ```tsx {/* StepForm ... */} ``` Même chose pour Ekoh/Kreative/etc. en remplaçant le shell : ```tsx {/* StepsForm dans un Card */} ``` ### 4.2. Pages “tableau & filtres” (list, ProTable) Ex : * KeenKonnect : `knowledge/search-filter-documents`, `projects/my-projects`, `workspaces/my-workspaces`, `knowledge/document-management`. * Kreative : listes d’espaces, projets, idées. * Ethikos / Ekoh : listes de contributions, événements, votes. Pattern : ```tsx New project )} > {/* Filtres / QueryFilter / search bar */} ``` ### 4.3. Pages “dashboard / analytics” Ex : * KeenKonnect : `sustainability-impact/sustainability-dashboard`, `track-project-impact`. * Ekoh/Ethikos : dashboards de scores, indices. * KonnectED : dashboard de progression. Pattern : ```tsx
{/* Graph / KPI */} {/* ... autres cards */} ``` Même logique pour les autres modules, avec leur shell respectif. --- ## 5. Migration / refactor – règles concrètes ### 5.1. Fix central Pour chaque module : 1. S’assurer que le shell existe (`KeenPageShell`, `EkohPageShell`, etc.) et expose : * `title` * `description?` * `metaTitle?` (optionnel, selon le module) * `toolbar?` * `children` 2. Vérifier que le shell gère : * le `` navigateur (ou au moins `usePageTitle`), * le `<h1>` et la description, * la largeur/padding du container principal. ### 5.2. Fix “par page” (ce que tu vas appliquer aux 20 fichiers KeenKonnect) Pour chaque page du module : 1. **Import du shell** ```tsx import KeenPageShell from '@/app/keenkonnect/KeenPageShell'; ``` (et équivalent pour les autres modules.) 2. **Wrapper racine** * Avant : ```tsx export default function MyPage() { return ( <div className="container mx-auto p-5"> <h1>My Page</h1> {/* ... */} </div> ); } ``` ou ```tsx return ( <PageContainer title="My Page"> {/* ... */} </PageContainer> ); ``` * Après : ```tsx export default function MyPage() { return ( <KeenPageShell title="My Page" description="One-line description." toolbar={/* optionnel */} > {/* Ancien contenu, SANS le h1, SANS le PageContainer header */} </KeenPageShell> ); } ``` 3. **Supprimer** : * `<h1>` / `Typography.Title` principaux (le shell gère le titre). * Breadcrumbs locaux (`<Breadcrumb>`, `breadcrumb` dans `PageContainer`). * `usePageTitle` dans la page (géré par le shell). * `<Head>` local (sauf cas très particulier, meta custom). 4. **Garder / Replacer** à l’intérieur du shell : * `Card`, `ProTable`, `StepsForm`, `Tabs`, `PageContainer` (mais sans header/breadcrumb). * Sous-sections : utiliser `Card title="…"`, ou `h2`/`h3` tailwind (`text-lg font-semibold`, etc.). --- ## 6. TL;DR pour les 5 modules * Un **shell par module** : * KeenKonnect → `KeenPageShell` * Ekoh → `EkohPageShell` * Ethikos → `EthikosPageShell` * KonnectED → `KonnectedPageShell` * Kreative → `KreativePageShell` * Chaque page de module : ```tsx import XxxPageShell from '@/app/xxx/XxxPageShell'; export default function SomePage() { return ( <XxxPageShell title="…" description="…" toolbar={…}> {/* contenu */} </XxxPageShell> ); } ``` * **Aucun** gros header local (`h1`, breadcrumb) dans les pages. * Tout le layout de haut niveau (titre, description, toolbar, padding) est géré par le shell. ================================================================================================ FILE: docs/Technical-Reference/Konnaxion_Frontend_Deployment_Runbook.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: b7d9a4f6b166a2b623edd8281e1748c074c07d6367be8d8e71240d47abe5fe1c CONTENT_BYTES: 4310 ================================================================================================ # Konnaxion Frontend Deployment Runbook ## Purpose This runbook captures the deployment flow that was validated on the live Konnaxion VPS. It is intended for updating the Next.js frontend after pushing changes to GitHub. ## Verified environment - Local repo root: `C:\mycode\Konnaxion\Konnaxion` - Frontend app root: `C:\mycode\Konnaxion\Konnaxion\frontend` - Live VPS checkout: `/home/deploy/apps/Konnaxion` - Live frontend working directory: `/home/deploy/apps/Konnaxion/frontend` - Frontend service name: `konnaxion-frontend` - Systemd working directory verified: `/home/deploy/apps/Konnaxion/frontend` - Systemd start command verified: `/usr/local/bin/pnpm start --port 3000` ## Standard deployment flow ### Local machine ```bash git add . git commit -m "your change" git push origin main ``` ### VPS deploy SSH to the VPS, pull the latest code, rebuild the frontend, then restart the frontend service. ```bash ssh deploy@159.198.41.96 cd /home/deploy/apps/Konnaxion git pull cd frontend export NODE_OPTIONS="--max-old-space-size=4096" rm -rf .next pnpm install --frozen-lockfile pnpm build sudo systemctl restart konnaxion-frontend journalctl -u konnaxion-frontend -n 50 --no-pager ``` ### Verify the deploy ```bash curl -I http://127.0.0.1:3000/ curl -I "http://127.0.0.1:3000/search?q=konnected" curl -I https://konnaxion.com/ curl -I "https://konnaxion.com/search?q=konnected" ``` Expected result: HTTP 200 responses from both the local service on port 3000 and the public domain. ## Important operational notes - Run `pnpm build` from the `frontend` directory, not from the repo root. - Set `NODE_OPTIONS=--max-old-space-size=4096` on the VPS before building. This was needed to avoid Next.js heap out-of-memory failures. - Do not restart the frontend service until the build has finished successfully. - The frontend service uses the existing production build inside `.next`. If `.next` is missing or incomplete, `next start` will fail immediately. ## Troubleshooting ### Build fails with JavaScript heap out of memory Symptoms: - `next build` exits with V8 heap / Mark-Compact / Allocation failed messages. - The VPS has limited RAM, so large production builds may fail without extra heap space. Fix: ```bash cd /home/deploy/apps/Konnaxion/frontend export NODE_OPTIONS="--max-old-space-size=4096" rm -rf .next pnpm install --frozen-lockfile pnpm build ``` ### `next start` says it cannot find a production build Symptoms: - `Could not find a production build in the '.next' directory.` - systemd restarts the service repeatedly and port 3000 does not stay up. Check that the build output exists before restarting: ```bash cd /home/deploy/apps/Konnaxion/frontend ls -la .next test -f .next/BUILD_ID && echo OK_BUILD ``` Only restart the service after `.next/BUILD_ID` exists. ### Service status checks ```bash systemctl status konnaxion-frontend --no-pager -l journalctl -u konnaxion-frontend -n 80 --no-pager ss -ltnp | grep :3000 || true ``` When healthy, the service should be active (running), Next.js should log `Ready`, and port 3000 should be listening. ### Manual startup test Run this only when the service is stopped, otherwise port 3000 will already be in use. ```bash cd /home/deploy/apps/Konnaxion/frontend NODE_ENV=production /usr/local/bin/pnpm start --port 3000 ``` ### Windows PowerShell notes On Windows, `rm -rf` is not valid PowerShell syntax. Use: ```powershell Remove-Item -Recurse -Force .next ``` Also remember that `pnpm build` must be run from the `frontend` folder, not from the repo root. ## Known caveats from this deployment - The frontend build completed with warnings related to `@auth0/nextjs-auth0` being included in the Edge Runtime path. - The frontend build also completed with warnings related to `@ant-design/plots` / `tslib` on `app/ethikos/insights/page.tsx`. - Those warnings did not block the deploy, but the Ethikos Insights page should be tested explicitly after each release. ## Minimal copy/paste deploy recipe ```bash ssh deploy@159.198.41.96 cd /home/deploy/apps/Konnaxion git pull cd frontend export NODE_OPTIONS="--max-old-space-size=4096" rm -rf .next pnpm install --frozen-lockfile pnpm build sudo systemctl restart konnaxion-frontend journalctl -u konnaxion-frontend -n 50 --no-pager curl -I https://konnaxion.com/ ``` ================================================================================================ FILE: docs/Technical-Reference/namecheap-vps.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: a607b62c281c801fb28eeaf9a96b18a10276c341883c07c7b52330d7cee97861 CONTENT_BYTES: 6413 ================================================================================================ # Konnaxion Deployment Guide — Namecheap VPS ## Scope This guide documents the current production deployment shape used for Konnaxion on the Namecheap VPS. ```text /home/deploy/apps/Konnaxion/ ├── backend/ └── frontend/ ``` Runtime shape: ```text Backend Django / DRF in Docker Compose Frontend Next.js with Node.js / pnpm Database PostgreSQL in Docker Queue Redis in Docker Workers Celery in Docker Proxy Traefik in Docker ``` Public routing: ```text https://konnaxion.com/ -> Next.js frontend :3000 https://konnaxion.com/api/ -> Django https://konnaxion.com/admin/ -> Django admin https://konnaxion.com/media/ -> media service https://konnaxion.com:5555/ -> Flower when enabled ``` ## Backend configuration Required production files: ```text backend/docker-compose.production.yml backend/.envs/.production/.django backend/.envs/.production/.postgres ``` Minimum `.django` shape: ```env DJANGO_SETTINGS_MODULE=config.settings.production DJANGO_SECRET_KEY='CHANGE_ME' DJANGO_DEBUG=False DJANGO_ALLOWED_HOSTS=159.198.41.96,localhost,127.0.0.1,konnaxion.com,www.konnaxion.com USE_DOCKER=yes DATABASE_URL=postgres://konnaxion:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/konnaxion REDIS_URL=redis://redis:6379/0 CELERY_BROKER_URL=redis://redis:6379/0 DJANGO_ADMIN_URL=admin/ SENTRY_DSN= ETHIKOS_DEMO_IMPORTER_ENABLED=true ``` Quote `DJANGO_SECRET_KEY` when it contains `$` so Docker Compose does not interpolate parts of the value. Minimum `.postgres` shape: ```env POSTGRES_HOST=postgres POSTGRES_PORT=5432 POSTGRES_DB=konnaxion POSTGRES_USER=konnaxion POSTGRES_PASSWORD=CHANGE_ME_POSTGRES_PASSWORD ``` `backend/requirements/production.txt` must provide the PostgreSQL driver required by the current Django configuration. The current deployment reference uses: ```text psycopg[binary]==3.2.12 ``` ## Start and migrate backend ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml up -d --build docker compose -f docker-compose.production.yml run --rm django python manage.py migrate docker compose -f docker-compose.production.yml ps docker compose -f docker-compose.production.yml logs --tail=100 django ``` Create an administrative user when required: ```bash docker compose -f docker-compose.production.yml run --rm django python manage.py createsuperuser ``` ## Frontend production configuration Production environment file: ```text frontend/.env.production ``` Expected public endpoints: ```env NEXT_PUBLIC_API_BASE=https://konnaxion.com/api NEXT_PUBLIC_BACKEND_BASE=https://konnaxion.com ``` Next.js embeds public environment variables during the build, so changing these values requires a rebuild. ```bash cd /home/deploy/apps/Konnaxion/frontend pnpm install --frozen-lockfile rm -rf .next export NODE_OPTIONS="--max-old-space-size=4096" export NEXT_TELEMETRY_DISABLED=1 pnpm build ``` Start the production frontend: ```bash cd /home/deploy/apps/Konnaxion/frontend pkill -f "next start" || true pkill -f "pnpm start" || true nohup pnpm start --hostname 0.0.0.0 --port 3000 > frontend.log 2>&1 & sleep 4 tail -n 60 frontend.log ``` ## Traefik routing Traefik owns the public HTTP/HTTPS entry points. The production routing must preserve these boundaries: ```text / -> frontend /api/ -> Django /admin/ -> Django /media/ -> media service ``` After changing Traefik configuration: ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml build --no-cache traefik docker compose -f docker-compose.production.yml up -d --force-recreate traefik docker compose -f docker-compose.production.yml logs --tail=200 traefik ``` DNS for `konnaxion.com` and `www.konnaxion.com` must resolve to the VPS before certificate issuance. Certificate configuration must contain public DNS names only. ## Worker lifecycle Celery workers can be stopped while a resource-intensive frontend build runs and restarted afterward. ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml stop celeryworker celerybeat flower || true ``` After the build: ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml up -d celeryworker celerybeat flower ``` ## Deployment sequence Build locally before upload: ```powershell cd C:\mycode\Konnaxion\Konnaxion\frontend pnpm install --frozen-lockfile pnpm exec tsc --noEmit --pretty false $env:NODE_OPTIONS="--max-old-space-size=4096" pnpm build ``` Deploy a clean source archive to `/home/deploy/apps/Konnaxion`, provision the production environment files outside the archive, then run: ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml up -d --build docker compose -f docker-compose.production.yml run --rm django python manage.py migrate cd /home/deploy/apps/Konnaxion/frontend pnpm install --frozen-lockfile rm -rf .next export NODE_OPTIONS="--max-old-space-size=4096" export NEXT_TELEMETRY_DISABLED=1 pnpm build nohup pnpm start --hostname 0.0.0.0 --port 3000 > frontend.log 2>&1 & cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml up -d --force-recreate traefik celeryworker celerybeat flower ``` ## Validation Backend and platform status: ```bash cd /home/deploy/apps/Konnaxion/backend docker compose -f docker-compose.production.yml ps docker compose -f docker-compose.production.yml logs --tail=100 django docker compose -f docker-compose.production.yml logs --tail=100 traefik ``` Frontend: ```bash cd /home/deploy/apps/Konnaxion/frontend tail -n 100 frontend.log ``` Ports: ```bash sudo ss -tulnp | grep -E ':80|:443|:3000|:5555' ``` External validation: ```powershell curl.exe -I https://konnaxion.com curl.exe -I https://www.konnaxion.com ``` The root response should be served by Next.js; `/api/` and `/admin/` should resolve through the Django route. ## Security baseline - never commit production `.env` files; - never paste `DATABASE_URL`, `POSTGRES_PASSWORD`, `DJANGO_SECRET_KEY`, API tokens or private keys into logs or documentation; - SSH uses keys only; - root SSH login is disabled; - public ingress is limited to SSH as administratively required plus HTTP/HTTPS; - port 3000 is not exposed publicly; - only expected Docker images and containers run on the host; - privileged actions and deployment credentials follow least privilege. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/CertifiKation (Skills & Certification) — sub‑module under KonnectED.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 13b57e8f28ae99e0cf81cf206d39b2df135228dcf10f893b5cf92664863c5751 CONTENT_BYTES: 4816 ================================================================================================ **CertifiKation (Skills & Certification)** — sub‑module under **KonnectED**. Implements five core services with fixed code‑names and routes exposed via the DRF backend and `/certs` UI flows. --- ### **1\) Functional Services (and expected files)** Code‑names come from the v14 Functional Inventory; each maps 1‑to‑1 to a Django service module (e.g., `services/<code_name>.py`). | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Certification Paths | `certification_path_management` | Define/maintain modular learning paths and competency milestones. | `services/certification_path_management.py` | | Automated Evaluation | `automated_evaluation` | Auto‑graded quizzes/tests and score calculation with metadata. | `services/automated_evaluation.py` | | Peer Validation | `peer_validation` | Mentor/peer approval workflow on submitted evidence tied to an evaluation. | `services/peer_validation.py` | | Skills Portfolio | `skills_portfolio` | User portfolio of validated skills and artifacts, surfaced in “My Certificates.” | `services/skills_portfolio.py` | | Interoperability (LMS) | `certification_interoperability` | Map/import/export certifications with external LMS/registries. | `services/certification_interoperability.py` | The inventory explicitly lists these five services for CertifiKation and describes the code‑name→service convention used across modules. --- ### **2\) Backend Functionalities** * **Program & curriculum management.** CRUD for *CertificationPath* (name, description), ordering of steps, and visibility rules; exposed via DRF to power `/certs` → “Programs.” * **Evaluations & scoring.** Creating an *Evaluation* per user/path records `raw_score` and structured `metadata` (e.g., answers, rubric). Pass/fail uses frozen thresholds (see CERT\_PASS\_PERCENT), and retries respect a cooldown policy. * **Peer validation workflow.** *PeerValidation* ties to an Evaluation; authorized peers issue an `approved`/`rejected` decision that finalizes the evaluation outcome when required by the path. * **Certificate issuance.** On successful completion (auto‑evaluation and/or peer validation), a **Certificate** record (core/common model) links the user to the earned credential for display and download from `/certs` → “My Certificates.” * **Skills portfolio linkage.** Portfolio items (evidence, learning artifacts) can be attached to programs and evaluations so achievements surface coherently in the user’s skill profile. * **Interoperability.** *InteropMapping* maps internal paths to external systems’ identifiers to support import/export and verification workflows. * **Permissions & roles.** Uses the platform’s unified JWT/RBAC and Krowd user model; module actions inherit common auth and moderation controls. --- ### **3\) Database Models** These are the concrete tables tied to CertifiKation features; “Certificate” is defined at the common/core layer and consumed here. | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | **CertificationPath** | Defines a named certification/learning path. | `id`, `name`, `description` | | **Evaluation** | Stores a user’s attempt and score on a path. | `id`, `user`, `path`, `raw_score`, `metadata` (JSON) | | **PeerValidation** | Peer/mentor decision for an Evaluation. | `id`, `evaluation`, `peer`, `decision` (enum) | | **Portfolio** (KonnectED) | User skill/evidence showcase used by skills\_portfolio. | `id`, `user`, `title`, `description`, `items` (M2M) | | **InteropMapping** | Links internal CertificationPath to external LMS IDs. | `id`, `local_certification`, `external_system`, `external_id` | | **Certificate** (Core) | Issued credential linking user↔certification. | fields per core “Certificate (CertifiKation)” model | Model purposes/fields are specified in the v14 schema reference and the core database description. --- ### **4\) Supporting Configuration** * **Pass threshold:** `CERT_PASS_PERCENT = 80%` (applied by automated\_evaluation/issuance logic). * **Retry policy:** `QUIZ_RETRY_COOLDOWN_MIN = 30` minutes between failed attempts. * **Module routes:** `/certs` reserved for the CertifiKation Center (Programs, My Certificates). --- ### **Summary** CertifiKation delivers end‑to‑end credentialing: define programs (*CertificationPath*), assess learners (*Evaluation*), adjudicate evidence (*PeerValidation*), issue credentials (core *Certificate*), and present outcomes via portfolios and the `/certs` flows. Its five named services (`certification_path_management`, `automated_evaluation`, `peer_validation`, `skills_portfolio`, `certification_interoperability`) are version‑locked in the inventory and backed by concrete schema and parameters. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/EkoH (Reputation & Expertise) — first sub‑module under Kollective Intelligence.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: ea74104a4cad1fdba9142a3b156d8eab6c7c3b33f44e5119b4cffca75a6df0cd CONTENT_BYTES: 4821 ================================================================================================ **EkoH (Reputation & Expertise)** — first sub‑module under **Kollective Intelligence**. Implements seven core services with clear code‑names, supported by dedicated models and fixed parameters. --- ### **1\) Functional Services (and expected files)** Code‑name list per the v14 inventory; each code‑name maps to a Django service module (e.g., `services/scoring.py` contains `multidimensional_scoring`). | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Multidimensional Scoring | `multidimensional_scoring` | Compute per‑user/content scores across axes (quality, frequency, relevance, expertise). | `services/scoring.py` | | Criteria Customization | `configuration_weights` | Adjust scoring weights per axis/domain; read from stored configuration. | `services/configuration.py` (reads `ScoreConfiguration`) | | Automatic Contextual Analysis | `contextual_analysis` | AI tweaks sub‑scores in real time by topic/history/complexity signals. | `services/contextual_analysis.py` | | Dynamic Privacy | `privacy_settings` | Enforce anonymity/pseudonym modes while still exposing merit outputs. | `services/privacy.py` | | History & Traceability | `score_history` | Persist every recalculation/config change for auditability. | `services/history.py` (+ model hooks) | | Interactive Visualizations | `score_visualization` | Serve aggregated data for dashboards/skill maps/matrices. | `services/visualization.py` | | Expertise Classification by Field | `expertise_field_classification` | Bind scores to formal knowledge domains (taxonomy). | `services/expertise.py` | — ### **2\) Backend Functionalities** * **Reputation engine & triggers.** A Django service updates users’ domain‑specific Ekoh scores from platform activity; scheduled Celery jobs perform periodic recalculation, and event hooks apply immediate updates on impactful actions. * **Ethical multiplier.** An ethics score multiplies domain expertise to produce final influence weights (raises for constructive behavior, lowers for flagged behavior). * **Smart‑Vote integration.** Voting across modules (e.g., Ethikos) is weighted by the voter’s relevant Ekoh score; live results may be pushed via Channels. * **Cross‑module APIs.** Provides shared search/notifications/feed/recommendation surfaces that consume Ekoh signals (e.g., leaderboards, relevance). * **Quality controls.** Thresholds and moderation safeguards prevent brigading/spam from distorting reputation and consensus. — ### **3\) Database Models (OLTP)** Canonical tables powering EkoH scoring, ethics, audit, and privacy. | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | `ExpertiseCategory` | Domain taxonomy for expertise classification. | `id`, `name` | | `UserExpertiseScore` | Per‑user per‑domain raw/weighted score. | `id`, `user`, `category`, `raw_score`, `weighted_score` | | `UserEthicsScore` | Per‑user ethical multiplier (applied to expertise). | `user` (PK), `ethical_score` | | `ScoreConfiguration` | Named weights/coefficients (global or per field). | `id`, `weight_name`, `weight_value`, `field` | | `ContextAnalysisLog` | AI context adjustments applied to scores. | `id`, `entity_type`, `entity_id`, `field`, `input_metadata` (JSON), `adjustments_applied` (JSON) | | `ConfidentialitySetting` | User privacy level for identity display near scores. | `user` (PK), `level` (enum: public/pseudonym/anonymous) | | `ScoreHistory` | Full audit trail of score changes. | `id`, `merit_score` (FK), `old_value`, `new_value`, `change_reason` | — ### **4\) Supporting Configuration (frozen)** Finalized parameters for EkoH engine and domain taxonomy. * **Initial axis weights:** `quality=1.000`, `expertise=1.500`, `frequency=0.750` → used by `multidimensional_scoring`. * **Ethical multiplier bounds:** floor `0.20`, cap `1.50`. * **Expertise domains:** `EXPERTISE_DOMAIN_CHOICES` (26 ISO‑based domains; seeded fixtures). — ### **5\) Schedules & runtime** * **Periodic recomputation:** Celery Beat tasks (nightly/interval) to refresh Ekoh scores and any precomputed leaderboards; monitored in CI/ops. * **Realtime delivery:** Optionally push score/leaderboard deltas or weighted results via Django Channels \+ Redis. — ### **Summary** EkoH exposes seven concrete services (`multidimensional_scoring`, `configuration_weights`, `contextual_analysis`, `privacy_settings`, `score_history`, `score_visualization`, `expertise_field_classification`) mapped to Django service modules; it persists expertise/ethics/traceability/privacy via dedicated tables and operates under fixed, reviewable parameters. It is the weighting backbone for Smart‑Vote and cross‑module relevance, with periodic recomputation and optional realtime updates. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Knowledge (Collaborative Learning Library) — sub‑module under KonnectED.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: d31bdf7b591cab7408f9112d149d2deddf9fe1a5aa7a2dc3fd17a7bad9ffcdcd CONTENT_BYTES: 4457 ================================================================================================ **Knowledge (Collaborative Learning Library)** — sub‑module under **KonnectED**. Implements five concrete services with code‑names, backed by specific tables and fixed parameters, and exposed through the **/learn** and **/course/** flows. --- ### **1\) Functional Services (and expected files)** Code‑name → service module mapping follows the v14 inventory convention. | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Collaborative Library | `library_resource_management` | CRUD, classify, and publish library resources; enforce type enums and moderation. | `services/library_resource_management.py` | | Personalized Recommendations | `personalized_recommendation` | Suggest resources per learner profile, usage, and expertise signals. | `services/personalized_recommendation.py` | | Co‑Creation Tools | `content_co_creation` | Real‑time authoring/versioning of lessons and media with contribution workflow. | `services/content_co_creation.py` | | Thematic Forums | `thematic_forum` | Subject‑based discussion boards tied to resources and courses. | `services/thematic_forum.py` | | Learning Progress Tracking | `learning_progress_tracking` | Track per‑user progress and completion across resources/lessons. | `services/learning_progress_tracking.py` | --- ### **2\) Backend Functionalities** * **Library management & contribution.** Resource CRUD with enforced content types, draft/publish states, and per‑user draft caps; surfaced in **/learn**. * **Search & discovery.** Full‑text search over titles/descriptions using the platform’s PostgreSQL tsvector backend; results feed the library listing and global search. * **Recommendations.** Periodic or on‑demand generation of **KnowledgeRecommendation** rows per user; ranking blends popularity, recency, and profile relevance. * **Co‑creation workflow.** Collaborative editing spaces for lessons/media with versioned **CoCreationContribution** entries; authors can iterate before publishing to the library. * **Forums.** Topic and post threads by theme/subject with moderation hooks; linked from resource or course views and listed under **/learn**. * **Progress tracking & player.** The **/course/\[slug\]** player reads/writes **LearningProgress** to drive completion %, resumes, and achievements. * **Offline distribution.** Scheduled packaging of selected knowledge content for low‑connectivity environments. --- ### **3\) Database Models** Custom tables for Knowledge, Co‑Creation, and Forums; plus recommendation/progress records. | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | **KnowledgeResource** | Canonical library item (article, video, lesson, quiz, dataset). | `id`, `title`, `type` *(enum)*, `url`, `author` | | **KnowledgeRecommendation** | Records a recommended resource for a user. | `id`, `user`, `resource`, `recommended_at` | | **LearningProgress** | Per‑user progress for a resource/lesson. | `id`, `user`, `resource`, `progress_percent` *(unique per user+resource)* | | **CoCreationProject** | Collaborative content project container. | `id`, `title`, `status` *(enum)* | | **CoCreationContribution** | Individual draft/edit within a project. | `id`, `project`, `user`, `content` | | **ForumTopic** | Thematic forum thread (subject/question). | `id`, `title`, `category`, `creator` | | **ForumPost** | Post/reply within a topic. | `id`, `topic`, `author`, `content` | --- ### **4\) Supporting Configuration & Routes** * **Allowed content types (enum):** `article`, `video`, `lesson`, `quiz`, `dataset`. * **Draft cap:** `MAX_CONTRIBUTION_DRAFTS = 10` per user. * **Search backend:** `SEARCH_BACKEND = "postgres"` (tsvector). * **Offline packaging schedule:** `OFFLINE_PACKAGE_CRON = 0 3 * * SUN`. * **Navigation:** **/learn** (Catalog, Recommendations, Offline Download) and **/course/\[slug\]** (Course Player: Lessons, Assessments, Progress). --- ### **Summary** Knowledge delivers the learning library and its social layer: resource management, personalized recommendations, collaborative authoring, themed forums, and progress tracking. It provides five named services (`library_resource_management`, `personalized_recommendation`, `content_co_creation`, `thematic_forum`, `learning_progress_tracking`) mapped to Django modules and backed by concrete tables and parameters, integrated with **/learn** and **/course/** UX. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Konservation (Creative Content & Cultural Preservation) — sub‑module under Kreative.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 8e659b5a1b8023676fefe830c48e5a312446797cdd4f2a0442fb8572f70730e1 CONTENT_BYTES: 5664 ================================================================================================ **Konservation (Creative Content & Cultural Preservation)** — sub‑module under **Kreative**. Implements five core services with named code‑functions, backed by dedicated models and frozen parameters. --- ### **1\) Functional Services (and expected files)** Code‑names follow the v14 inventory and map 1:1 to service modules. | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Digital Archives | `digital_archive_management` | Ingest, store, and retrieve digitized artworks and heritage media; handle provenance and rights metadata. | `kreative/services/digital_archive.py` | | Virtual Exhibitions | `virtual_exhibition` | Build interactive online galleries/VR rooms from curated sets; enforce per‑room capacity; publish exhibits. | `kreative/services/virtual_exhibition.py` | | Documentation Base | `archive_documentation` | Manage bios, provenance notes, and supplemental documents attached to artworks/galleries. | `kreative/services/archive_documentation.py` | | AI‑Enriched Catalogue | `ai_enriched_catalogue` | Auto‑classify artworks, generate tags/labels and fill style/medium using ML; writes to tagging/metadata. | `kreative/services/catalogue_ai.py` and `kreative/tasks/ai_enrichment.py` | | Cultural Partners Integration | `cultural_partner_integration` | Import/sync collections from partner museums/heritage systems; map external metadata to local schema. | `kreative/services/partner_integration.py` and `kreative/tasks/partner_ingest.py` | Mapping guidance (“each code name maps to a service module”) per the Functional Code‑Name Inventory. --- ### **2\) Backend Functionalities** * **Artwork & media lifecycle.** Upload, validate, and persist artworks; generate multiple image renditions for fast delivery; enforce upload size and allowed media types. * **Curation & exhibitions.** Curators assemble **Galleries** (ordered sets) and publish **Virtual Exhibitions** with capacity limits per room. * **Tagging & discovery.** Global **Tag** vocabulary with many‑to‑many mapping to artworks; AI service can propose tags and styles. * **Heritage submissions.** Community submits **TraditionEntry** items (media \+ description \+ region) to the archive; moderator approval workflow. * **Rights, privacy, and moderation.** NSFW flag on upload; shared moderation policies across modules; provenance and creator attribution preserved. * **API & stack.** Exposed via Django REST Framework to the Next.js frontend; object storage for media; background workers for image/AI pipelines. --- ### **3\) Database Models (OLTP)** Canonical tables for Konservation content and curation. | Table / Model | Purpose | Key fields (excerpt) | | ----- | ----- | ----- | | `KreativeArtwork` | A single artwork or creative work (image/video/audio/other). | `id`, `artist` (FK User), `title`, `description`, `media_file`, `media_type` (ENUM), `year`, `medium`, `style` | | `Tag` | Global tagging vocabulary reused by artworks (and other content). | `id`, `name` (unique) | | `ArtworkTag` | Join table linking artworks ↔ tags (M2M; unique per pair). | `id`, `artwork` (FK), `tag` (FK) | | `Gallery` | Curated collection or exhibition container. | `id`, `title`, `description`, `created_by` (FK User, nullable), `theme`, `created_at` | | `GalleryArtwork` | Through‑table to place artworks in a gallery with order. | `id`, `gallery` (FK), `artwork` (FK), `order` | | `TraditionEntry` | Cultural heritage submission for long‑term archive. | `id`, `title`, `description`, `region`, `media_file`, `submitted_by` (FK, nullable), `submitted_at`, `approved` (bool), `approved_by` (FK, nullable), `approved_at` | Models live under the Kreative app (e.g., `kreative/models/artwork.py`, `gallery.py`, `tradition.py`). --- ### **4\) Supporting Configuration (frozen)** Operational parameters and invariants affecting Konservation features. * **ARTWORK\_MAX\_IMAGE\_MB:** **50 MB** — upload limit for image media. * **ARTWORK\_RESOLUTIONS:** **\[256, 1024, 2048\]** px — renditions generated on ingest. * **VIRTUAL\_GALLERY\_CAPACITY:** **24 artworks / room** — enforced by `virtual_exhibition`. * **NSFW\_FLAG\_REQUIRED:** boolean (default **False**) — surfaced in upload form and display gates. * **MEDIA\_ROOT:** `/app/media/` — single bucket mount for all modules (shared invariant). --- ### **5\) Routes & Ownership (UI)** Top‑level navigation and page ownership for this sub‑module. * **/kreative** — Creativity Hub (tabs: Gallery, Incubator, Virtual Exhibitions). * **/art/\[id\]** — Artwork Sheet (details, comments, metadata). * **/archive** — Konservation Archive (Heritage, Partners). --- ### **6\) DevOps & Tasks** * **Image pipeline.** Celery task generates `ARTWORK_RESOLUTIONS` on upload; stores renditions alongside originals in object storage. * **AI enrichment.** Scheduled worker applies `ai_enriched_catalogue` to new/updated artworks (tags, style/medium suggestions). * **Partner ingest.** Periodic sync jobs fetch external collections and map metadata via `cultural_partner_integration`. * **Publishing.** Exhibition build step compiles gallery selections into front‑end consumables (JSON descriptors / assets), respecting capacity limits. --- ### **Summary** Konservation provides **digital archiving**, **virtual exhibitions**, **documentation**, **AI‑assisted cataloguing**, and **partner integrations** via the five services above, grounded in the `KreativeArtwork`, `Gallery`, `Tag/ArtworkTag`, and `TraditionEntry` models and governed by fixed upload, rendition, and exhibition parameters. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Konstruct (Project Collaboration Spaces) — first sub‑module under keenKonnect.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: ceb6e1e452c27bf61b9fe8a4a77431aabef8eafc1ae96cf46174e938e32cda63 CONTENT_BYTES: 5401 ================================================================================================ **Konstruct (Project Collaboration Spaces)** — first sub‑module under **keenKonnect**. Implements five core services with concrete code‑names, backed by project/task/chat models and fixed parameters. --- ### **1\) Functional Services (and expected files)** | Display name | Code name / service | Purpose / behavior | Likely file or module | Status | | ----- | ----- | ----- | ----- | ----- | | Virtual Collaboration Spaces | `collaboration_space` | Create/join project rooms with membership, roles, and access rules. | `keenkonnect/services/collaboration_space.py` | Implemented (projects & teams) | | Project Management Tools | `project_task_management` | Tasks, Kanban states, assignees, due dates, and activity logs. | `keenkonnect/services/project_task_management.py` | Implemented (tasks) | | Real‑Time Editing | `real_time_document_editing` | Synchronous co‑editing of docs; conflict resolution (OT/CRDT pattern). | `keenkonnect/services/real_time_document_editing.py` | Planned (MVP uses resource versioning) | | Integrated Chat & Video | `integrated_communication` | Per‑project chat via sockets; optional video sessions via provider. | `keenkonnect/services/integrated_communication.py` | Chat implemented; video wired by env | | AI Collaborative Analysis | `ai_collaboration_analysis` | Live summaries, action suggestions, and collaborator recommendations. | `keenkonnect/services/ai_collaboration_analysis.py` | Implemented (summaries/reco service) | Code‑names and scope are defined in the v14 service inventory. --- ### **2\) Backend Functionalities** * **Project lifecycle & membership.** Create/update/archive projects; manage membership and roles; enforce access on project‑scoped endpoints. * **Tasking.** CRUD tasks with statuses (todo/in‑progress/done/blocked), assignment, due dates, ordering; emits project activity events. * **Resources & blueprints.** Attach documents and 3D assets; optional background conversion/previews for CAD/3D models (e.g., glTF) via worker jobs. * **Collaboration channels.** Real‑time project chat over WebSockets; optional video sessions bound by provider config; rate‑limits and moderation hooks applied. * **Real‑time document editing (MVP).** Until dedicated models land, uses resource versioning plus optimistic locking; planned upgrade to true real‑time persistence. * **AI assistance.** Generate meeting notes, decisions, and next‑actions from chat/tasks; recommend collaborators based on skills/Ekoh domains. --- ### **3\) Database Models (OLTP)** Actual models present in the codebase for Konstruct‑level collaboration; names/purposes below. | Table / Model | Purpose | Key fields (abridged) | | ----- | ----- | ----- | | `Project` | Project workspace container. | `id`, `title`, `description`, `creator`, `category`, `status` | | `ProjectResource` | Files/links attached to a project (incl. blueprints). | `id`, `project`, `title`, `url`, `added_by` | | `ProjectTask` | Tasks/milestones for the project. | `id`, `project`, `title`, `description`, `assignee`, `status`, `due_date` | | `ProjectMessage` | Project chat/message history. | `id`, `project`, `sender`, `content` | | `ProjectTeam` | Membership and roles. | `id`, `project`, `user`, `role`, `joined_at` | | `ProjectRating` | Community validation signal. | `id`, `project`, `user`, `rating`, `comment` | | `Tag` | Reusable keyword taxonomy. | `id`, `name` | **Not present (planned names suggested by docs):** `RealTimeDocument`, `DocumentRevision`, `VideoSession`, `AIInteractionLog`. The schema note explicitly calls these out as missing today. --- ### **4\) Supporting Configuration (frozen)** | Parameter | Location | Final value / notes | | ----- | ----- | ----- | | `MAX_BLUEPRINT_UPLOAD_MB` | `settings.STORAGE` | **150 MB** maximum per file | | `ALLOWED_BLUEPRINT_TYPES` | `ProjectResource` | `[".pdf", ".png", ".jpg", ".glb", ".gltf", ".stl"]` | | `COLLAB_SPACE_MEMBER_CAP` | `CollaborationSpace` | **40** members per space | | `AI_SUGGESTION_TOP_N` | `settings.KEENKONNECT` | **8** collaborator suggestions | | `VIDEO_SESSION_PROVIDER` | env `KC_VIDEO_PROVIDER` | `"livekit"` (self‑hosted) | These parameters are locked in the Global Parameter Reference. --- ### **5\) Routes & UI Surface** * **/projects** → Project Studio (Browse, Create, My Projects). * **/projects/\[slug\]** → Single Workspace with tabs: **Overview**, **Tasks**, **Blueprints**, **Chat**, **AI Insights**, **Settings**. Top‑level routing invariants assign these paths to the keenKonnect app. --- ### **6\) Runtime & real‑time** * **WebSockets:** Django Channels \+ Redis for chat/notifications; project‑scoped groups per workspace. * **File storage:** Object storage (S3/MinIO) for blueprints; optional preview/convert workers for 3D assets. * **Video:** Session bootstrap via the configured provider (`KC_VIDEO_PROVIDER`). --- ### **Summary** Konstruct exposes five services—`collaboration_space`, `project_task_management`, `real_time_document_editing`, `integrated_communication`, `ai_collaboration_analysis`—implemented over the `Project`, `ProjectTask`, `ProjectMessage`, `ProjectTeam`, `ProjectResource`, `ProjectRating`, and `Tag` models, with fixed size/type/member caps and dedicated routes under `/projects`. Real‑time editing is currently backed by resource versioning, with dedicated models planned. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Konsultations (Public Consultations & Feedback) — sub‑module under ethiKos.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: ebb0219cb85e6e9dbe566b32239be0df3ef104b75971c7317d621c4811ab2f36 CONTENT_BYTES: 4664 ================================================================================================ **Konsultations (Public Consultations & Feedback)** — sub‑module under **ethiKos**. Implements five core services with stable code‑names, backed by consultation/suggestion/vote/result/impact models and frozen routing/analytics invariants. --- ### **1\) Functional Services (and expected files)** Code‑names map 1:1 to Django service modules; file names follow the `services/<code_name>.py` convention. | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Public Consultations | `public_consultation` | Create and run time‑boxed civic consultations (setup, schedule, close). | `services/public_consultation.py` | | Citizen Suggestions | `citizen_suggestion` | Intake pipeline for user‑proposed ideas/amendments feeding into consultations. | `services/citizen_suggestion.py` | | Weighted Voting (EkoH) | `weighted_consultation_vote` | Cast ballots with optional EkoH‑based weighting; aggregates to results. | `services/weighted_consultation_vote.py` | | Results Visualization | `consultation_result_visualization` | Compute/serve KPIs and breakdowns for dashboards. | `services/consultation_result_visualization.py` | | Impact Tracking | `impact_tracking` | Log follow‑up actions and implementation status for adopted proposals. | `services/impact_tracking.py` | --- ### **2\) Backend functionalities** * **Consultation lifecycle.** CRUD for consultations with scheduling (open/close) and status transitions; business rules on who can launch/manage, exposed via DRF. * **Suggestion intake → consultation.** Users submit suggestions; moderators/owners triage and link them to an active consultation or backlog for future cycles. * **Ballots with weighting.** Store raw and EkoH‑weighted ballot values per user/consultation; recompute totals on each vote/change; optional live push via Channels/Redis. * **Results & dashboards.** Persist snapshot JSONs for totals/segments; serve aggregates to the UI and to the analytics pipeline. * **Impact follow‑through.** Record action items that implement approved proposals; status progression and audit trail. --- ### **3\) Database models (OLTP)** Actual tables implemented for Konsultations. | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | `Consultation` | A consultation instance (time‑boxed). | `id`, `title`, `open_date`, `close_date`, `status` (ENUM) | | `CitizenSuggestion` | User‑submitted ideas tied to a consultation. | `id`, `consultation` (FK), `author` (FK), `content` | | `ConsultationVote` | Ballots with raw and EkoH‑weighted values. | `id`, `user` (FK), `consultation` (FK), `raw_value`, `weighted_value` | | `ConsultationResult` | Aggregated outcomes (snapshot). | `id`, `consultation` (FK), `results_data` (JSONB) | | `ImpactTrack` | Post‑consultation action log. | `id`, `consultation` (FK), `action`, `status`, `date` | --- ### **4\) Supporting configuration (frozen)** * **Ballot modalities** (available to consultations via Smart Vote): `approval`, `ranking`, `rating`, `preferential`. * **Smart‑Vote thresholds** (used when labeling outcomes, platform‑wide): e.g., `CONSENSUS_STRONG_THRESHOLD ≥ 75%` weighted agreement. * **Route invariants:** `/consult` namespace is owned by **ethiKos** (no other module may claim it). --- ### **5\) Routes & ownership** * **Primary UI:** `/consult` (**Consultation Hub**) with tabs **Live / Results / Suggest**. * **Analytics:** `/ethikos/insights` for opinion analytics related to debates/consultations (read‑only). --- ### **6\) Integration points** * **EkoH weighting & Smart Vote.** Consultation ballots can use the same reputation‑weighted engine as debates; results reflect domain expertise where configured. * **Insights (ETL \+ dashboards).** Voting events flow to the analytics star schema via `etl_smart_vote` (every 10 min) and power `/reports/smart-vote`. --- ### **7\) Realtime & ops** * **Live updates:** Optional push of result deltas via Django Channels \+ Redis. * **Caching:** Use Redis to cache popular result filters/segments to reduce recomputation. --- **Summary** Konsultations provides time‑boxed consultations, suggestion intake, EkoH‑weighted ballots, and transparent result snapshots through five services (`public_consultation`, `citizen_suggestion`, `weighted_consultation_vote`, `consultation_result_visualization`, `impact_tracking`). Data persists in `Consultation`, `CitizenSuggestion`, `ConsultationVote`, `ConsultationResult`, and `ImpactTrack`; routing is fixed at `/consult`, and analytics integrate with the platform’s Smart‑Vote ETL and dashboards. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Kontact (Collaboration & Networking) — sub‑module under Kreative.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: cf3b050bc4b419a986505dab954a53de7130301638abb7acd7aa3d5cd0b7193f CONTENT_BYTES: 4628 ================================================================================================ **Kontact (Collaboration & Networking)** — sub‑module under **Kreative**. Implements **five core services** with stable code‑names and module ownership under the `/connect` and `/profile/[user]` routes. --- ### **1\) Functional Services (and expected files)** Code‑names are canonical; each maps 1:1 to a Django service module consumed by DRF views and Celery tasks. | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Professional Profiles | `professional_profile` | Rich public profiles for creators/diffusers: bio, skills, portfolio links; integrates artwork and tags for discovery. | `kreative/services/professional_profile.py` | | Intelligent Matching | `intelligent_matching` | Recommends people to follow/contact or invite into collaborations based on skills, tags, and activity signals (Ekoh context optional). | `kreative/services/intelligent_matching.py` | | Collaboration Workspaces | `collaboration_workspace` | Lightweight networking‑context rooms (chat/notes/canvas) to meet, plan, and co‑create; reuses real‑time infra. | `kreative/services/collaboration_workspace.py` | | Opportunities Board | `opportunity_announcement` | Post/browse residencies, exhibitions, calls, jobs; searchable by tags, region, dates. | `kreative/services/opportunity_announcement.py` | | Reviews & Endorsements | `partner_recommendation` | Post‑engagement endorsements/ratings to establish trust and reputation between collaborators/hosts. | `kreative/services/partner_recommendation.py` | --- ### **2\) Backend Functionalities** * **Profiles & portfolios.** Exposes read/write APIs for creator profiles, linking to existing creative assets (artworks, tags) for rich portfolios and searchability. * **People matching.** `intelligent_matching` ranks suggested contacts via skills/tags overlap and activity; tunable top‑N, and optional Ekoh/Smart‑Vote signals when relevant. * **Real‑time meetups.** `collaboration_workspace` provisions ephemeral rooms (DM/group), built on the same Channels/Redis stack used elsewhere; participant cap enforced at runtime. * **Opportunity lifecycle.** `opportunity_announcement` provides CRUD for postings (type, location, dates, attachments), listing/search, and status (open/closed/filled). * **Trust signals.** `partner_recommendation` lets collaborators leave structured endorsements after a workspace or engagement concludes; surfaced on profile pages. * **Routes & ownership.** UI/API bound to **/connect** (People, Opportunities, Workspace) and **/profile/\[user\]** (public profile), per navigation invariants. --- ### **3\) Database Models** The database reference explicitly lists the **CollabSession** table under Kreative/Kontact. Profiles, opportunities, and endorsements use existing/core objects and Kontact app models not enumerated in that reference. | Table / Model | Purpose | Key fields (excerpt) | | ----- | ----- | ----- | | `CollabSession` | Real‑time collaborative session (networking/co‑creation room). | `id`, `name`, `host (FK User)`, `session_type (ENUM)`, `started_at`, `ended_at`, `final_artwork (FK KreativeArtwork, nullable)` | | *(Reused)* `KreativeArtwork` | Portfolio items surfaced on profiles (read‑only in Kontact). | `id`, `artist (FK)`, `title`, `media_file`, `media_type`, `style` | | *(Reused)* `Tag` / `ArtworkTag` | Skills/genre tags used for discovery/matching. | `Tag.name (unique)`; `ArtworkTag (artwork, tag)` | *Note:* Only `CollabSession` is listed under Kontact in the v14 schema reference; other Kontact records (profiles, opportunities, recommendations) are implemented at the app level and/or reuse core tables. --- ### **4\) Supporting Configuration** Fixed parameters and route invariants that affect Kontact behavior. * **COLLAB\_CANVAS\_MAX\_USERS:** **6** simultaneous editors in a real‑time room. * **MEDIA\_ROOT:** `/app/media/` for attachments (shared across modules). * **Routes reserved:** `/connect`, `/profile/[user]` owned by Kreative/Kontact; additional nested tabs do not create new top‑level routes. --- ### **Summary** Kontact delivers networking‑centric capabilities via five services — `professional_profile`, `intelligent_matching`, `collaboration_workspace`, `opportunity_announcement`, `partner_recommendation` — integrated with the Kreative domain and routed under `/connect` and `/profile/[user]`. Data persists primarily through `CollabSession` and reused creative/Tag tables; real‑time rooms and matching leverage the platform’s DRF \+ Channels \+ Redis stack and frozen configuration. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Korum (Structured Debates) — sub‑module under ethiKos.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 61ae3dc9ba9a84a0b0334fb7ea4255af53c59c1c628134fca037cdfaaa573417 CONTENT_BYTES: 4503 ================================================================================================ **Korum (Structured Debates)** — sub‑module under **ethiKos**. Implements five core services with defined code‑names, backed by concrete debate/stance/argument models and fixed parameters. --- ### **1\) Functional Services (and expected files)** Each service name is stable and maps to a dedicated Django service module (file paths reflect the cookiecutter layout; exact filenames may vary by repo). | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Structured Debates | `structured_debate` | Create and manage ordered debate sequences and topics. | `ethikos/services/structured_debate.py` | | Klônes IA | `ai_clone_management` | Manage AI expert‑emulating agents for continuity/testing. | `ethikos/services/ai_clone_management.py` | | Comparative Analysis | `comparative_argument_analysis` | Compare arguments to surface convergences/divergences. | `ethikos/services/comparative_argument_analysis.py` | | Public Archiving | `public_debate_archive` | Produce immutable debate snapshots for transparency. | `ethikos/services/public_debate_archive.py` | | Automated Summaries | `automated_debate_summary` | Generate concise, structured debate outcome digests. | `ethikos/services/automated_debate_summary.py` | --- ### **2\) Backend functionalities** * **Debate lifecycle:** CRUD for topics with status transitions (open/closed/archived), category assignment, and owner/moderation rules; exposed via DRF. * **Threaded arguments:** Nested replies under each topic with optional “pro/con” flag and moderation hooks. * **Nuanced stance capture:** Integer stance scale −3…+3 per user/topic; integrates with Smart Vote for weighted aggregation. * **Weighted results & cohorts:** Results recomputed by expertise cohorts (EkoH) and other filters; realtime push optional via Channels/Redis. * **Quality & moderation:** Report/auto‑hide thresholds; flagged content routed to shared moderation queue. --- ### **3\) Database models (OLTP)** Actual implemented tables for Korum (planned AI/summary/archive tables are intentionally omitted in v14). | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | `EthikosCategory` | Thematic categories for debates. | `id`, `name`, `description` | | `EthikosTopic` | Debate topic/question. | `id`, `title`, `status`, `start_date`, `end_date` | | `EthikosStance` | User stance on a topic (−3…+3). | `id`, `topic` (FK), `user` (FK), `value` | | `EthikosArgument` | User argument/post (threaded). | `id`, `topic` (FK), `author` (FK), `content`, `parent` (FK), `side` (enum, optional) | Note: AI clones, comparative‑analysis logs, public archives, and debate summaries are listed as services but not present as tables in the current schema snapshot. --- ### **4\) Supporting configuration (frozen)** * **Stance scale:** −3 … \+3 (0 \= neutral). * **Expert cohort quorum (display):** 12 distinct experts (Ekoh threshold per domain). * **Moderation auto‑hide:** Hide an argument after 3 independent reports. * **AI clone training batch:** 128 records. --- ### **5\) Frontend & navigation** * **Routes:** `/debate` (Debate Hub: Open / Archived / Start New), `/ethikos/insights` (opinion analytics dashboards). * **Behavior:** Stance slider (−3…+3), live tallies, cohort filters, threaded arguments; analytics readouts live under Insights. --- ### **6\) Integration points** * **EkoH & Smart Vote:** Stances are aggregated using EkoH reputation to compute weighted results; outcomes can feed analytics (/reports/smart‑vote). * **Insights module:** ETL ingests vote/stance facts; dashboards render trends with export limits and privacy safeguards (k‑anonymity, hashed IDs). --- ### **7\) Realtime & ops** * **Push updates:** Optional WebSocket broadcasts via Django Channels \+ Redis for stance/result changes. * **Caching & rate control:** Use Redis caching for common cohort filters; apply API throttles consistent with platform policy. --- ### **Summary** Korum provides structured topic management, nuanced stance capture, and threaded argumentation, with weighted consensus via EkoH/Smart Vote. Its five named services are stable integration points; the production schema covers categories, topics, stances, and arguments, while advanced AI/archive features run as services without additional OLTP tables in v14. Routes and parameters are version‑locked to ensure predictable behavior across UI, API, and analytics. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Smart Vote (Weighted Voting System) — second sub‑module under Kollective Intelligence.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 903fe4ccb3692289fc87b21039dfb4e52adf5b46f43dd6c2271d339bbc0e8dff CONTENT_BYTES: 4299 ================================================================================================ **Smart Vote (Weighted Voting System)** — second sub‑module under **Kollective Intelligence**. Implements six core services with explicit code‑names, backed by vote/aggregation models, global parameters, and analytics pipelines. --- ### **1\) Functional Services (and expected files)** | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Dynamic Weighted Voting | `dynamic_weighted_vote` | Re‑weights each vote in real time using the voter’s EkoH domain weight. | `services/dynamic_weighted_vote.py` | | Flexible Voting Modalities | `voting_modalities` | Supports approval, ranking, rating, preferential ballots; modality parameters drive tally logic. | `services/voting_modalities.py` | | Emerging Expert Detection | `emerging_expert_detection` | Flags users whose EkoH score is rising sharply to surface new experts. | `tasks/emerging_expert_detection.py` | | Transparency of Results | `vote_transparency` | Publishes raw and weighted totals with context (no private data). | `services/vote_transparency.py` | | Advanced Result Visualizations | `vote_result_visualization` | Produces histograms, distributions, network graphs for outcomes. | `services/vote_result_visualization.py` | | Cross‑Module Integration | `cross_module_vote_integration` | Makes Smart Vote available across modules (e.g., debates, content, projects). | `services/cross_module_vote_integration.py` | --- ### **2\) Backend Functionalities** * **Vote intake & aggregation.** API records a per‑user vote on a target (`target_type`, `target_id`), applies EkoH‑weighted scoring, and updates an aggregated result object; concurrency‑safe updates with immediate read‑back for live UIs. * **Modalities engine.** Aggregation logic switches by `VoteModality` parameters (approval/rating/ranking/preferential); modality configuration stored and read at runtime. * **Realtime delivery.** Updated tallies pushed via Django Channels \+ Redis for live dashboards and pages displaying current consensus. * **Cohort/segment views.** Aggregator exposes filtered outcomes (e.g., experts‑only, verified‑only) when the calling module requests segmented results. * **Cross‑module linkage.** Generic mapping allows any app entity to become a vote target (e.g., debates, consultations, projects). --- ### **3\) Database Models (OLTP)** | Table / Model | Purpose | Key fields | | ----- | ----- | ----- | | `Vote` | Stores each user vote (raw value \+ weighted value). | `id`, `user`, `target_type`, `target_id`, `raw_value`, `weighted_value` | | `VoteModality` | Config for voting modes (approval, ranking, rating, preferential). | `id`, `name`, `parameters` (JSON) | | `EmergingExpert` | Flags users with sharp reputation gains. | `id`, `user`, `detection_date`, `score_delta` | | `VoteResult` | Aggregated totals per target (cumulative weighted sums \+ counts). | `id`, `target_type`, `target_id`, `sum_weighted_value`, `vote_count` | | `IntegrationMapping` | Cross‑module link from vote context to other modules’ objects. | `id`, `module_name`, `context_type`, `mapping_details` (JSON) | --- ### **4\) Supporting Configuration (frozen)** * **Vote modalities:** `"approval" | "ranking" | "rating" | "preferential"` (`VOTE_MODALITY_CHOICES`). * **Emerging expert threshold:** `+15%` EkoH delta over 30 days. * **Strong consensus threshold:** `≥ 75%` weighted agreement. --- ### **5\) Schedules, Analytics & Runtime** * **Realtime channel layer:** `channels_redis.core.RedisChannelLayer` used for live result pushes. * **Analytics ETL:** `etl_smart_vote` runs every **10 minutes** to load OLTP deltas into `smart_vote_fact`; retention **5 years**; cached views power `/reports/smart-vote`. * **UI surfaces:** * **Konsensus Center** (end‑user portal with live polls/results): `/konsensus`. * **Insights dashboard (read‑only analytics):** `/reports/smart-vote`. --- ### **Summary** Smart Vote provides modality‑aware, EkoH‑weighted voting with real‑time aggregation, transparent reporting, and cross‑module targeting. Its models (`Vote`, `VoteModality`, `VoteResult`, `EmergingExpert`, `IntegrationMapping`), frozen parameters, and analytics pipelines make it the consensus backbone across the platform. ================================================================================================ FILE: docs/Technical-Reference/sub-modules_description/Stockage (Secure Repository & Versioned Storage) — second sub‑module under keenKonnect.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 202621aacc3a8d0dd78e3305d922cdd0dbbf1cf30a676be6ca911bcb9c95bee3 CONTENT_BYTES: 5014 ================================================================================================ **Stockage (Secure Repository & Versioned Storage)** — second sub‑module under **keenKonnect**. Implements five services with defined code‑names, backed by project‑scoped resource models and fixed storage/search parameters. --- ### **1\) Functional Services (and expected files)** Code‑names come from the v14 services inventory; each maps to a Django service module imported by API controllers and Celery tasks. | Display name | Code name / service | Purpose / behavior | Likely file or module | | ----- | ----- | ----- | ----- | | Secure Repository | `secure_document_storage` | Persist files with authenticated access and per‑project visibility. | `apps/keenkonnect/services/secure_storage.py` | | Automatic Versioning | `document_versioning` | Maintain sequential revisions; enable diff/rollback semantics. | `apps/keenkonnect/services/document_versioning.py` | | Intelligent Indexing | `intelligent_indexing` | Extract metadata/keywords; update full‑text search index. | `apps/keenkonnect/services/indexing.py` | | Real‑Time Sync | `real_time_sync` | Broadcast file add/update/delete to active collaborators. | `apps/keenkonnect/services/real_time_sync.py`, `apps/keenkonnect/channels/consumers.py` | | Fine‑Grained Permissions | `granular_permissions` | Enforce document‑level ACLs beyond project roles. | `apps/keenkonnect/services/permissions.py` | --- ### **2\) Backend Functionalities** * **Upload & storage pipeline.** Accept files under an explicit size/type policy; persist metadata and storage URL on the `ProjectResource` table; store blobs in the configured media bucket (S3/MinIO). * **Versioning semantics.** Expose create‑new‑revision, list revisions, restore, and compute diffs via `document_versioning`. The Database Reference documents `ProjectResource` as the current file record; dedicated version entities are not detailed there and can be added alongside this service. * **Indexing & search.** On upload/update, `intelligent_indexing` extracts text/keywords and refreshes the platform’s PostgreSQL full‑text index (SEARCH\_BACKEND=“postgres”), enabling global search and in‑workspace filtering. * **Access control.** Enforce read/write/admin by project membership (`ProjectTeam`) and, where required, per‑document ACL through `granular_permissions`. Current schema formalizes project‑level roles; document‑level ACL tables are not enumerated in the v14 schema file. * **Real‑time notifications.** `real_time_sync` uses Django Channels over Redis to push “file added/updated/removed” events to clients in `/projects/[slug]` workspaces. --- ### **3\) Database Models** Stockage persists file metadata as project resources; project membership governs default access. | Table / Model | Purpose | Key fields (abridged) | | ----- | ----- | ----- | | `ProjectResource` | Link a document/file (blueprint, image, 3D model, guide) to a project. | `id`, `project`, `title`, `url`, `added_by`, timestamps | | `Project` | Workspace container for resources and collaboration. | `id`, `title`, `description`, `creator`, `category`, `status` | | `ProjectTeam` | Membership & role for access control. | `id`, `project`, `user`, `role`, `joined_at` | | `Tag` | Reusable keywords for classification (optional). | `id`, `name` | *Notes.* The schema file does not list dedicated version/ACL tables for documents; if `document_versioning`/`granular_permissions` introduces them, add to the canonical schema alongside `ProjectResource`. --- ### **4\) Supporting Configuration (frozen)** * **File size cap:** `MAX_BLUEPRINT_UPLOAD_MB = 150`. * **Allowed types:** `[".pdf", ".png", ".jpg", ".glb", ".gltf", ".stl"]`. * **Search backend:** `SEARCH_BACKEND = "postgres"` (tsvector indexing). * **Realtime layer:** Channels backend \= `channels_redis.core.RedisChannelLayer`. * **Media root/bucket:** `MEDIA_ROOT=/app/media/` (object storage mount used across modules). --- ### **5\) Routes & UI Surface** * Users access Stockage features inside project workspaces: **/projects** and **/projects/\[slug\] → “Blueprints” tab** for uploads, previews, version/history, and permissions UI. Route ownership lives with keenKonnect. --- ### **6\) Runtime & Real‑Time** * **Object storage & previews.** Files live in the media bucket; optional workers can generate previews/conversions (e.g., glTF thumbnails) per the technical spec’s storage guidance. * **WebSockets.** Document events publish to project channel groups so collaborators see updates without refresh. --- ### **Summary** Stockage provides `secure_document_storage`, `document_versioning`, `intelligent_indexing`, `real_time_sync`, and `granular_permissions`. Today’s schema centers on `ProjectResource` within `/projects/[slug]` workspaces, governed by `ProjectTeam` roles, with search on PostgreSQL tsvectors and real‑time updates via Channels/Redis. Version and per‑document ACL tables can be added when those services move from interface to implementation. ================================================================================================ FILE: docs/Technical-Reference/UpdateBackendAndMigrateAndDocker.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 4b96c448ec8242bf561cf6832415a8efa51a5703013daa27218691ac50ad8726 CONTENT_BYTES: 2015 ================================================================================================ # Reference: Backend Update & Database Migration Workflow **Target Environment:** Docker (using `docker-compose.local.yml`) **Framework:** Django **Shell:** PowerShell (Windows) This document outlines the required operational steps to apply changes to the backend data models and update the running environment. ### 1\. Build and Start Services When backend code or dependencies change, the containers must be rebuilt to reflect the new state. * **Command:** ```powershell docker-compose -f docker-compose.local.yml up -d --build ``` * **Purpose:** Rebuilds the Docker images (installing any new Python requirements) and starts the services in detached mode. ### 2\. Generate Migrations Django must detect changes in `models.py` and create the corresponding migration files. * **Command:** ```powershell docker-compose -f docker-compose.local.yml run --rm django python manage.py makemigrations ``` * **Purpose:** Scans the codebase for model changes and creates new files in the `migrations/` directories. ### 3\. Apply Migrations The generated migration files must be applied to the PostgreSQL database to update the schema. * **Command:** ```powershell docker-compose -f docker-compose.local.yml run --rm django python manage.py migrate ``` * **Purpose:** Executes the SQL required to synchronize the database schema with the current model state. ### 4\. Verify Service Status Ensure the Django application is running correctly after updates. * **Command:** ```powershell docker-compose -f docker-compose.local.yml ps ``` * **Purpose:** Lists running containers. The `django` container should have a status of `Up`. ### 5\. (Optional) Create Superuser If the database was reset or a new admin is required. * **Command:** ```powershell docker-compose -f docker-compose.local.yml run --rm django python manage.py createsuperuser ``` * **Purpose:** Creates an administrative user for accessing the Django Admin panel. ================================================================================================ FILE: frontend/app/ethikos_20260903_132014_Dump/00_START_HERE.instructions.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 16682ce56457cf5a9a190d1045558de40e7218ece27bde2c2cb3f49c2a449bff CONTENT_BYTES: 2792 ================================================================================================ # START HERE — Instructions for AI You are given a repository codedump split into multiple volume files. ## Goal Answer questions by opening the minimum necessary content. ## Format notes - Use `==== FILE_INDEX ====` first in each volume. - Search for `ENTRY` lines to locate file metadata quickly. - Then jump to `----- FILE BEGIN -----` with matching `path="..."`. - For large files, prefer `--- CHUNK BEGIN ---` blocks. ## AI navigation features When available, use these sections before reading full files: - `FILE DETAIL INDEX`: find exact file metadata, volume, line range, chunk ranges, and summary. - `SYMBOL INDEX`: locate classes, functions, and methods directly. - `IMPORT INDEX`: inspect dependencies before expanding to related files. - `PATCH TARGETS`: identify likely files to modify for common change types. - `line_ref`: full line range for a file. - `chunk_refs`: smaller line ranges for large files. Navigation rule: 1. Start from the master index if present. 2. Use `SYMBOL INDEX` when looking for a class, function, or method. 3. Use `IMPORT INDEX` when tracing dependencies. 4. Use `FILE DETAIL INDEX` to choose the smallest relevant file or chunk range. 5. Read only the needed file or chunk content. ## How to navigate this dump 1) Open `Code_snapshot_ethikos.zip` (single upload archive), then use `CODE_SNAPSHOT_MANIFEST.md` or the repository-relative paths to find the source file you need. Optional: use `Index.txt` to locate the relevant volume faster. 2) Pick the relevant volume file. 3) Use the per-volume index section to locate the path. 4) Read the exact file content or required chunks only. 5) Expand cautiously through imports, calls, or routes, 1–2 hops unless needed. ## Rules - Do NOT try to read the entire dump. - Prefer the master index, file indexes, summaries, and chunk references before opening full files. - Prefer docs, diagrams, and generated indexes when present. - When answering, cite file paths and the volume filename. - Preserve clean source content when copying code; ignore physically numbered lines unless line citations are needed. ## Files - Instructions this file: `00_START_HERE.instructions.md` - Master index: `Index.txt` - Volumes: - ethikos_20260903_132014_01_ROOT.txt — ROOT FILES - ethikos_20260903_132014_02_deliberate.txt — FOLDER: deliberate - ethikos_20260903_132014_03_decide.txt — FOLDER: decide - ethikos_20260903_132014_04_admin.txt — FOLDER: admin - ethikos_20260903_132014_05_pulse.txt — FOLDER: pulse - ethikos_20260903_132014_06_trust.txt — FOLDER: trust - ethikos_20260903_132014_07_impact.txt — FOLDER: impact - ethikos_20260903_132014_99_OTHERS.txt — OTHERS (Misc Folders) ## ChatGPT upload helper - Single upload archive: `Code_snapshot_ethikos.zip` ================================================================================================ FILE: frontend/README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 98131c561b9e7650a5e3e7779b1a79478563fc5e74249ea7ac1a8d1331a0c9ce CONTENT_BYTES: 6139 ================================================================================================ # [Next.js Enterprise Boilerplate](https://blazity.com/open-source/nextjs-enterprise-boilerplate) A production-ready template for building enterprise applications with Next.js. This boilerplate provides a solid foundation with carefully selected technologies and ready-to-go infrastructure to help you develop high-quality applications efficiently. ## Motivation While most Next.js boilerplates focus on individual developer needs with excessive complexity, **next-enterprise** prioritizes strategic simplicity for enterprise teams. It offers a streamlined foundation with high-impact features that maximize developer productivity and accelerate time-to-market for business-critical applications. <a href="https://blazity.com/"> <picture> <source media="(prefers-color-scheme: dark)" srcset="/assets/blazity-logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="/assets/blazity-logo-light.svg"> <img alt="Logo" align="right" height="80" src="/assets/blazity-logo-light.svg"> </picture> </a> > [!NOTE] > **Blazity** is a group of Next.js architects. We help organizations architect, optimize, and deploy high-performance Next.js applications at scale. Contact us at [contact@blazity.com](https://blazity.com) if you’d like to talk about your project. ## Documentation There is a separate documentation that explains its functionality, highlights core business values and technical decisions, provides guidelines for future development, and includes architectural diagrams. We encourage you to [visit our docs (docs.blazity.com)](https://docs.blazity.com) to learn more ## Integrated features ### Boilerplate With this template you will get all the boilerplate features included: * [Next.js 15](https://nextjs.org/) - Performance-optimized configuration using App Directory * [Tailwind CSS v4](https://tailwindcss.com/) - Utility-first CSS framework for efficient UI development * [ESlint 9](https://eslint.org/) and [Prettier](https://prettier.io/) - Code consistency and error prevention * [Corepack](https://github.com/nodejs/corepack) & [pnpm](https://pnpm.io/) as the package manager - For project management without compromises * [Strict TypeScript](https://www.typescriptlang.org/) - Enhanced type safety with carefully crafted config and [ts-reset](https://github.com/total-typescript/ts-reset) library * [GitHub Actions](https://github.com/features/actions) - Pre-configured workflows including bundle size and performance tracking * Perfect Lighthouse score - Optimized performance metrics * [Bundle analyzer](https://www.npmjs.com/package/@next/bundle-analyzer) - Monitor and manage bundle size during development * Testing suite - [Jest](https://jestjs.io/), [React Testing Library](https://testing-library.com/react), and [Playwright](https://playwright.dev/) for comprehensive testing * [Storybook](https://storybook.js.org/) - Component development and documentation * Advanced testing - Smoke and acceptance testing capabilities * [Conventional commits](https://www.conventionalcommits.org/) - Standardized commit history management * [Observability](https://opentelemetry.io/) - Open Telemetry integration * [Absolute imports](https://nextjs.org/docs/advanced-features/module-path-aliases) - Simplified import structure * [Health checks](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) - Kubernetes-compatible monitoring * [Radix UI](https://www.radix-ui.com/) - Headless components for customization * [CVA](http://cva.style/) (Class Variance Authority) - Consistent design system creation * [Renovate BOT](https://www.whitesourcesoftware.com/free-developer-tools/renovate) - Automated dependency and security updates * [Patch-package](https://www.npmjs.com/package/patch-package) - External dependency fixes without compromises * Component relationship tools - Graph for managing coupling and cohesion * [Semantic Release](https://github.com/semantic-release/semantic-release) - Automated changelog generation * [T3 Env](https://env.t3.gg/) - Streamlined environment variable management ### Infrastructure & deployments #### Vercel Easily deploy your Next.js app with [Vercel](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=github&utm_campaign=next-enterprise) by clicking the button below: [![Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/Blazity/next-enterprise) #### Custom cloud infrastructure **next-enterprise** offers dedicated infrastructure as code (IaC) solutions built with Terraform, designed specifically for deploying Next.js applications based on our extensive experience working with enterprise clients. Learn more in our [documentation (docs.blazity.com)][docs] how to quickstart with the deployments using simple CLI. #### Available cloud providers and theirs features: * **AWS (Amazon Web Services)** * Automated provisioning of AWS infrastructure * Scalable & secure setup using: * VPC - Isolated network infrastructure * Elastic Container Service (ECS) - Container orchestration * Elastic Container Registry (ECR) - Container image storage * Application Load Balancer - Traffic distribution * S3 + CloudFront - Static asset delivery and caching * AWS WAF - Web Application Firewall protection * Redis Cluster - Caching * CI/CD ready - Continuous integration and deployment pipeline *... more coming soon* ### Team & maintenance **next-enterprise** is backed and maintained by [Blazity](https://blazity.com), providing up to date security features and integrated feature updates. #### Active maintainers - Igor Klepacki ([neg4n](https://github.com/neg4n)) - Open Source Software Developer - Tomasz Czechowski ([tomaszczechowski](https://github.com/tomaszczechowski)) - Solutions Architect & DevOps - Jakub Jabłoński ([jjablonski-it](https://github.com/jjablonski-it)) - Head of Integrations #### All-time contributors [bmstefanski](https://github.com/bmstefanski) ## License MIT [docs]: https://docs.blazity.com/next-enterprise/deployments/enterprise-cli ================================================================================================ FILE: README.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: a90f1f2903709a31b4521234ab30e5c0ed38cb8cf397529ef62c0f7d164bf230 CONTENT_BYTES: 10017 ================================================================================================ # Konnaxion Konnaxion is a socio-technical framework for coordinating people, knowledge, and action through a clear, ethical, and modular civic architecture. It follows the KOA model (KonnectED, Ethikos, Kreative, keenKonnect, EkoH, Smart Vote) and aims to connect learning, collaboration, debate, and culture, while adding domain- and ethics-aware weighting (EkoH + Smart Vote) so decisions and rankings can be read both as raw crowd signals and as expertise-sensitive views. Konnaxion is a socio-technical framework for coordinating people, knowledge, and action through a clear, ethical, and modular civic architecture. Its foundations follow the KOA model (KonnectED, Ethikos, Kreative, keenKonnect, EkoH, Smart Vote), whose full functional tree is detailed in the system document. Alongside its technical architecture, Konnaxion includes a fictional origin mythology introduced in **Konvergence** and expanded through a series of YouTube videos. This mythos presents a symbolic narrative of how a civic system can emerge in times of turbulence and transformation. --- ## Current maturity & release status **Current status:** Advanced Functional Beta — Final Release Candidate Qualification **Engineering maturity:** ~92% **Release Candidate readiness:** ~86–90% **Current release line:** `v0.8.0` **Latest confirmed tag:** `v0.8.0-beta.2` **Recommended next checkpoint:** `v0.8.0-rc.1` Konnaxion’s core civic-decision slice is now strongly qualified locally: - ethiKos → EkoH → Smart Vote delivery workflow: **GREEN** - Next.js production build: **GREEN** - Django checks and migration state: **GREEN** - Smart Vote schema and real reading runtime: **GREEN** - EkoH targeted browser smoke: **GREEN** - local Docker/runtime hardening: **GREEN** The main remaining work before production promotion is operational rather than core-product functionality: - fresh VPS / Linux security qualification; - production secret rotation; - clean-target deployment reproducibility; - backup → isolated restore → validation drill. Some secondary product surfaces remain explicitly **preview, read-only, placeholder, or deferred** where no complete backend contract exists yet. These placeholders are intentionally retained rather than being replaced by fabricated persistence or fake success states. > The project is entering Release Candidate qualification, but the current code should not yet be described as a final production release. ## Mythological Origins Konnaxion’s fictional foundation appears in the **Konvergence** universe, where symbolic events, archetypes, and narrative structures illuminate the forces that shape collective intelligence. Extended worldbuilding is presented through the following YouTube playlists and videos: - https://www.youtube.com/watch?v=Hh6R8k7Xny4&list=PLLBzJ-PjZQP5ByokC3BYBsLIIzn21Ltaw - https://www.youtube.com/watch?v=-g6EOGPfbOY&list=PLLBzJ-PjZQP6YMA4wDzL_wmTZfiXdofrt&index=16 - https://www.youtube.com/watch?v=JgSh8syza0g&list=PLLBzJ-PjZQP6YMA4wDzL_wmTZfiXdofrt&index=15 - https://youtu.be/BgtqbQ65wic This mythology serves as an imaginative lens that complements the system’s civic functions and long-term vision. --- ## ️Purpose & Vision Konnaxion advances civic coordination through: - structured knowledge ecosystems - meaningful participation and constructive deliberation - transparent decision-making - merit-sensitive evaluation models - culturally enriched collaboration - shared digital spaces and cooperative workflows Each component is designed to operate independently or as part of a larger integrated civic ecosystem. --- ## Access & how to try (placeholder) Konnaxion is in Release Candidate qualification and is not yet exposed as a public demo instance. This section will be updated with: - the URL of a **public Konnaxion demo** and demo accounts; - how organisations can request a **pilot instance** (city, ministry, school system, NGO, etc.); - instructions for developers who want to **run a local stack** (services to start, commands, sample data). Until those paths are formalised, this repository and the wiki focus on **architecture, modules, and concepts** rather than end-user onboarding. --- ## System Architecture The Konnaxion architecture consists of six major modules, each supported by detailed functional submodules: 1. KonnectED — Learning, Knowledge, and Certification 2. Ethikos — Structured Debate and Civic Consultation 3. Kreative — Culture, Preservation & Professional Networks 4. keenKonnect — Collaboration Spaces & Document Infrastructure 5. EkoH — Merit Signaling & Contextual Evaluation 6. Smart Vote — Flexible & Merit-Sensitive Voting (A full breakdown of submodules and interactions is provided in the internal KOA / Konnaxion system document and related diagrams.) --- ## 1. KonnectED — Learning, Knowledge, and Certification ### CertifiKation - Modular certification paths - AI-based assessment - Peer validation - Competency portfolios - Interoperable credentials ### Knowledge - Collaborative libraries - Personalized recommendations - Co-creation tools - Thematic forums - Learning progression dashboards --- ## 2. Ethikos — Structured Debate and Civic Consultation ### Korum - Structured elite debates - AI-driven reasoning “Klônes” - Comparative analytics - Public archives - Automated syntheses ### Konsultations - Open citizen consultations - Proposal submission - Optional expertise-weighted voting (via EkoH) - Interactive result visualizations - Impact tracking --- ## 3. Kreative — Culture, Preservation & Professional Networks ### Kreative Konservation - Digital cultural archives - Virtual exhibitions - Comprehensive documentation - AI-enhanced cataloging - Cultural institution partnerships ### Kontact - Professional profiles - Intelligent matchmaking - Collaborative tools - Opportunity marketplaces - Endorsement and reputation features --- ## 4. keenKonnect — Collaboration Spaces & Document Infrastructure ### Stockage - Secure centralized repositories - Automatic versioning - Intelligent indexing - Real-time synchronization - Fine-grained access control ### Konstruct - Real-time collaborative workspaces - Integrated project management - Co-editing environments - Embedded messaging and video - AI-supported analysis --- ## 5. EkoH — Merit Signaling & Contextual Evaluation - Multidimensional scoring - Customizable criteria - Contextual AI interpretation - Adaptive confidentiality - Comprehensive traceability - Visualized merit maps EkoH models domain-specific and ethics-aware merit signals, which can be applied to debates, consultations, recommendations, and collaborative workspaces to generate different “readings” of activity and outcomes. --- ## 6. Smart Vote — Flexible & Merit-Sensitive Voting - Dynamic weighting through EkoH - Multiple voting modalities - Emerging-expertise detection - Transparent results - Advanced visualizations - Integration across all civic modules Smart Vote uses EkoH-derived weights (when enabled) to produce expertise-sensitive readings alongside raw vote counts, and is designed to operate across KonnectED, Ethikos, Kreative, and keenKonnect scenarios. --- ## Technology This repository currently includes: - Next.js / React / TypeScript frontend applications and services - Django / Django REST Framework backend APIs - PostgreSQL data models and migrations - Redis + Celery background processing - Playwright browser qualification workflows - Docker-based local and production orchestration - Python analytical and diagnostic tooling - UI concept explorations and explicitly retained prototype/placeholder surfaces - data modeling and integration experiments Each component contributes to the assembly of a unified civic infrastructure. The core ethiKos / EkoH / Smart Vote path is now substantially implemented and qualified locally, while some secondary surfaces remain intentionally experimental, preview, read-only, placeholder, or deferred pending complete domain contracts. --- ## Conceptual Foundations ### Mythology & Narrative - **Konvergence** — narrative origin of Konnaxion - Extended symbolic world via the Konvergence / King Klown YouTube playlists ### Civic Architecture - **The Book of kOA** — modular civic systems and KOA ecosystem - Additional philosophical and technical writings via open-access archives (PhilArchive, PhilPeople, etc.) Konnaxion is the principal software expression of the KOA civic architecture and the broader movement described on the public hubs (kingklown.com, kingklown.wiki, okido.wiki). --- ## ️Roadmap Planned directions include: - Consolidation of core primitives across modules - Prototype civic workflow (proposal → deliberation → decision → action) - Interactive interface experiments for different user roles - Early implementations of EkoH & Smart Vote - Documentation and integration pathways for external tools and institutions - Expanded mythology-based simulation tools and narrative UX Roadmap items are refined continuously based on experimentation and potential pilot needs. --- ## Contributing Konnaxion welcomes collaborators interested in: - civic technology - coordination systems - collective intelligence - governance innovation - cultural knowledge infrastructures - AI-assisted deliberation Discussions, issue proposals, and architecture reviews are encouraged. As the stack stabilises, contribution guidelines and starter issues will be added. --- ## ✨ Author **Réjean McCormick** GitHub: https://github.com/Rejean-McCormick --- ## About Modular civic-tech platform that connects people, knowledge, and projects across learning, R&D, governance, and culture, with domain- and ethics-aware weighting (EkoH + Smart Vote). ================================================================================================ FILE: seed-data/ethikos/canada_quebec_public_debates_2026_inventory.md AUTHORITY: reference CONTENT_ROLE: knowledge CONTENT_SHA256: 943f8cf9e1fdf2f9dadf41c53a71216854115f08716166b0672df6e6a52d6e3b CONTENT_BYTES: 56078 ================================================================================================ # Inventaire — Débats publics Québec–Canada 2026 > Package seed normalisé pour `ethikos-demo-scenario/v3`. > Le JSON principal est la source de vérité machine. Les lectures Smart Vote restent dérivées; les exclusions/récusations déclarées configurent seulement la lecture consultative et ne retirent aucune stance du baseline. > Corpus V4 walkthrough: **31 acteurs · 14 débats · 67 positions · 78 arguments · 95 liens argument→source · 31 profils EkoH · 1 récusation consultative déclarée**. > V4.1: les **31 profils EkoH du scénario sont explicitement `rating_visibility=public`** pour la transparence de la démonstration; cette règle de seed ne remplace pas le nouveau contrôle d’accès EkoH générique (`public | scoped | private`). ## Inventaire éditorial détaillé # Inventaire Ethikos — débats Québec–Canada 2026 **Instantané : 17 août 2026** **Scénario :** `canada_quebec_public_debates_2026` **Portée :** 14 débats, 31 acteurs, 78 arguments, 95 liens argument→source. **Passe éditoriale :** V4 walkthrough — scénario Canada–États-Unis → infrastructure IA → question Trump → lecture EkoH/Smart Vote avec récusation déclarée. ## Méthode - Les cinq profils ajoutés pour le walkthrough Trump sont **explicitement DEMO** et ne représentent aucune personne réelle. - Le rapport de contexte King Klown/Trump et les événements associés sont **fictionnels dans le scénario de démonstration**; ils ne doivent pas être interprétés comme des événements réels. - Une récusation déclarée retire uniquement King Klown de la lecture consultative EkoH/Smart Vote; sa stance source reste visible dans le baseline. - Les positions et arguments sont des **paraphrases synthétiques**, pas des citations. - Les sources primaires des gouvernements, partis, organisations professionnelles, syndicats, associations patronales, Premières Nations et organismes concernés sont privilégiées pour attribuer une position. - Les données de Statistique Canada et du Directeur parlementaire du budget servent surtout de contexte factuel. - La valeur Ethikos `-3…+3` situe un acteur sur **l’axe propre à chaque débat**; elle ne mesure ni vérité, ni qualité, ni popularité. - Les nouveaux nœuds utilisent `parent` lorsque le lien de soutien, opposition ou nuance est assez clair pour former un graphe argumentatif. - Certains débats ont un consensus relatif parmi les principaux acteurs recensés; aucun camp artificiel n’est créé. - Le fichier `*_sources.json` demeure un sidecar en attendant que le modèle proposé `ArgumentSource` soit importable nativement. ## Répartition des sources - `official_government` : 37 - `political_party` : 27 - `civil_society` : 4 - `industry_advocacy` : 4 - `official_statistics` : 4 - `independent_officer` : 2 - `professional_order` : 2 - `expert_advisory` : 1 - `first_nations_primary` : 1 - `higher_education_stakeholder` : 1 - `international_standard` : 1 - `labour_union` : 1 - `official_research` : 1 ## Débats, acteurs et arguments ### 1. Le Canada devrait-il réduire rapidement le déficit fédéral, même si cela limite certains investissements publics? Débat sur la vitesse du retour vers l'équilibre budgétaire, la distinction entre dépenses courantes et investissements, le coût du service de la dette et la capacité de financer les priorités futures. **Pôle + :** Réduction rapide du déficit et discipline budgétaire **Pôle − :** Déficits tolérés pour financer des investissements prioritaires **Acteurs / arguments** - **Gouvernement du Canada** — stance `-1`, côté `con` : Le gouvernement soutient qu'il faut distinguer les dépenses courantes des investissements de long terme et qu'un retour graduel vers l'équilibre des opérations peut coexister avec des investissements en logement, infrastructures, défense et capacité économique. Sources : `finance_spring_update_2026` - **Parti conservateur du Canada** — stance `+3`, côté `pro` : Les conservateurs soutiennent que des déficits élevés et persistants augmentent la dette, les frais d'intérêt et les pressions fiscales futures; ils privilégient une réduction plus rapide des dépenses et du déficit. Sources : `cpc_fiscal_spending`, `cpc_affordable_budget` - **Directeur parlementaire du budget** — stance `+0`, côté `neutral` : Le Directeur parlementaire du budget conclut que les cibles fiscales annoncées sont atteignables selon les projections de 2026, tout en signalant un manque de précision dans la définition de certaines dépenses classées comme capital, ce qui limite l'évaluation indépendante. Sources : `pbo_spring_fiscal_anchors_2026`, `pbo_budget_2025_issues` **Inventaire des sources du débat** - `finance_spring_update_2026` — **Department of Finance Canada**, *Spring Economic Update 2026* (2026-04-28) — https://budget.canada.ca/update-miseajour/2026/report-rapport/intro-en.html - `pbo_spring_fiscal_anchors_2026` — **Parliamentary Budget Officer**, *PBO assessment of the Spring Economic Update fiscal anchors and fiscal sustainability* (2026-05-04) — https://www.pbo-dpb.ca/en/publications/NT-2627-002-S--pbo-assessment-spring-economic-update-fiscal-anchors-fiscal-sustainability--evaluation-dpb-mise-jour-economique-printemps-cibles-budgetaires-viabilite-financiere - `pbo_budget_2025_issues` — **Parliamentary Budget Officer**, *Budget 2025: Issues for Parliamentarians* (date non fixée dans le sidecar) — https://www.pbo-dpb.ca/en/publications/RP-2526-017-S--budget-2025-issues-parliamentarians--budget-2025-enjeux-parlementaires - `cpc_fiscal_spending` — **Conservative Party of Canada**, *Liberal Inflationary Spending by the Numbers* (date non fixée dans le sidecar) — https://www.conservative.ca/liberal-inflationary-spending-by-the-numbers/ - `cpc_affordable_budget` — **Conservative Party of Canada**, *An Affordable Budget for Affordable Lives* (date non fixée dans le sidecar) — https://www.conservative.ca/an-affordable-budget-for-affordable-lives/ ### 2. Le Canada devrait-il réduire fortement sa dépendance envers les États-Unis, même au prix de coûts à court terme? Débat sur la diversification commerciale, l'intégration nord-américaine, les tarifs, les chaînes d'approvisionnement, la défense et l'autonomie stratégique du Canada. **Pôle + :** Diversification et autonomie stratégique plus fortes **Pôle − :** Priorité à la restauration de l'intégration et du libre-échange nord-américain **Acteurs / arguments** - **Gouvernement du Canada** — stance `+2`, côté `pro` : Le gouvernement fédéral cherche à préserver l'accès au marché américain tout en diversifiant les exportations, les chaînes d'approvisionnement et les partenariats afin de réduire la vulnérabilité du Canada aux mesures commerciales américaines. Sources : `gac_canada_us_engagement`, `gac_canada_us_aug_2026`, `gac_state_trade_2026` - **Parti conservateur du Canada** — stance `-1`, côté `con` : Les conservateurs reconnaissent l'intérêt de diversifier les marchés, mais insistent surtout sur la nécessité de réparer la relation avec Washington et de retrouver un commerce nord-américain largement exempt de tarifs. Sources : `cpc_good_deal_us_2026`, `cpc_fighting_for_canada_us` - **Nouveau Parti démocratique** — stance `+3`, côté `pro` : Le NPD plaide pour une économie canadienne moins vulnérable aux décisions américaines, avec davantage de résilience domestique, de diversification et de protection des travailleurs face aux chocs commerciaux. Sources : `ndp_campaign_commitments` - **Bloc Québécois** — stance `+2`, côté `pro`, parent `us_gov_diversify` : Le Bloc soutient qu'une dépendance aussi forte envers le marché américain rend le Québec vulnérable aux décisions de Washington; il réclame une voix québécoise directe dans les négociations, des contre-mesures ciblées et des mécanismes d'adaptation pour protéger les secteurs exposés. Sources : `bq_quebec_voice_us_2025`, `bq_tariffs_pme_2026` **Inventaire des sources du débat** - `gac_canada_us_engagement` — **Global Affairs Canada**, *Canada–United States engagement* (2026-07-02) — https://international.canada.ca/en/global-affairs/campaigns/canada-us-engagement - `gac_canada_us_aug_2026` — **Global Affairs Canada**, *Minister LeBlanc and Chief Trade Negotiator update provincial and territorial trade ministers and advisory committee on Canada-U.S. economic relation* (2026-08-14) — https://www.canada.ca/en/global-affairs/news/2026/08/minister-leblanc-and-chief-trade-negotiator-update-provincial-and-territorial-trade-ministers-and-advisory-committee-on-canada-us-economic-relation.html - `gac_state_trade_2026` — **Global Affairs Canada**, *State of Trade 2026* (2026) — https://international.canada.ca/en/global-affairs/corporate/reports/chief-economist/state-trade/2026 - `cpc_good_deal_us_2026` — **Conservative Party of Canada**, *Canadians Need a Good Deal* (2026-08-13) — https://www.conservative.ca/canadians-need-a-good-deal/ - `cpc_fighting_for_canada_us` — **Conservative Party of Canada**, *Fighting for Canada* (2026-03-19) — https://www.conservative.ca/fighting-for-canada/ - `ndp_campaign_commitments` — **New Democratic Party of Canada**, *Campaign commitments* (date non fixée dans le sidecar) — https://www.ndp.ca/campaign-commitments - `bq_quebec_voice_us_2025` — **Bloc Québécois**, *Négociations avec Donald Trump : Le Québec doit parler de sa propre voix* (2025-04-03) — https://www.blocquebecois.org/negociations-avec-donald-trump-le-quebec-doit-parler-de-sa-propre-voix/ - `bq_tariffs_pme_2026` — **Bloc Québécois**, *Journée de l’opposition du Bloc Québécois : Un cri d’alarme pour soutenir nos PME face aux tarifs américains* (2026-05-01) — https://www.blocquebecois.org/journee-de-lopposition-du-bloc-quebecois-un-cri-dalarme-pour-soutenir-nos-pme-face-aux-tarifs-americains/ ### 3. Le Canada devrait-il maintenir ou augmenter son soutien militaire, financier et diplomatique à l'Ukraine? Débat sur l'ampleur et la durée de l'aide canadienne à l'Ukraine, les sanctions, l'assistance militaire, l'aide financière et la recherche d'une paix durable. **Pôle + :** Maintenir ou accroître le soutien à l'Ukraine **Pôle − :** Réduire ou conditionner fortement le soutien **Acteurs / arguments** - **Gouvernement du Canada** — stance `+3`, côté `pro` : Le gouvernement du Canada présente le soutien militaire, financier, humanitaire et diplomatique à l'Ukraine comme un engagement durable envers sa souveraineté et sa capacité de résister à l'agression russe. Sources : `gac_ukraine_support`, `gac_ukraine_relations` - **Parti conservateur du Canada** — stance `+3`, côté `pro` : Les conservateurs appuient l'Ukraine, les sanctions contre la Russie et l'utilisation d'actifs russes saisis ou gelés au bénéfice de l'Ukraine, tout en mettant l'accent sur la fermeté envers le Kremlin. Sources : `cpc_ukraine_assets` - **Nouveau Parti démocratique** — stance `+2`, côté `pro` : Le NPD soutient l'Ukraine et demande notamment une meilleure application des sanctions et des mesures de responsabilité internationale; son accent porte davantage sur les institutions, les droits et la diplomatie multilatérale. Sources : `ndp_foreign_affairs_ukraine` - **Bloc Québécois** — stance `+3`, côté `pro`, parent `ukraine_gov_support` : Le Bloc réaffirme un appui ferme à l'indépendance, à la liberté et à la sécurité de l'Ukraine, et considère que le Canada doit demeurer engagé plutôt que devenir un acteur passif face à l'agression russe. Sources : `bq_ukraine_2025` **Inventaire des sources du débat** - `gac_ukraine_support` — **Global Affairs Canada**, *Canada's response to the Russian invasion of Ukraine* (2026-05-08) — https://www.international.gc.ca/world-monde/issues_development-enjeux_developpement/response_conflict-reponse_conflits/crisis-crises/ukraine-dev.aspx?lang=eng - `gac_ukraine_relations` — **Global Affairs Canada**, *Canada-Ukraine relations* (2026-05-10) — https://www.international.gc.ca/country-pays/ukraine/relations.aspx?lang=eng - `cpc_ukraine_assets` — **Conservative Party of Canada**, *Conservatives Will Provide Seized Russian Assets to Ukraine* (date non fixée dans le sidecar) — https://www.conservative.ca/conservatives-will-provide-seized-russian-assets-to-ukraine/ - `ndp_foreign_affairs_ukraine` — **New Democratic Party of Canada**, *Heather McPherson MP: Canada-U.S. relationship and the NDP's vision for foreign affairs in a time of crisis* (2025-01-28) — https://heathermcpherson.ndp.ca/news/heather-mcpherson-mp-canada-us-relationship-and-ndps-vision-foreign-affairs-time-crisis - `bq_ukraine_2025` — **Bloc Québécois**, *Trois ans d’invasion russe en Ukraine : le Bloc Québécois réaffirme son appui total à l’indépendance ukrainienne* (2025-02-24) — https://www.blocquebecois.org/trois-ans-dinvasion-russe-en-ukraine-le-bloc-quebecois-reaffirme-son-appui-total-a-lindependance-ukrainienne/ ### 4. Le Canada devrait-il adopter au Moyen-Orient une ligne plus indépendante des États-Unis et davantage centrée sur le droit international? Débat couvrant Israël–Palestine et l'Iran : sécurité d'Israël, protection des civils, droit international, solution à deux États, sanctions, programme nucléaire iranien, diplomatie et risque d'escalade régionale. **Pôle + :** Diplomatie, droit international et autonomie accrue par rapport aux États-Unis **Pôle − :** Alignement sécuritaire plus étroit avec les États-Unis et Israël face à l'Iran **Acteurs / arguments** - **Gouvernement du Canada** — stance `+1`, côté `pro` : Le gouvernement fédéral défend l'aide humanitaire, la protection des civils, une solution à deux États et une approche diplomatique du dossier nucléaire iranien, tout en condamnant les menaces à la sécurité régionale. Sources : `gac_israel_palestine_response`, `gac_israel_palestine_policy`, `gac_iran_diplomacy_2026` - **Parti conservateur du Canada** — stance `-3`, côté `con` : Les conservateurs adoptent une ligne nettement plus favorable à Israël et à une coopération étroite avec les États-Unis et leurs alliés face au régime iranien, en privilégiant la sécurité et la pression sur Téhéran. Sources : `cpc_iran_2026`, `cpc_israel_oct7` - **Nouveau Parti démocratique** — stance `+3`, côté `pro` : Le NPD met davantage l'accent sur le droit international, la reddition de comptes, la protection des civils et la désescalade, y compris lorsqu'il critique des actions militaires d'Israël ou de l'Iran. Sources : `ndp_israel_iran_attacks`, `ndp_war_crimes_accountability` **Inventaire des sources du débat** - `gac_israel_palestine_response` — **Global Affairs Canada**, *Canada's response to the crisis in Israel, the West Bank and the Gaza Strip* (2026-03-03) — https://www.international.gc.ca/world-monde/issues_development-enjeux_developpement/response_conflict-reponse_conflits/crisis-crises/israel.aspx?lang=eng - `gac_israel_palestine_policy` — **Global Affairs Canada**, *Canadian policy on key issues in the Israeli-Palestinian conflict* (date non fixée dans le sidecar) — https://www.international.gc.ca/world-monde/international_relations-relations_internationales/mena-moan/israeli-palestinian_policy-politique_israelo-palestinien.aspx?lang=eng - `gac_iran_diplomacy_2026` — **Global Affairs Canada**, *Statement at the UN Security Council on the Middle East* (2026-04-28) — https://www.international.gc.ca/world-monde/international_relations-relations_internationales/un-onu/statements-declarations/2026-04-28-middle-east-palestinienne.aspx?lang=eng - `cpc_iran_2026` — **Conservative Party of Canada**, *Conservative Statement on Military Action Against Iran* (2026) — https://www.conservative.ca/conservative-statement-on-military-action-against-iran/ - `cpc_israel_oct7` — **Conservative Party of Canada**, *Statement from Conservative Leader Pierre Poilievre on the Second Anniversary of the October 7th Attacks* (2025-10-07) — https://www.conservative.ca/statement-from-conservative-leader-pierre-poilievre-on-the-second-anniversary-of-the-october-7th-attacks/ - `ndp_israel_iran_attacks` — **New Democratic Party of Canada**, *NDP statement on Israel's recent attacks* (2025-06-13) — https://www.ndp.ca/news/ndp-statement-israels-recent-attacks - `ndp_war_crimes_accountability` — **New Democratic Party of Canada**, *NDP letter to ministers re: prosecution of crimes by Canadians in Israel and Palestine* (date non fixée dans le sidecar) — https://heathermcpherson.ndp.ca/news/ndp-letter-ministers-re-prosecution-crimes-canadians-israel-and-palestine ### 5. Le Canada devrait-il taxer davantage les grandes fortunes et profits pour réduire les inégalités et le coût de la vie? Débat sur la concentration de la richesse, le pouvoir d'achat, la fiscalité des ménages les plus riches, l'investissement privé et les politiques de redistribution. **Pôle + :** Fiscalité plus redistributive sur grandes fortunes et profits **Pôle − :** Priorité à la croissance et aux baisses d'impôts plutôt qu'à de nouvelles taxes sur la richesse **Acteurs / arguments** - **Nouveau Parti démocratique** — stance `+3`, côté `pro` : Le NPD propose une fiscalité accrue sur les très grandes fortunes afin de financer les services publics et de réduire la concentration de la richesse et la pression du coût de la vie sur les ménages ordinaires. Sources : `ndp_campaign_commitments` - **Parti conservateur du Canada** — stance `-3`, côté `con` : Les conservateurs privilégient des baisses d'impôts, une réduction des coûts gouvernementaux et une stratégie de croissance plutôt que de nouvelles taxes sur le capital ou la richesse, qu'ils jugent susceptibles de décourager l'investissement. Sources : `cpc_affordability_home`, `cpc_affordable_budget` - **Statistique Canada** — stance `+0`, côté `neutral` : Les données de Statistique Canada montrent une forte concentration de la valeur nette chez les ménages les plus riches et un écart de richesse important entre le haut et le bas de la distribution. Sources : `statcan_wealth_q4_2025`, `statcan_weekly_wealth_apr_2026` - **Québec solidaire** — stance `+3`, côté `pro`, parent `wealth_ndp_tax` : Québec solidaire soutient que le coût de la vie et l'érosion du pouvoir d'achat reflètent aussi une répartition trop inégale des gains économiques; il privilégie une fiscalité plus redistributive, un rôle accru de l'État, des services publics renforcés et des protections salariales. Sources : `qs_workers_manifest` - **Fédération des travailleurs et travailleuses du Québec (FTQ)** — stance `+2`, côté `pro`, parent `wealth_ndp_tax` : La FTQ critique les politiques d'austérité et les baisses d'impôt qui réduisent la capacité de financer les services publics, et soutient qu'une réponse au coût de la vie doit protéger davantage les travailleuses, travailleurs et ménages moins favorisés. Sources : `ftq_may_day_2025` **Inventaire des sources du débat** - `statcan_wealth_q4_2025` — **Statistics Canada**, *Distributions of household economic accounts for income, consumption, saving and wealth of Canadian households, fourth quarter 2025* (2026-04-13) — https://www150.statcan.gc.ca/n1/daily-quotidien/260413/dq260413a-eng.htm - `statcan_weekly_wealth_apr_2026` — **Statistics Canada**, *The Weekly Review, April 13 to 17, 2026* (2026-04-17) — https://www.statcan.gc.ca/o1/en/plus/9136-weekly-review-april-13-17-2026 - `ndp_campaign_commitments` — **New Democratic Party of Canada**, *Campaign commitments* (date non fixée dans le sidecar) — https://www.ndp.ca/campaign-commitments - `cpc_affordability_home` — **Conservative Party of Canada**, *Poilievre Lays Out Plan to Make Canada Affordable at Home* (2026) — https://www.conservative.ca/poilievre-lays-out-plan-to-make-canada-affordable-at-home/ - `cpc_affordable_budget` — **Conservative Party of Canada**, *An Affordable Budget for Affordable Lives* (date non fixée dans le sidecar) — https://www.conservative.ca/an-affordable-budget-for-affordable-lives/ - `qs_workers_manifest` — **Québec solidaire**, *Manifeste pour un Québec solidaire de ses travailleuses et travailleurs* (date non fixée dans le sidecar) — https://appuyez.quebecsolidaire.net/manifeste - `ftq_may_day_2025` — **FTQ**, *1er mai 2025 — Journée internationale des travailleuses et travailleurs* (2025-05-01) — https://ftq.qc.ca/1er-mai-2025/ ### 6. Faut-il accélérer fortement les approbations de projets en réduisant les chevauchements réglementaires et les délais de décision? Débat sur le coût économique des délais, la coordination fédérale-provinciale, la prévisibilité des autorisations, les consultations et les garanties environnementales et sociales. **Pôle + :** Accélérer fortement les autorisations et réduire les chevauchements **Pôle − :** Maintenir des processus plus longs pour maximiser les garanties et consultations **Acteurs / arguments** - **Gouvernement du Canada** — stance `+2`, côté `pro` : Le gouvernement fédéral veut simplifier et accélérer les grands projets par une meilleure coordination, le principe d'un projet–un examen et des échéanciers plus prévisibles, tout en affirmant maintenir les obligations environnementales et de consultation. Sources : `canada_regulatory_acceleration_2026`, `canada_major_projects_discussion_2026` - **Parti conservateur du Canada** — stance `+3`, côté `pro` : Les conservateurs soutiennent que la réglementation et les délais d'autorisation ont rendu le Canada trop lent à construire des infrastructures, des projets énergétiques et des logements; ils proposent d'abroger ou simplifier plusieurs règles jugées bloquantes. Sources : `cpc_red_tape_projects`, `cpc_sovereignty_act` - **Parti libéral du Québec** — stance `+3`, côté `pro`, parent `reg_gov_one_review` : Le PLQ veut réduire rapidement le fardeau administratif des entreprises, notamment par un moratoire sur de nouvelles règles alourdissant les PME et une règle de type « deux pour un » pour les formalités réglementaires. Sources : `plq_general_council_2026` - **Conseil du patronat du Québec** — stance `+3`, côté `pro`, parent `reg_gov_one_review` : Le CPQ considère l'allègement réglementaire et la réduction des délais de permis comme des leviers de compétitivité; il demande que ces objectifs deviennent des pratiques durables et prévisibles de l'administration québécoise. Sources : `cpq_bill11_2026` - **Équiterre** — stance `-2`, côté `con`, parent `reg_gov_one_review` : Équiterre avertit qu'accélérer les grands projets en affaiblissant les protections environnementales peut produire de mauvaises décisions et transférer les coûts écologiques au public; l'accélération devrait plutôt améliorer la planification sans diminuer les exigences de fond. Sources : `equiterre_major_projects_2026` - **Assemblée des Premières Nations Québec-Labrador (APNQL)** — stance `-3`, côté `con`, parent `reg_gov_one_review` : L'APNQL soutient que l'allègement administratif ne doit pas supprimer les mécanismes de suivi, de reddition de comptes ou de consultation, particulièrement lorsque des projets affectent les droits et territoires des Premières Nations. Sources : `apnql_bill11_2026` **Inventaire des sources du débat** - `canada_regulatory_acceleration_2026` — **Government of Canada**, *Canada's new government to simplify and accelerate Canada's regulatory process* (2026-05-08) — https://www.canada.ca/en/one-canadian-economy/news/2026/05/canadas-new-government-to-simplify-and-accelerate-canadas-regulatory-process.html - `canada_major_projects_discussion_2026` — **Government of Canada**, *Getting major projects built in Canada: Discussion paper on proposed legislative, regulatory and policy reforms* (2026-07-23) — https://www.canada.ca/en/one-canadian-economy/services/simplifying-canada-process/engagement-supporting-timely-decision-making/getting-major-projects-built-canada-discussion-paper-proposed-legislative-regulatory-policy-reforms.html - `cpc_red_tape_projects` — **Conservative Party of Canada**, *A New Chapter in an Old Friendship* (2026-03-04) — https://www.conservative.ca/a-new-chapter-in-an-old-friendship/ - `cpc_sovereignty_act` — **Conservative Party of Canada**, *Canadian Sovereignty Act* (date non fixée dans le sidecar) — https://www.conservative.ca/canadian-sovereignty-act/ - `plq_general_council_2026` — **Parti libéral du Québec**, *Conseil général du Parti libéral du Québec à Sherbrooke : Charles Milliard veut réparer le Québec* (2026-06-09) — https://plq.org/conseil-general-du-parti-liberal-du-quebec-a-sherbrooke-charles-milliard-veut-reparer-le-quebec/ - `cpq_bill11_2026` — **Conseil du patronat du Québec**, *Projet de loi 11 : le CPQ salue plusieurs avancées et appelle à ancrer durablement l’allègement réglementaire* (2026-02-04) — https://www.cpq.qc.ca/publications/projet-de-loi-11-le-cpq-salue-plusieurs-avancees-et-appel-a-ancrer-durablement-lallegement-reglementaire-dans-les-facons-de-faire-du-gouvernement/ - `equiterre_major_projects_2026` — **Équiterre**, *Comment bâtir un Canada fort en freinant la transition?* (2026-06-15) — https://www.equiterre.org/fr/ressources/comment-b%C3%A2tir-un-canada-fort-en-freinant-la-transition - `apnql_bill11_2026` — **Assemblée des Premières Nations Québec-Labrador / Assemblée nationale du Québec**, *Avis de l’APNQL sur le projet de loi 11 — allègement du fardeau réglementaire et administratif* (date non fixée dans le sidecar) — https://www.assnat.qc.ca/Media/Process.aspx?MediaId=ANQ.Vigie.Bll.DocumentGenerique_217945&process=Default&token=ZyMoxNwUn8ikQ+TRKYwPCjWrKwg+vIv9rjij7p3xLGTZDmLVSmJLoqe%2FvG7%2FYWzz ### 7. Le système de justice devrait-il prioriser davantage la rapidité et la sécurité publique, même si cela réduit certaines marges procédurales? Débat sur les délais judiciaires, l'accès à la justice, l'aide juridique, les règles de mise en liberté, les garanties constitutionnelles et la confiance du public. **Pôle + :** Priorité accrue à la rapidité, à l'exécution et à la sécurité publique **Pôle − :** Priorité accrue à l'accès, aux garanties procédurales et à l'aide juridique **Acteurs / arguments** - **Gouvernement du Canada** — stance `+1`, côté `pro` : Le gouvernement cherche à réduire les conséquences des délais judiciaires et à renforcer la sécurité publique, notamment en proposant des outils autres que l'arrêt pur et simple des procédures lorsque les délais deviennent déraisonnables. Sources : `justice_c16_delays`, `justice_department_plan_2026` - **Justice Canada — accès à la justice** — stance `+0`, côté `neutral` : Les travaux fédéraux sur l'accès à la justice soulignent que les réformes doivent rester centrées sur les personnes, préserver l'aide juridique et éviter que l'efficacité procédurale n'accroisse les inégalités pour les groupes déjà marginalisés. Sources : `justice_access_overview`, `justice_legal_aid_marginalized` - **Parti conservateur du Canada** — stance `+3`, côté `pro` : Les conservateurs veulent durcir les règles de mise en liberté pour les récidivistes violents et placent la sécurité du public et l'exécution rapide des décisions au-dessus d'une approche qu'ils jugent trop permissive. Sources : `cpc_restore_safe_streets` - **Gouvernement du Québec** — stance `+0`, côté `neutral` : Le gouvernement du Québec cherche à améliorer simultanément l'accès et l'efficacité par le financement d'initiatives d'accès à la justice et par la transformation numérique des services judiciaires, qui vise notamment à simplifier les démarches et réduire certains délais de traitement. Sources : `quebec_justice_digital_2025_2026`, `quebec_fonds_acces_justice` - **Barreau du Québec** — stance `-1`, côté `con`, parent `justice_gov_delay_remedies` : Le Barreau reconnaît la nécessité de réduire les délais, mais insiste sur une justice accessible et de qualité; ses initiatives privilégient aussi l'information juridique, les cliniques gratuites et des solutions procédurales qui ne sacrifient pas les droits des justiciables. Sources : `barreau_clinic_2026`, `barreau_delay_actions_2024` **Inventaire des sources du débat** - `justice_department_plan_2026` — **Department of Justice Canada**, *Departmental Plan 2026–27* (2026-03-13) — https://www.justice.gc.ca/eng/rp-pr/cp-pm/rpp/2026_2027/rep-rap/index.html - `justice_access_overview` — **Department of Justice Canada**, *Access to Justice* (date non fixée dans le sidecar) — https://www.justice.gc.ca/eng/csj-sjc/access-acces/index.html - `justice_c16_delays` — **Department of Justice Canada**, *Bill C-16: Strengthening the criminal justice system and addressing court delays* (2026) — https://www.justice.gc.ca/eng/csj-sjc/pl/c16/index.html - `justice_legal_aid_marginalized` — **Department of Justice Canada**, *Legal aid and marginalized populations* (2024) — https://www.justice.gc.ca/eng/rp-pr/jr/aid-aide/2024/p11.html - `cpc_restore_safe_streets` — **Conservative Party of Canada**, *Restore Safe Streets* (date non fixée dans le sidecar) — https://www.conservative.ca/restore-safe-streets/ - `quebec_justice_digital_2025_2026` — **Gouvernement du Québec**, *Portefeuille des projets prioritaires gouvernemental en transformation numérique 2025-2026* (2025-09-12) — https://www.quebec.ca/gouvernement/ministeres-organismes/cybersecurite-numerique/publications/portefeuille-projets-prioritaires-gouvernemental-transformation-numerique-2025-2026 - `quebec_fonds_acces_justice` — **Ministère de la Justice du Québec**, *Fonds Accès Justice* (2025-11-11) — https://www.quebec.ca/gouvernement/ministeres-organismes/justice/mission-services/faj - `barreau_clinic_2026` — **Barreau du Québec**, *Clinique juridique du Barreau : un levier concret d’accès à la justice et de formation* (2026-06-05) — https://www.barreau.qc.ca/fr/nouvelle/communiques/clinique-juridique-ecole-barreau-levier-concret-acces-justice-formation/ - `barreau_delay_actions_2024` — **Barreau du Québec**, *Le Barreau du Québec propose plusieurs pistes d’action concrètes pour réduire les délais en matière criminelle et pénale* (2024-02-12) — https://www.barreau.qc.ca/fr/nouvelle/avis-aux-membres/reduction-delais-criminelle-penale-barreau-propose-plusieurs-pistes-action-concretes/ ### 8. L'école et l'enseignement supérieur devraient-ils intégrer largement l'IA générative dans l'apprentissage et l'évaluation, sous un cadre éthique? Débat sur la littératie en IA, les usages pédagogiques, l'intégrité des évaluations, la protection des données, l'équité d'accès et la formation du personnel enseignant. **Pôle + :** Intégration large et encadrée de l'IA dans l'éducation **Pôle − :** Usage fortement restreint ou retardé de l'IA dans l'éducation **Acteurs / arguments** - **Gouvernement du Québec — Éducation** — stance `+2`, côté `pro` : Le Québec développe des ressources, un centre d'expertise et un cadre de compétence numérique qui intègrent l'IA; l'orientation est d'encadrer son usage de façon responsable plutôt que de tenter de l'exclure du réseau scolaire. Sources : `quebec_ai_education`, `quebec_ai_tools`, `quebec_digital_competency` - **Conseil consultatif du Canada sur l'intelligence artificielle** — stance `+2`, côté `pro` : Le Conseil consultatif fédéral sur l'IA recommande une littératie en IA accessible dès l'école et tout au long de la vie, avec une attention aux biais, à la sécurité, à la responsabilité et à l'inclusion. Sources : `ised_ai_strategy_inputs`, `ai_advisory_learning_responsible` - **Fédération québécoise des professeures et professeurs d'université (FQPPU)** — stance `+0`, côté `con`, parent `aiedu_quebec_responsible` : La FQPPU ne rejette pas l'IA en soi, mais critique une intégration pilotée sans consultation substantielle ni moyens suffisants; elle demande que les communautés universitaires, la liberté académique et la gouvernance collégiale soient réellement intégrées aux décisions. Sources : `fqppu_ai_governance` - **UNESCO — éducation et IA** — stance `+1`, côté `pro`, parent `aiedu_quebec_responsible` : L'UNESCO estime que l'IA peut soutenir l'apprentissage et l'enseignement, mais seulement dans un cadre centré sur l'humain qui protège la vie privée, l'équité, l'autonomie des apprenants et la capacité critique des enseignants et étudiants. Sources : `unesco_genai_guidance` **Inventaire des sources du débat** - `quebec_ai_education` — **Gouvernement du Québec**, *Intelligence artificielle en éducation* (2026-06-18) — https://www.quebec.ca/education/numerique/intelligence-artificielle - `quebec_ai_tools` — **Gouvernement du Québec**, *Documents et outils sur l'IA dans le réseau de l'éducation* (2026-04-28) — https://www.quebec.ca/education/numerique/intelligence-artificielle/reseau-education/documents-outils-ia - `quebec_digital_competency` — **Gouvernement du Québec**, *Cadre de référence de la compétence numérique* (2026-08-10) — https://www.quebec.ca/education/numerique/cadre-reference - `ised_ai_strategy_inputs` — **Innovation, Science and Economic Development Canada**, *Engagements on Canada's next AI strategy: Summary of inputs* (2026-02-05) — https://ised-isde.canada.ca/site/ised/en/public-consultations/engagements-canadas-next-ai-strategy-summary-inputs - `ai_advisory_learning_responsible` — **Advisory Council on Artificial Intelligence**, *Learning together for responsible artificial intelligence* (date non fixée dans le sidecar) — https://ised-isde.canada.ca/site/advisory-council-artificial-intelligence/en/public-awareness-working-group/learning-together-responsible-artificial-intelligence - `fqppu_ai_governance` — **FQPPU**, *La FQPPU demande la démission de la ministre de l’Enseignement supérieur* (date non fixée dans le sidecar) — https://fqppu.org/la-fqppu-demande-la-demission-de-pascale-dery/ - `unesco_genai_guidance` — **UNESCO**, *Guidance for generative AI in education and research* (2026-01-16) — https://www.unesco.org/en/articles/guidance-generative-ai-education-and-research ### 9. Le Canada et le Québec devraient-ils réduire davantage l'immigration jusqu'à ce que logement, santé et infrastructures rattrapent la croissance? Débat sur les volumes d'immigration temporaire et permanente, la capacité d'accueil, les pénuries de main-d'œuvre, les droits des travailleurs temporaires, la francisation et l'intégration. **Pôle + :** Réduction supplémentaire des volumes jusqu'au rattrapage de la capacité d'accueil **Pôle − :** Maintien de volumes plus élevés et priorité aux droits/statuts permanents plutôt qu'aux réductions **Acteurs / arguments** - **Gouvernement du Canada** — stance `+1`, côté `pro` : Ottawa a réduit ses cibles de nouveaux résidents temporaires et cherche à ramener leur part de la population sous 5 %, en invoquant la nécessité de mieux aligner l'immigration sur le logement, les services et la capacité d'accueil. Sources : `ircc_levels_2026_2028`, `ircc_supplementary_2026_2028` - **Gouvernement du Québec** — stance `+2`, côté `pro` : Québec veut limiter davantage les volumes temporaires et permanents afin de réduire la pression sur le logement, les services publics et la francisation, tout en ciblant les admissions selon ses priorités économiques et linguistiques. Sources : `quebec_immigration_2026_2029` - **Parti conservateur du Canada** — stance `+3`, côté `pro` : Les conservateurs demandent une réduction plus marquée des volumes et une refonte du Programme des travailleurs étrangers temporaires afin que l'immigration corresponde davantage aux capacités de logement, de santé et d'emploi. Sources : `cpc_immigration_numbers`, `cpc_end_tfw` - **Nouveau Parti démocratique** — stance `-1`, côté `con` : Le NPD reconnaît les problèmes du Programme des travailleurs étrangers temporaires, mais privilégie la réduction de la précarité et davantage de voies vers la résidence permanente plutôt qu'une politique générale de réduction fondée principalement sur le statut temporaire. Sources : `ndp_tfw_cuts` - **Parti Québécois** — stance `+3`, côté `pro`, parent `immigration_quebec_capacity` : Le Parti Québécois propose de réduire fortement l'immigration temporaire et de ramener l'immigration permanente autour de niveaux qu'il juge compatibles avec la capacité de logement, de soins, d'éducation, de francisation et d'intégration du Québec. Sources : `pq_immigration_plan_2026` - **Parti libéral du Québec** — stance `+1`, côté `pro`, parent `immigration_quebec_capacity` : Le PLQ propose de planifier l'immigration selon les besoins économiques et la capacité d'accueil propres aux régions, avec davantage de francisation; il se distingue d'une baisse uniforme des volumes en privilégiant une modulation territoriale. Sources : `plq_general_council_2026` - **Bloc Québécois** — stance `+2`, côté `pro`, parent `immigration_quebec_capacity` : Le Bloc soutient que les cibles doivent correspondre à la capacité d'accueil du Québec et réclame davantage de pouvoirs québécois en immigration, notamment pour mieux arrimer les volumes aux capacités de loger, soigner, éduquer, franciser et intégrer. Sources : `bq_immigration_capacity_2025` **Inventaire des sources du débat** - `ircc_levels_2026_2028` — **Immigration, Refugees and Citizenship Canada**, *Immigration Levels Plan* (2025-11-06) — https://www.canada.ca/en/immigration-refugees-citizenship/corporate/mandate/corporate-initiatives/levels.html - `ircc_supplementary_2026_2028` — **Immigration, Refugees and Citizenship Canada**, *Supplementary Information for the 2026–2028 Immigration Levels Plan* (2025-11-05) — https://www.canada.ca/en/immigration-refugees-citizenship/corporate/mandate/corporate-initiatives/levels/supplementary-immigration-levels-2026-2028.html - `quebec_immigration_2026_2029` — **Gouvernement du Québec**, *Tabling of the 2026–2029 immigration orientations and 2026 plan* (2025-11-07) — https://www.quebec.ca/en/news/actualites/detail/tabling-orientations-immigration-2026-2029-plan-2026-complementary-measures-66844 - `cpc_immigration_numbers` — **Conservative Party of Canada**, *Carney's Out-of-Control Immigration Numbers* (date non fixée dans le sidecar) — https://www.conservative.ca/carneys-out-of-control-immigration-numbers/ - `cpc_end_tfw` — **Conservative Party of Canada**, *End the TFW Program* (date non fixée dans le sidecar) — https://www.conservative.ca/end-the-tfw-program/ - `ndp_tfw_cuts` — **New Democratic Party of Canada**, *NDP statement on Temporary Foreign Worker Program cuts* (2024-08-26) — https://www.ndp.ca/news/ndp-statement-temporary-foreign-worker-program-cuts - `pq_immigration_plan_2026` — **Parti Québécois**, *Plan en immigration — un modèle viable* (2026) — https://pq.org/independance/plan-immigration/ - `plq_general_council_2026` — **Parti libéral du Québec**, *Conseil général du Parti libéral du Québec à Sherbrooke : Charles Milliard veut réparer le Québec* (2026-06-09) — https://plq.org/conseil-general-du-parti-liberal-du-quebec-a-sherbrooke-charles-milliard-veut-reparer-le-quebec/ - `bq_immigration_capacity_2025` — **Bloc Québécois**, *Seul le Québec peut assurer l’immigration réussie* (2025-04-21) — https://www.blocquebecois.org/seul-le-quebec-peut-assurer-limmigration-reussie/ ### 10. Faut-il durcir les interdictions et la responsabilité des producteurs pour réduire les plastiques et déchets non biodégradables? Débat sur les interdictions de plastiques à usage unique, les coûts pour les consommateurs et entreprises, la responsabilité élargie des producteurs, le recyclage et la réduction à la source. **Pôle + :** Règles plus strictes et responsabilité accrue des producteurs **Pôle − :** Allègement ou retrait des interdictions pour limiter les coûts **Acteurs / arguments** - **Gouvernement du Canada** — stance `+2`, côté `pro` : Le gouvernement fédéral utilise des interdictions ciblées, un registre des plastiques et des obligations de déclaration pour réduire les déchets et faire progresser la responsabilité sur l'ensemble du cycle de vie des produits. Sources : `canada_single_use_plastics`, `canada_plastics_registry`, `canada_plastics_amendments_2026` - **Parti conservateur du Canada** — stance `-3`, côté `con` : Les conservateurs veulent supprimer certaines interdictions fédérales sur les plastiques et soutiennent qu'elles augmentent les coûts d'emballage et d'alimentation sans offrir un rapport coût-bénéfice suffisant. Sources : `cpc_plastics_packaging` - **Ecojustice** — stance `+3`, côté `pro` : Ecojustice et des groupes environnementaux demandent de maintenir et renforcer les règles fédérales contre la pollution plastique, qu'ils considèrent nécessaires pour réduire les dommages environnementaux et sanitaires. Sources : `ecojustice_plastic_2026` - **Équiterre** — stance `+3`, côté `pro`, parent `plastic_gov_regulation` : Équiterre soutient que la réduction des déchets doit remonter à la source et responsabiliser davantage les producteurs, plutôt que reposer principalement sur les gestes individuels de tri et de recyclage. Sources : `equiterre_production_consumption` **Inventaire des sources du débat** - `canada_single_use_plastics` — **Environment and Climate Change Canada**, *Single-use Plastics Prohibition Regulations — Overview* (date non fixée dans le sidecar) — https://www.canada.ca/en/environment-climate-change/services/managing-reducing-waste/reduce-plastic-waste/single-use-plastic-overview.html - `canada_plastics_amendments_2026` — **Environment and Climate Change Canada**, *Proposed amendments to the Single-use Plastics Prohibition Regulations* (2026-03-13) — https://www.canada.ca/en/environment-climate-change/corporate/transparency/consultations/proposed-amendments-single-use-plastics-prohibition-regulations.html - `canada_plastics_registry` — **Environment and Climate Change Canada**, *Federal Plastics Registry* (date non fixée dans le sidecar) — https://www.canada.ca/en/environment-climate-change/services/managing-reducing-waste/reduce-plastic-waste/federal-plastics-registry.html - `cpc_plastics_packaging` — **Conservative Party of Canada**, *Axe the Food Packaging Tax* (date non fixée dans le sidecar) — https://www.conservative.ca/axe-the-food-packaging-tax/ - `ecojustice_plastic_2026` — **Ecojustice**, *Health and environmental groups celebrate victory in plastic pollution regulation case* (2026-01-30) — https://ecojustice.ca/news/health-and-environmental-groups-celebrate-victory-in-plastic-pollution-regulation-case/ - `equiterre_production_consumption` — **Équiterre**, *Production et consommation* (date non fixée dans le sidecar) — https://www.equiterre.org/fr/notre-travail/production-et-consommation ### 11. Le Québec devrait-il miser davantage sur une culture commune et la francisation que sur un modèle multiculturaliste pour renforcer la cohésion sociale? Débat sur les modèles d'intégration, la langue française, les valeurs communes, le pluralisme, la lutte contre la discrimination et le sentiment d'appartenance. **Pôle + :** Culture commune, français et intégration nationale comme cadre principal **Pôle − :** Multiculturalisme et pluralisme comme cadre principal de cohésion **Acteurs / arguments** - **Gouvernement du Québec** — stance `+3`, côté `pro` : La nouvelle politique québécoise d'intégration nationale met l'accent sur le français, une culture commune et l'adhésion à des repères collectifs comme fondements de l'intégration et de la cohésion sociale. Sources : `quebec_integration_policy_2026`, `quebec_integration_action` - **Gouvernement du Canada** — stance `-2`, côté `con` : La politique fédérale de multiculturalisme considère le pluralisme, la lutte contre le racisme et la reconnaissance de la diversité comme des composantes de l'unité nationale et de la cohésion sociale canadienne. Sources : `canada_multiculturalism_overview`, `canada_multiculturalism_cohesion_2026` - **Parti Québécois** — stance `+3`, côté `pro`, parent `cohesion_quebec_common_culture` : Le Parti Québécois lie la cohésion à l'intégration à une nation québécoise de langue française, à une politique d'immigration compatible avec la capacité d'accueil et à la protection d'un espace culturel commun, tout en affirmant vouloir lutter contre le racisme et la discrimination. Sources : `pq_immigration_plan_2026`, `pq_project_national_2026` - **Bloc Québécois** — stance `+3`, côté `pro`, parent `cohesion_quebec_common_culture` : Le Bloc défend un modèle québécois d'intégration centré sur le français, la nation québécoise et l'égalité dans la diversité, qu'il oppose au cadre multiculturaliste fédéral lorsqu'il estime que celui-ci affaiblit l'intégration linguistique et culturelle. Sources : `bq_immigration_capacity_2025` **Inventaire des sources du débat** - `quebec_integration_policy_2026` — **Gouvernement du Québec**, *Politique québécoise d'intégration nationale* (2026-07-16) — https://www.quebec.ca/gouvernement/ministeres-organismes/langue-francaise/publications/politique-integration-nationale - `quebec_integration_action` — **Gouvernement du Québec**, *Plan d'action de développement durable 2023-2028 — Immigration, francisation et intégration* (date non fixée dans le sidecar) — https://www.quebec.ca/gouvernement/ministeres-organismes/immigration/publications/plan-action-developpement-durable-2023-2028 - `canada_multiculturalism_overview` — **Canadian Heritage**, *Overview — Canadian identity, culture and multiculturalism* (date non fixée dans le sidecar) — https://www.canada.ca/en/canadian-heritage/corporate/transparency/open-government/standing-committee/guilbeault-identity-culture-september-2025/overview.html - `canada_multiculturalism_cohesion_2026` — **Canadian Heritage**, *Other items of interest — Multiculturalism and anti-racism* (2026-06) — https://www.canada.ca/en/canadian-heritage/corporate/transparency/open-government/standing-committee/bilodeau-pacp-public-accounts-june-2026/other-items-interest.html - `pq_immigration_plan_2026` — **Parti Québécois**, *Plan en immigration — un modèle viable* (2026) — https://pq.org/independance/plan-immigration/ - `pq_project_national_2026` — **Parti Québécois**, *Projet national — proposition principale 2026* (2026-05) — https://pq.org/wp-content/uploads/2026/05/PQ-PROPOSITION-PRINCIPALE-PROJET-NATIONAL-V5-individuel.pdf - `bq_immigration_capacity_2025` — **Bloc Québécois**, *Seul le Québec peut assurer l’immigration réussie* (2025-04-21) — https://www.blocquebecois.org/seul-le-quebec-peut-assurer-limmigration-reussie/ ### 12. Le Canada devrait-il accélérer la transition vers l'énergie propre même si cela impose des coûts aux secteurs fossiles à court terme? Débat sur l'électrification, la réduction des émissions, le pétrole et le gaz, les technologies de captage, les coûts de l'énergie, la compétitivité et les objectifs climatiques. **Pôle + :** Accélération de l'électrification et de la transition même avec coûts de court terme **Pôle − :** Transition plus graduelle maintenant une forte production d'hydrocarbures et misant sur la technologie **Acteurs / arguments** - **Gouvernement du Canada** — stance `+2`, côté `pro` : Ottawa mise sur l'électricité propre, l'électrification et les investissements dans les réseaux pour réduire les émissions tout en renforçant la compétitivité d'une économie appelée à consommer beaucoup plus d'électricité. Sources : `canada_clean_electricity`, `canada_2030_emissions_plan` - **Gouvernement du Québec** — stance `+3`, côté `pro` : Le Québec poursuit son Plan pour une économie verte en misant fortement sur l'électrification, l'efficacité énergétique et la réduction des émissions, avec l'hydroélectricité comme avantage stratégique. Sources : `quebec_green_economy_plan`, `quebec_green_implementation` - **Gouvernement de l'Alberta** — stance `-1`, côté `con` : L'Alberta privilégie une trajectoire qui combine réduction d'émissions, tarification industrielle, captage du carbone et technologies propres avec le maintien ou l'augmentation de la production pétrolière; elle rejette une transition fondée sur une sortie rapide des hydrocarbures. Sources : `alberta_tier`, `alberta_west_coast_pipeline` - **Parti Québécois** — stance `+3`, côté `pro`, parent `climate_quebec_green_plan` : Le Parti Québécois propose une transition verte plus contraignante, avec budget carbone, test climat, électrification, efficacité énergétique, hausse de la production renouvelable et réduction de l'utilisation des combustibles fossiles dans l'industrie. Sources : `pq_project_national_2026` - **Québec solidaire** — stance `+3`, côté `pro`, parent `climate_quebec_green_plan` : Québec solidaire défend une transition sociale et écologique rapide fondée sur le transport collectif électrifié, la sortie des hydrocarbures, le développement des énergies renouvelables et une planification avec les travailleurs, les communautés vulnérables et les peuples autochtones. Sources : `qs_workers_manifest` - **Équiterre** — stance `+3`, côté `pro`, parent `climate_quebec_green_plan` : Équiterre demande une politique climatique plus ambitieuse et plus cohérente, notamment un marché du carbone plus efficace et des décisions de grands projets qui n'affaiblissent pas les protections environnementales au nom de la vitesse. Sources : `equiterre_spede_2026`, `equiterre_major_projects_2026` **Inventaire des sources du débat** - `canada_clean_electricity` — **Government of Canada**, *Clean electricity* (2026-05-27) — https://www.canada.ca/en/services/environment/weather/climatechange/climate-plan/clean-electricity.html - `canada_2030_emissions_plan` — **Government of Canada**, *2030 Emissions Reduction Plan* (date non fixée dans le sidecar) — https://www.canada.ca/en/services/environment/weather/climatechange/climate-plan/climate-plan-overview/emissions-reduction-2030.html - `quebec_green_economy_plan` — **Gouvernement du Québec**, *Plan pour une économie verte 2030* (2026-07-29) — https://www.quebec.ca/gouvernement/politiques-orientations/plan-economie-verte - `quebec_green_implementation` — **Gouvernement du Québec**, *Plan de mise en œuvre du Plan pour une économie verte* (2026-06-29) — https://www.quebec.ca/gouvernement/politiques-orientations/plan-economie-verte/plan-mise-en-oeuvre - `alberta_tier` — **Government of Alberta**, *Technology Innovation and Emissions Reduction Regulation* (date non fixée dans le sidecar) — https://www.alberta.ca/technology-innovation-and-emissions-reduction-regulation - `alberta_west_coast_pipeline` — **Government of Alberta**, *West Coast oil pipeline* (2026-07) — https://www.alberta.ca/west-coast-oil-pipeline - `pq_project_national_2026` — **Parti Québécois**, *Projet national — proposition principale 2026* (2026-05) — https://pq.org/wp-content/uploads/2026/05/PQ-PROPOSITION-PRINCIPALE-PROJET-NATIONAL-V5-individuel.pdf - `qs_workers_manifest` — **Québec solidaire**, *Manifeste pour un Québec solidaire de ses travailleuses et travailleurs* (date non fixée dans le sidecar) — https://appuyez.quebecsolidaire.net/manifeste - `equiterre_spede_2026` — **Équiterre**, *Une réforme qui manque d’ambition* (2026-07-14) — https://www.equiterre.org/fr/ressources/601-recommandation-politique-reforme-spede - `equiterre_major_projects_2026` — **Équiterre**, *Comment bâtir un Canada fort en freinant la transition?* (2026-06-15) — https://www.equiterre.org/fr/ressources/comment-b%C3%A2tir-un-canada-fort-en-freinant-la-transition ### 13. Le Canada devrait-il adopter une politique industrielle plus interventionniste pour conserver au pays l'IA, la propriété intellectuelle, les données et les entreprises technologiques? Débat sur la commercialisation de la recherche, la propriété intellectuelle, l'adoption de l'IA, les infrastructures de calcul, les marchés publics, le capital de croissance et la souveraineté technologique. **Pôle + :** Politique industrielle et souveraineté technologique plus interventionnistes **Pôle − :** Approche davantage fondée sur le marché et l'ouverture internationale du capital et des actifs **Acteurs / arguments** - **Gouvernement du Canada** — stance `+2`, côté `pro` : La stratégie fédérale sur l'IA vise à augmenter fortement l'adoption de l'IA par les entreprises, développer les compétences et renforcer les infrastructures de calcul et les capacités nationales afin de convertir la recherche canadienne en gains économiques. Sources : `ised_national_ai_strategy_2026` - **Council of Canadian Innovators** — stance `+3`, côté `pro` : Le Council of Canadian Innovators demande une politique plus explicite de souveraineté économique : conserver la propriété intellectuelle et les données au Canada, utiliser les marchés publics pour faire grandir les entreprises locales et soutenir leur passage à l'échelle. Sources : `cci_innovation_power_2026`, `cci_quebec_election_2026`, `cci_public_procurement` - **Statistique Canada** — stance `+0`, côté `neutral` : Les travaux de Statistique Canada montrent à la fois le potentiel de l'IA pour relever la croissance de la productivité et la faiblesse persistante de la productivité canadienne, ce qui fait de l'adoption et de la diffusion technologique un enjeu central. Sources : `statcan_ai_productivity_2026`, `statcan_productivity_competition_2026` **Inventaire des sources du débat** - `ised_national_ai_strategy_2026` — **Innovation, Science and Economic Development Canada**, *Canada's National Artificial Intelligence Strategy* (2026-06-08) — https://ised-isde.canada.ca/site/ised/en/canadas-national-artificial-intelligence-strategy-ai-all - `statcan_ai_productivity_2026` — **Statistics Canada**, *Artificial intelligence and productivity growth in Canada* (2026-04-22) — https://www150.statcan.gc.ca/n1/pub/36-28-0001/2026004/article/00002-eng.htm - `statcan_productivity_competition_2026` — **Statistics Canada**, *Productivity and competition in Canada* (2026) — https://www150.statcan.gc.ca/n1/pub/11f0019m/11f0019m2026002-eng.htm - `cci_innovation_power_2026` — **Council of Canadian Innovators**, *Innovation as Power: The Choices That Will Define 2026* (2026-01-16) — https://www.canadianinnovators.org/content/innovation-as-power-the-choices-that-will-define-2026 - `cci_quebec_election_2026` — **Council of Canadian Innovators**, *2026 Quebec Election Primer: What Innovators Need to Scale* (2026-07-16) — https://www.canadianinnovators.org/content/2026-quebec-election-primer-what-innovators-need-to-scale - `cci_public_procurement` — **Council of Canadian Innovators**, *Buying What We Build: A CCI Policy Report on Public Buying for Canadian Innovation and Prosperity* (date non fixée dans le sidecar) — https://www.canadianinnovators.org/content/buying-what-we-build-a-cci-policy-report-on-public-buying-for-canadian-innovation-and-prosperity