diff --git a/.claude/PROJECT.adoc b/.claude/PROJECT.adoc new file mode 100644 index 0000000..815714c --- /dev/null +++ b/.claude/PROJECT.adoc @@ -0,0 +1,33 @@ +== The-Nash-Equilibrium - Claude Code Instructions + +This repository contains the The-Nash-Equilibrium project. + +=== Project Structure + +.... +the-nash-equilibrium/ +├── .claude/ # AI assistant instructions +├── .git/ # Version control +├── .gitignore # Git ignore rules +├── .editorconfig # Editor configuration +└── ... # Project files +.... + +=== Build Commands + +Refer to project-specific documentation. + +=== Coding Conventions + +* Follow hyperpolymath standards +* All code must have SPDX license headers +* Use approved languages only (see CLAUDE.md) +* Document all non-obvious decisions + +=== Security + +* No hardcoded secrets +* All secrets through environment variables or secret management +* SHA-pinned dependencies where applicable +* HTTPS only, no HTTP URLs +* No MD5/SHA1 for security purposes diff --git a/.claude/PROJECT.md b/.claude/PROJECT.md deleted file mode 100644 index 4cd84b4..0000000 --- a/.claude/PROJECT.md +++ /dev/null @@ -1,33 +0,0 @@ -# The-Nash-Equilibrium - Claude Code Instructions - -This repository contains the The-Nash-Equilibrium project. - -## Project Structure - -``` -the-nash-equilibrium/ -├── .claude/ # AI assistant instructions -├── .git/ # Version control -├── .gitignore # Git ignore rules -├── .editorconfig # Editor configuration -└── ... # Project files -``` - -## Build Commands - -Refer to project-specific documentation. - -## Coding Conventions - -- Follow hyperpolymath standards -- All code must have SPDX license headers -- Use approved languages only (see CLAUDE.md) -- Document all non-obvious decisions - -## Security - -- No hardcoded secrets -- All secrets through environment variables or secret management -- SHA-pinned dependencies where applicable -- HTTPS only, no HTTP URLs -- No MD5/SHA1 for security purposes diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..ca1c652 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..5949bf0 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,9 @@ +== Contributing + +[arabic] +. Fork the repository +. Create a feature branch +. Ensure SPDX headers on all files +. Submit a pull request + +*Author:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 8725e71..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,9 +0,0 @@ - -# Contributing - -1. Fork the repository -2. Create a feature branch -3. Ensure SPDX headers on all files -4. Submit a pull request - -**Author:** Jonathan D.A. Jewell diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..7fa19c7 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,11 @@ +== Security Policy + +=== Reporting a Vulnerability + +*Email:* j.d.a.jewell@open.ac.uk + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5aecb31..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,13 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -**Email:** j.d.a.jewell@open.ac.uk - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/mvt/README.adoc b/mvt/README.adoc new file mode 100644 index 0000000..754defb --- /dev/null +++ b/mvt/README.adoc @@ -0,0 +1,42 @@ +== Econosphere MVT 0.0: Public Goods Kernel + +Rollback prototype for testing only the core public-goods dilemma: + +[source,text] +---- +private growth -> shared stress -> pledge -> defection/cooperation -> collapse or survival +---- + +This directory is intentionally self-contained and dependency-free. The +active ruleset is `+mvt-public-goods-kernel+` in `+src/kernel+`. The +larger Alpha 0.1 engine remains in `+src/engine+` for later reuse, but +the UI now runs the simplified thesis test. + +=== Run + +[source,sh] +---- +cd mvt +deno task test +deno task serve +---- + +Then open `+http://localhost:5173/+`. + +=== Scope + +Implemented: + +* 4 asymmetric roles +* 5-turn deterministic state machine +* One private value: Prosperity +* One shared danger track: System Stress +* One pledge type: Stewardship Pledge +* Three actions: Develop, Steward, Hedge +* Deterministic crisis bands and highest-contributor penalty +* Save/load/export as JSON through local browser controls +* Event log, stress history, turn history, collapse gate, endgame +explanation + +The active kernel can be imported independently from +`+src/kernel/index.js+`. diff --git a/mvt/README.md b/mvt/README.md deleted file mode 100644 index 84e1275..0000000 --- a/mvt/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# Econosphere MVT 0.0: Public Goods Kernel - -Rollback prototype for testing only the core public-goods dilemma: - -```text -private growth -> shared stress -> pledge -> defection/cooperation -> collapse or survival -``` - -This directory is intentionally self-contained and dependency-free. The active ruleset is `mvt-public-goods-kernel` in `src/kernel`. The larger Alpha 0.1 engine remains in `src/engine` for later reuse, but the UI now runs the simplified thesis test. - -## Run - -```sh -cd mvt -deno task test -deno task serve -``` - -Then open `http://localhost:5173/`. - -## Scope - -Implemented: - -- 4 asymmetric roles -- 5-turn deterministic state machine -- One private value: Prosperity -- One shared danger track: System Stress -- One pledge type: Stewardship Pledge -- Three actions: Develop, Steward, Hedge -- Deterministic crisis bands and highest-contributor penalty -- Save/load/export as JSON through local browser controls -- Event log, stress history, turn history, collapse gate, endgame explanation - -The active kernel can be imported independently from `src/kernel/index.js`. diff --git a/mvt/docs/changelog.adoc b/mvt/docs/changelog.adoc new file mode 100644 index 0000000..ceae332 --- /dev/null +++ b/mvt/docs/changelog.adoc @@ -0,0 +1,18 @@ +== Changelog + +=== MVT 0.0 + +* Rolled active prototype back to the public-goods kernel. +* Replaced resources with Prosperity. +* Replaced three stress tracks with one System Stress track. +* Replaced contracts with Stewardship Pledges. +* Replaced crisis deck with deterministic crisis bands. + +=== Alpha 0.1 Expanded Prototype + +* Added deterministic state engine. +* Added local hot-seat browser UI. +* Added content pack for roles, actions, assets, breakthroughs, +contracts, and crises. +* Added save/load via serialized JSON. +* Added playtest telemetry and final scoring analytics. diff --git a/mvt/docs/changelog.md b/mvt/docs/changelog.md deleted file mode 100644 index ccc2602..0000000 --- a/mvt/docs/changelog.md +++ /dev/null @@ -1,17 +0,0 @@ -# Changelog - -## MVT 0.0 - -- Rolled active prototype back to the public-goods kernel. -- Replaced resources with Prosperity. -- Replaced three stress tracks with one System Stress track. -- Replaced contracts with Stewardship Pledges. -- Replaced crisis deck with deterministic crisis bands. - -## Alpha 0.1 Expanded Prototype - -- Added deterministic state engine. -- Added local hot-seat browser UI. -- Added content pack for roles, actions, assets, breakthroughs, contracts, and crises. -- Added save/load via serialized JSON. -- Added playtest telemetry and final scoring analytics. diff --git a/mvt/docs/design-spec-alpha-0.1.adoc b/mvt/docs/design-spec-alpha-0.1.adoc new file mode 100644 index 0000000..be86cf7 --- /dev/null +++ b/mvt/docs/design-spec-alpha-0.1.adoc @@ -0,0 +1,30 @@ +== MVT 0.0: Public Goods Kernel + +This rollback intentionally tests less than Alpha 0.1. The active +prototype tests one question: + +[source,text] +---- +When private growth creates shared stress, will players sacrifice short-term advantage to prevent collapse? +---- + +=== Active Systems + +* Four asymmetric roles: Capitalist, Socialist, Green, Techno-Utopian +* One private value: Prosperity +* One shared danger track: System Stress +* One cooperation mechanism: Stewardship Pledge +* One collapse rule: System Stress 12+ means no winner + +=== Disabled For This Kernel + +* Multi-resource economy +* Three-track stress dashboard +* Asset market and buildings +* Breakthroughs and research +* Contract templates and trade economy +* Crisis deck +* Role-specific scoring formulas + +The expanded engine remains in `+src/engine+` for later reuse. The +active ruleset is `+mvt-public-goods-kernel+` in `+src/kernel+`. diff --git a/mvt/docs/design-spec-alpha-0.1.md b/mvt/docs/design-spec-alpha-0.1.md deleted file mode 100644 index eb0a457..0000000 --- a/mvt/docs/design-spec-alpha-0.1.md +++ /dev/null @@ -1,27 +0,0 @@ -# MVT 0.0: Public Goods Kernel - -This rollback intentionally tests less than Alpha 0.1. The active prototype tests one question: - -```text -When private growth creates shared stress, will players sacrifice short-term advantage to prevent collapse? -``` - -## Active Systems - -- Four asymmetric roles: Capitalist, Socialist, Green, Techno-Utopian -- One private value: Prosperity -- One shared danger track: System Stress -- One cooperation mechanism: Stewardship Pledge -- One collapse rule: System Stress 12+ means no winner - -## Disabled For This Kernel - -- Multi-resource economy -- Three-track stress dashboard -- Asset market and buildings -- Breakthroughs and research -- Contract templates and trade economy -- Crisis deck -- Role-specific scoring formulas - -The expanded engine remains in `src/engine` for later reuse. The active ruleset is `mvt-public-goods-kernel` in `src/kernel`. diff --git a/mvt/docs/playtest-form.adoc b/mvt/docs/playtest-form.adoc new file mode 100644 index 0000000..c8a2507 --- /dev/null +++ b/mvt/docs/playtest-form.adoc @@ -0,0 +1,26 @@ +== MVT 0.0 Playtest Form + +=== Session + +* Date: +* Players: +* Seed: +* Shared outcome: +* Winner or historical influence leader: + +=== Thesis Checks + +* Did growth feel tempting? +* Did System Stress feel caused by player choices? +* Did players voluntarily coordinate? +* Did public pledges create trust pressure? +* Was defection tempting at least once? +* Did Hedge feel rational but insufficient? +* Did collapse or survival feel caused by player decisions? + +=== Balance Notes + +* Strongest role: +* Weakest role: +* Most confusing rule: +* Most important turning point: diff --git a/mvt/docs/playtest-form.md b/mvt/docs/playtest-form.md deleted file mode 100644 index e5d93dc..0000000 --- a/mvt/docs/playtest-form.md +++ /dev/null @@ -1,26 +0,0 @@ -# MVT 0.0 Playtest Form - -## Session - -- Date: -- Players: -- Seed: -- Shared outcome: -- Winner or historical influence leader: - -## Thesis Checks - -- Did growth feel tempting? -- Did System Stress feel caused by player choices? -- Did players voluntarily coordinate? -- Did public pledges create trust pressure? -- Was defection tempting at least once? -- Did Hedge feel rational but insufficient? -- Did collapse or survival feel caused by player decisions? - -## Balance Notes - -- Strongest role: -- Weakest role: -- Most confusing rule: -- Most important turning point: diff --git a/mvt/docs/rules-alpha-0.1.adoc b/mvt/docs/rules-alpha-0.1.adoc new file mode 100644 index 0000000..3940f95 --- /dev/null +++ b/mvt/docs/rules-alpha-0.1.adoc @@ -0,0 +1,58 @@ +== Rules: MVT 0.0 Public Goods Kernel + +Players complete up to 5 turns. Each turn has four phases: + +[arabic] +. Pledge +. Choose Action +. Resolve +. Crisis Check + +Each player starts with 5 Prosperity, 0 Shield, and 0 Defection Marks. +System Stress starts at 3. If System Stress reaches 12 or more, the +system collapses and no one wins. + +=== Actions + +* Develop: +4 Prosperity, +2 System Stress. +* Steward: +1 Prosperity, -2 System Stress. +* Hedge: +2 Prosperity, gain 1 Shield this turn. + +=== Role Modifiers + +* Capitalist: Develop gives +1 additional Prosperity and +1 additional +System Stress. +* Socialist: Steward gives +1 Prosperity to the lowest-Prosperity +player. +* Green: Steward reduces 1 additional System Stress. +* Techno-Utopian: Hedge gives 1 additional Shield. + +=== Stewardship Pledge + +During Pledge, players publicly choose whether to pledge Steward. If a +pledged player chooses Steward, the pledge is fulfilled. If a pledged +player chooses Develop or Hedge, the pledge is broken: +1 Defection Mark +and +1 System Stress. + +If at least two pledged players actually Steward in the same turn, +Collective Stewardship succeeds: -2 additional System Stress and +1 +Prosperity to each fulfilling pledged player. + +=== Crisis Bands + +* System Stress 0-4: no crisis damage. +* System Stress 5-7: each player loses 1 Prosperity. +* System Stress 8-10: each player loses 2 Prosperity. +* System Stress 11: each player loses 3 Prosperity. +* System Stress 12+: collapse. + +Shield reduces crisis damage for that player only. During crisis, the +highest stress contributor this turn loses 1 additional Prosperity. Tied +highest contributors all take the penalty. + +=== Endgame + +Final Score = Prosperity - (2 × Defection Marks). + +If collapse occurs, no one wins and rankings are shown as historical +influence. If the system survives Turn 5, highest final score wins. diff --git a/mvt/docs/rules-alpha-0.1.md b/mvt/docs/rules-alpha-0.1.md deleted file mode 100644 index 61b200f..0000000 --- a/mvt/docs/rules-alpha-0.1.md +++ /dev/null @@ -1,45 +0,0 @@ -# Rules: MVT 0.0 Public Goods Kernel - -Players complete up to 5 turns. Each turn has four phases: - -1. Pledge -2. Choose Action -3. Resolve -4. Crisis Check - -Each player starts with 5 Prosperity, 0 Shield, and 0 Defection Marks. System Stress starts at 3. If System Stress reaches 12 or more, the system collapses and no one wins. - -## Actions - -- Develop: +4 Prosperity, +2 System Stress. -- Steward: +1 Prosperity, -2 System Stress. -- Hedge: +2 Prosperity, gain 1 Shield this turn. - -## Role Modifiers - -- Capitalist: Develop gives +1 additional Prosperity and +1 additional System Stress. -- Socialist: Steward gives +1 Prosperity to the lowest-Prosperity player. -- Green: Steward reduces 1 additional System Stress. -- Techno-Utopian: Hedge gives 1 additional Shield. - -## Stewardship Pledge - -During Pledge, players publicly choose whether to pledge Steward. If a pledged player chooses Steward, the pledge is fulfilled. If a pledged player chooses Develop or Hedge, the pledge is broken: +1 Defection Mark and +1 System Stress. - -If at least two pledged players actually Steward in the same turn, Collective Stewardship succeeds: -2 additional System Stress and +1 Prosperity to each fulfilling pledged player. - -## Crisis Bands - -- System Stress 0-4: no crisis damage. -- System Stress 5-7: each player loses 1 Prosperity. -- System Stress 8-10: each player loses 2 Prosperity. -- System Stress 11: each player loses 3 Prosperity. -- System Stress 12+: collapse. - -Shield reduces crisis damage for that player only. During crisis, the highest stress contributor this turn loses 1 additional Prosperity. Tied highest contributors all take the penalty. - -## Endgame - -Final Score = Prosperity - (2 × Defection Marks). - -If collapse occurs, no one wins and rankings are shown as historical influence. If the system survives Turn 5, highest final score wins.