From 13b3cb157662ff870c5c1ab7eb0a803bc62bcbd1 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:27:42 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CHANGELOG.adoc | 9 + CHANGELOG.md | 11 - CODE_OF_CONDUCT.adoc | 24 + CODE_OF_CONDUCT.md | 27 - CONTRIBUTING.adoc | 71 +++ CONTRIBUTING.md | 66 --- GOVERNANCE.adoc | 60 ++ GOVERNANCE.md | 60 -- README.adoc | 166 ++++++ README.md | 102 ---- SECURITY.adoc | 16 + SECURITY.md | 20 - TEST-NEEDS.adoc | 30 + TEST-NEEDS.md | 26 - .../ADR-001-three-agent-architecture.adoc | 126 +++++ decisions/ADR-001-three-agent-architecture.md | 102 ---- evaluations/README.adoc | 31 ++ evaluations/README.md | 23 - evaluations/productive-meandering-v0-v3.adoc | 278 ++++++++++ evaluations/productive-meandering-v0-v3.md | 163 ------ evaluations/v3-cross-project-consistency.adoc | 130 +++++ evaluations/v3-cross-project-consistency.md | 97 ---- .../2026-03-23-ambientops-meander.adoc | 98 ++++ .../2026-03-23-ambientops-meander.md | 71 --- .../2026-03-23-multi-session-synthesis.adoc | 82 +++ .../2026-03-23-multi-session-synthesis.md | 75 --- ...-03-23-stapeln-tsdm-hybrid-validation.adoc | 66 +++ ...26-03-23-stapeln-tsdm-hybrid-validation.md | 52 -- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 16 - .../breadth-first-engineering/README.adoc | 17 + .../breadth-first-engineering/README.md | 15 - .../contractile-lifecycle/README.adoc | 17 + methodologies/contractile-lifecycle/README.md | 15 - .../cross-project-propagation/README.adoc | 17 + .../cross-project-propagation/README.md | 15 - .../ecosystem-surface-campaign/README.adoc | 16 + .../ecosystem-surface-campaign/README.md | 15 - .../event-chain-critical-chain/README.adoc | 235 ++++++++ .../event-chain-critical-chain/README.md | 205 ------- methodologies/explainme-standard/README.adoc | 17 + methodologies/explainme-standard/README.md | 15 - .../external-link-crosscheck/README.adoc | 16 + .../external-link-crosscheck/README.md | 15 - .../floor-raise-campaign/README.adoc | 17 + methodologies/floor-raise-campaign/README.md | 15 - methodologies/git-cycle/README.adoc | 16 + methodologies/git-cycle/README.md | 15 - .../hypatia-feedback-loop/README.adoc | 127 +++++ methodologies/hypatia-feedback-loop/README.md | 111 ---- .../language-repo-taxonomy/README.adoc | 17 + .../language-repo-taxonomy/README.md | 15 - .../multi-agent-coordination/README.adoc | 84 +++ .../multi-agent-coordination/README.md | 70 --- .../panel-harness-autowiring/README.adoc | 16 + .../panel-harness-autowiring/README.md | 15 - methodologies/parallel-audit/README.adoc | 60 ++ methodologies/parallel-audit/README.md | 54 -- methodologies/pre-commit-gate/README.adoc | 16 + methodologies/pre-commit-gate/README.md | 15 - .../{README.md => README.adoc} | 512 +++++++++--------- .../proven-first-resolution/README.adoc | 17 + .../proven-first-resolution/README.md | 15 - methodologies/repo-enrollment/README.adoc | 17 + methodologies/repo-enrollment/README.md | 15 - methodologies/resource-management/README.adoc | 89 +++ methodologies/resource-management/README.md | 72 --- methodologies/rsr/README.adoc | 68 +++ methodologies/rsr/README.md | 56 -- .../session-design-document/README.adoc | 17 + .../session-design-document/README.md | 15 - .../spec-exhaustive-search/README.adoc | 17 + .../spec-exhaustive-search/README.md | 15 - methodologies/topology-standard/README.adoc | 17 + methodologies/topology-standard/README.md | 15 - .../traversal-mode-selection/README.adoc | 17 + .../traversal-mode-selection/README.md | 15 - methodologies/tsdm/README.adoc | 99 ++++ methodologies/tsdm/README.md | 84 --- methodologies/v-api-quality-gate/README.adoc | 17 + methodologies/v-api-quality-gate/README.md | 15 - .../verisimdb-instance-policy/README.adoc | 17 + .../verisimdb-instance-policy/README.md | 15 - methodologies/visibility-triad/README.adoc | 17 + methodologies/visibility-triad/README.md | 15 - 89 files changed, 2636 insertions(+), 2172 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md create mode 100644 decisions/ADR-001-three-agent-architecture.adoc delete mode 100644 decisions/ADR-001-three-agent-architecture.md create mode 100644 evaluations/README.adoc delete mode 100644 evaluations/README.md create mode 100644 evaluations/productive-meandering-v0-v3.adoc delete mode 100644 evaluations/productive-meandering-v0-v3.md create mode 100644 evaluations/v3-cross-project-consistency.adoc delete mode 100644 evaluations/v3-cross-project-consistency.md create mode 100644 field-reports/2026-03-23-ambientops-meander.adoc delete mode 100644 field-reports/2026-03-23-ambientops-meander.md create mode 100644 field-reports/2026-03-23-multi-session-synthesis.adoc delete mode 100644 field-reports/2026-03-23-multi-session-synthesis.md create mode 100644 field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.adoc delete mode 100644 field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md create mode 100644 methodologies/breadth-first-engineering/README.adoc delete mode 100644 methodologies/breadth-first-engineering/README.md create mode 100644 methodologies/contractile-lifecycle/README.adoc delete mode 100644 methodologies/contractile-lifecycle/README.md create mode 100644 methodologies/cross-project-propagation/README.adoc delete mode 100644 methodologies/cross-project-propagation/README.md create mode 100644 methodologies/ecosystem-surface-campaign/README.adoc delete mode 100644 methodologies/ecosystem-surface-campaign/README.md create mode 100644 methodologies/event-chain-critical-chain/README.adoc delete mode 100644 methodologies/event-chain-critical-chain/README.md create mode 100644 methodologies/explainme-standard/README.adoc delete mode 100644 methodologies/explainme-standard/README.md create mode 100644 methodologies/external-link-crosscheck/README.adoc delete mode 100644 methodologies/external-link-crosscheck/README.md create mode 100644 methodologies/floor-raise-campaign/README.adoc delete mode 100644 methodologies/floor-raise-campaign/README.md create mode 100644 methodologies/git-cycle/README.adoc delete mode 100644 methodologies/git-cycle/README.md create mode 100644 methodologies/hypatia-feedback-loop/README.adoc delete mode 100644 methodologies/hypatia-feedback-loop/README.md create mode 100644 methodologies/language-repo-taxonomy/README.adoc delete mode 100644 methodologies/language-repo-taxonomy/README.md create mode 100644 methodologies/multi-agent-coordination/README.adoc delete mode 100644 methodologies/multi-agent-coordination/README.md create mode 100644 methodologies/panel-harness-autowiring/README.adoc delete mode 100644 methodologies/panel-harness-autowiring/README.md create mode 100644 methodologies/parallel-audit/README.adoc delete mode 100644 methodologies/parallel-audit/README.md create mode 100644 methodologies/pre-commit-gate/README.adoc delete mode 100644 methodologies/pre-commit-gate/README.md rename methodologies/productive-meandering/{README.md => README.adoc} (71%) create mode 100644 methodologies/proven-first-resolution/README.adoc delete mode 100644 methodologies/proven-first-resolution/README.md create mode 100644 methodologies/repo-enrollment/README.adoc delete mode 100644 methodologies/repo-enrollment/README.md create mode 100644 methodologies/resource-management/README.adoc delete mode 100644 methodologies/resource-management/README.md create mode 100644 methodologies/rsr/README.adoc delete mode 100644 methodologies/rsr/README.md create mode 100644 methodologies/session-design-document/README.adoc delete mode 100644 methodologies/session-design-document/README.md create mode 100644 methodologies/spec-exhaustive-search/README.adoc delete mode 100644 methodologies/spec-exhaustive-search/README.md create mode 100644 methodologies/topology-standard/README.adoc delete mode 100644 methodologies/topology-standard/README.md create mode 100644 methodologies/traversal-mode-selection/README.adoc delete mode 100644 methodologies/traversal-mode-selection/README.md create mode 100644 methodologies/tsdm/README.adoc delete mode 100644 methodologies/tsdm/README.md create mode 100644 methodologies/v-api-quality-gate/README.adoc delete mode 100644 methodologies/v-api-quality-gate/README.md create mode 100644 methodologies/verisimdb-instance-policy/README.adoc delete mode 100644 methodologies/verisimdb-instance-policy/README.md create mode 100644 methodologies/visibility-triad/README.adoc delete mode 100644 methodologies/visibility-triad/README.md 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/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). 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/README.adoc b/README.adoc new file mode 100644 index 0000000..d852d9f --- /dev/null +++ b/README.adoc @@ -0,0 +1,166 @@ +Captured design decisions, learnings, and methodologies from AI-assisted +software development across the hyperpolymath ecosystem. + +== Purpose + +This repo is the *canonical home* for process knowledge that transcends +individual projects. When a pattern is discovered, validated, and +refined across multiple sessions, it lives here — not scattered across +memory files or buried in project docs/ directories. + +== Contents + +[width="100%",cols="50%,50%",options="header",] +|=== +|Directory |Description +|`+methodologies/productive-meandering/+` |Productive Meandering v3 — +maximal traversal task execution with weighted priorities, wave +discipline, spike requirement, and self-termination. Field-tested across +6 sessions. + +|`+methodologies/tsdm/+` |Triaxial Software Development Methodology — +Scope → Maintenance → Audit. The systematic counterpart to meandering. + +|`+methodologies/parallel-audit/+` |Parallel audit methodology — sending +multiple agents to audit the same repo from different angles with +exclusive scoping. + +|`+methodologies/multi-agent-coordination/+` |Multi-agent coordination +patterns — workspace locking, task sharing, conflict prevention, +alternating passes. + +|`+methodologies/resource-management/+` |Resource guardrails — token +budgets, disk/RAM limits, build staggering, artifact cleanup. Learned +the hard way. + +|`+methodologies/rsr/+` |Rhodium Standard Repositories — the +template-based repo methodology itself, treated as a methodology for +consideration and refinement. + +|`+methodologies/event-chain-critical-chain/+` |Event Chain Methodology ++ Critical Chain (Theory of Constraints). Focuses agent work on the +actual constraint — the bottleneck that limits throughput. Subordination +rule: non-constraint work is waste. + +|`+methodologies/hypatia-feedback-loop/+` |Automated methodology +learning via Hypatia’s neurosymbolic CI/CD loop. Bayesian confidence +updating, pattern promotion, neural coordination. Closes the loop +between methodology execution and methodology improvement. + +|`+methodologies/git-cycle/+` |Full git cycle: commit + .gitignore + +push + mirror in one pass. + +|`+methodologies/pre-commit-gate/+` |panic-attack assail before every +commit across all repos. + +|`+methodologies/proven-first-resolution/+` |Check proven repo for +formally verified alternatives before manual fixes. + +|`+methodologies/spec-exhaustive-search/+` |Multi-extension search +before claiming a spec file doesn’t exist. + +|`+methodologies/contractile-lifecycle/+` |Five contractile files per +repo (Mustfile, Trustfile, Dustfile, Intentfile, K9). + +|`+methodologies/language-repo-taxonomy/+` |14-section naming convention +for language repos from spec to deployment. + +|`+methodologies/breadth-first-engineering/+` |Work across all languages +in sweeps by layer, not one language at a time. + +|`+methodologies/floor-raise-campaign/+` |Audit repos for missing +standards, generate dispatch manifests, run fixes. + +|`+methodologies/ecosystem-surface-campaign/+` |14-touchpoint playbook +for maximising exposure of new formats and tools. + +|`+methodologies/visibility-triad/+` |Four coordinated campaigns: +claim-forge + avatar-foundry + git-seo + palimpsest-plasma. + +|`+methodologies/cross-project-propagation/+` |After building a pattern, +document which other projects should adopt it. + +|`+methodologies/traversal-mode-selection/+` |Ask depth-first / +breadth-first / no-stubbing before large multi-file work. + +|`+methodologies/explainme-standard/+` |EXPLAINME.adoc: +show-me-the-receipts file backing README claims. + +|`+methodologies/v-api-quality-gate/+` |Seven-category checklist for zig +implementations before awesome-v. + +|`+methodologies/panel-harness-autowiring/+` |panels/manifest.json +schema for PanLL auto-discovery and health probing. + +|`+methodologies/verisimdb-instance-policy/+` |Every project gets its +own VeriSimDB instance with unique port and volume. + +|`+methodologies/repo-enrollment/+` |Three-tier: git-private-farm → +Hypatia scanning → gitbot-fleet. + +|`+methodologies/topology-standard/+` |ASCII architecture diagram + +completion dashboard per repo. + +|`+methodologies/session-design-document/+` |Dated design document at +session start for cross-AI knowledge transfer. + +|`+methodologies/external-link-crosscheck/+` |Check open PRs and +submissions before archiving or reorganising repos. + +|`+evaluations/+` |Quantitative comparisons of methodology +effectiveness. 7 dimensions: efficiency, effectiveness, efficacy, +economy, elegance, equity, ethics. + +|`+decisions/+` |Architecture Decision Records (ADRs) for methodology +choices. + +|`+field-reports/+` |Session field reports — honest assessments of what +worked, what failed, and why. The raw data behind methodology +refinements. +|=== + +== How to Use + +[arabic] +. When starting a new project or session, check if a methodology here +applies +. Follow the methodology’s instructions (designed to be copy-pasted into +CLAUDE.md or used as session instructions) +. After the session, write a field report if you learned something new +. Update the methodology if the field report reveals a gap + +== Status + +[width="100%",cols="41%,11%,18%,30%",options="header",] +|=== +|Methodology |Version |Field Tests |Status +|Productive Meandering |v3 |6 |Active, refined +|TSDM |v1 |20+ |Active, stable +|Event Chain + Critical Chain |v1 |1 (retro) |Active, new +|Hypatia Feedback Loop |v1 |— |Active, connecting +|Parallel Audit |v2 |3 |Active, needs v3 +|Multi-Agent Coordination |v0 |2 |Design phase +|Resource Management |v1 |5+ |Active, stable +|RSR |v1 |500+ repos |Active, stable +|Contractile Lifecycle |v1 |100+ repos |Active, stable +|Breadth-First Engineering |v1 |14 languages |Active, stable +|16 others |v0-v1 |various |Stub — to be expanded +|=== + +== Key Insight + +These methodologies are not competitors — they’re tools for different +situations: + +* *TSDM* when you need guaranteed systematic coverage +* *Productive Meandering* when you need serendipitous discovery +* *Event Chain + Critical Chain* when you need to identify and work the +constraint +* *Hybrid (audit-then-focus)* for most real sessions (default) +* *Three-Agent Architecture* (proposed) for complex projects needing +both convergent and divergent work simultaneously +* *Parallel Audit* for pre-milestone comprehensive review +* *RSR* as the structural standard that all repos follow + +The art is knowing when to switch between them, and the field reports +are how we learn which works when. diff --git a/README.md b/README.md deleted file mode 100644 index 1f9188a..0000000 --- a/README.md +++ /dev/null @@ -1,102 +0,0 @@ - - -Captured design decisions, learnings, and methodologies from AI-assisted -software development across the hyperpolymath ecosystem. - -# Purpose - -This repo is the **canonical home** for process knowledge that -transcends individual projects. When a pattern is discovered, validated, -and refined across multiple sessions, it lives here — not scattered -across memory files or buried in project docs/ directories. - -# Contents - -| Directory | Description | -|----|----| -| `methodologies/productive-meandering/` | Productive Meandering v3 — maximal traversal task execution with weighted priorities, wave discipline, spike requirement, and self-termination. Field-tested across 6 sessions. | -| `methodologies/tsdm/` | Triaxial Software Development Methodology — Scope → Maintenance → Audit. The systematic counterpart to meandering. | -| `methodologies/parallel-audit/` | Parallel audit methodology — sending multiple agents to audit the same repo from different angles with exclusive scoping. | -| `methodologies/multi-agent-coordination/` | Multi-agent coordination patterns — workspace locking, task sharing, conflict prevention, alternating passes. | -| `methodologies/resource-management/` | Resource guardrails — token budgets, disk/RAM limits, build staggering, artifact cleanup. Learned the hard way. | -| `methodologies/rsr/` | Rhodium Standard Repositories — the template-based repo methodology itself, treated as a methodology for consideration and refinement. | -| `methodologies/event-chain-critical-chain/` | Event Chain Methodology + Critical Chain (Theory of Constraints). Focuses agent work on the actual constraint — the bottleneck that limits throughput. Subordination rule: non-constraint work is waste. | -| `methodologies/hypatia-feedback-loop/` | Automated methodology learning via Hypatia’s neurosymbolic CI/CD loop. Bayesian confidence updating, pattern promotion, neural coordination. Closes the loop between methodology execution and methodology improvement. | -| `methodologies/git-cycle/` | Full git cycle: commit + .gitignore + push + mirror in one pass. | -| `methodologies/pre-commit-gate/` | panic-attack assail before every commit across all repos. | -| `methodologies/proven-first-resolution/` | Check proven repo for formally verified alternatives before manual fixes. | -| `methodologies/spec-exhaustive-search/` | Multi-extension search before claiming a spec file doesn’t exist. | -| `methodologies/contractile-lifecycle/` | Five contractile files per repo (Mustfile, Trustfile, Dustfile, Intentfile, K9). | -| `methodologies/language-repo-taxonomy/` | 14-section naming convention for language repos from spec to deployment. | -| `methodologies/breadth-first-engineering/` | Work across all languages in sweeps by layer, not one language at a time. | -| `methodologies/floor-raise-campaign/` | Audit repos for missing standards, generate dispatch manifests, run fixes. | -| `methodologies/ecosystem-surface-campaign/` | 14-touchpoint playbook for maximising exposure of new formats and tools. | -| `methodologies/visibility-triad/` | Four coordinated campaigns: claim-forge + avatar-foundry + git-seo + palimpsest-plasma. | -| `methodologies/cross-project-propagation/` | After building a pattern, document which other projects should adopt it. | -| `methodologies/traversal-mode-selection/` | Ask depth-first / breadth-first / no-stubbing before large multi-file work. | -| `methodologies/explainme-standard/` | EXPLAINME.adoc: show-me-the-receipts file backing README claims. | -| `methodologies/v-api-quality-gate/` | Seven-category checklist for zig implementations before awesome-v. | -| `methodologies/panel-harness-autowiring/` | panels/manifest.json schema for PanLL auto-discovery and health probing. | -| `methodologies/verisimdb-instance-policy/` | Every project gets its own VeriSimDB instance with unique port and volume. | -| `methodologies/repo-enrollment/` | Three-tier: git-private-farm → Hypatia scanning → gitbot-fleet. | -| `methodologies/topology-standard/` | ASCII architecture diagram + completion dashboard per repo. | -| `methodologies/session-design-document/` | Dated design document at session start for cross-AI knowledge transfer. | -| `methodologies/external-link-crosscheck/` | Check open PRs and submissions before archiving or reorganising repos. | -| `evaluations/` | Quantitative comparisons of methodology effectiveness. 7 dimensions: efficiency, effectiveness, efficacy, economy, elegance, equity, ethics. | -| `decisions/` | Architecture Decision Records (ADRs) for methodology choices. | -| `field-reports/` | Session field reports — honest assessments of what worked, what failed, and why. The raw data behind methodology refinements. | - -# How to Use - -1. When starting a new project or session, check if a methodology here - applies - -2. Follow the methodology’s instructions (designed to be copy-pasted - into CLAUDE.md or used as session instructions) - -3. After the session, write a field report if you learned something new - -4. Update the methodology if the field report reveals a gap - -# Status - -| Methodology | Version | Field Tests | Status | -|------------------------------|---------|--------------|-----------------------| -| Productive Meandering | v3 | 6 | Active, refined | -| TSDM | v1 | 20+ | Active, stable | -| Event Chain + Critical Chain | v1 | 1 (retro) | Active, new | -| Hypatia Feedback Loop | v1 | — | Active, connecting | -| Parallel Audit | v2 | 3 | Active, needs v3 | -| Multi-Agent Coordination | v0 | 2 | Design phase | -| Resource Management | v1 | 5+ | Active, stable | -| RSR | v1 | 500+ repos | Active, stable | -| Contractile Lifecycle | v1 | 100+ repos | Active, stable | -| Breadth-First Engineering | v1 | 14 languages | Active, stable | -| 16 others | v0-v1 | various | Stub — to be expanded | - -# Key Insight - -These methodologies are not competitors — they’re tools for different -situations: - -- **TSDM** when you need guaranteed systematic coverage - -- **Productive Meandering** when you need serendipitous discovery - -- **Event Chain + Critical Chain** when you need to identify and work - the constraint - -- **Hybrid (audit-then-focus)** for most real sessions (default) - -- **Three-Agent Architecture** (proposed) for complex projects needing - both convergent and divergent work simultaneously - -- **Parallel Audit** for pre-milestone comprehensive review - -- **RSR** as the structural standard that all repos follow - -The art is knowing when to switch between them, and the field reports -are how we learn which works when. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*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 5c4d5e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**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/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..6892cb0 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — methodologies + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Structural validation |1 |tests/validate_structure.sh — required files, +format checks +|=== + +=== What’s Covered + +* [x] Required RSR files present (validate_structure.sh) +* [x] Content format spot-checks + +=== Still Missing (for CRG B+) + +* [ ] Link validation (external URLs) +* [ ] Content completeness checks +* [ ] CI integration for test script + +=== Run Tests + +[source,bash] +---- +bash tests/validate_structure.sh +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index db953ff..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,26 +0,0 @@ -# TEST-NEEDS.md — methodologies - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Structural validation | 1 | tests/validate_structure.sh — required files, format checks | - -## What's Covered - -- [x] Required RSR files present (validate_structure.sh) -- [x] Content format spot-checks - -## Still Missing (for CRG B+) - -- [ ] Link validation (external URLs) -- [ ] Content completeness checks -- [ ] CI integration for test script - -## Run Tests - -```bash -bash tests/validate_structure.sh -``` diff --git a/decisions/ADR-001-three-agent-architecture.adoc b/decisions/ADR-001-three-agent-architecture.adoc new file mode 100644 index 0000000..277b58c --- /dev/null +++ b/decisions/ADR-001-three-agent-architecture.adoc @@ -0,0 +1,126 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== ADR-001: Three-Agent Architecture (Diverge / Converge / TSDM) + +== Status: Proposed + +== Date: 2026-03-23 + +=== Context + +Current approaches use either: - Pure meandering (1 agent, random walk) +- Parallel meandering (3 agents, same mode, exclusive scopes) - +Sequential alternating (TSDM reads → meander builds → TSDM re-evaluates) + +User proposed: could three bots with _different approaches_ +intercommunicate and produce better results? + +=== Proposal + +Three specialised agents running in parallel with intercommunication: + +==== Agent Roles + +[width="100%",cols="17%,13%,36%,34%",options="header",] +|=== +|Agent |Mode |Responsibility |Communication +|*Diverge* |Divergent meandering |Find what’s unique/strongest, push it +further. Identify novel patterns, creative connections, research avenues +|Sends insights to TSDM for triage + +|*Converge* |Convergent meandering |Find gaps, fill them. Build +infrastructure, fix broken things. Standard completeness |Sends found +issues to TSDM for priority + +|*TSDM* |Systematic audit |Read state, maintain priority queue, track +coverage, prevent cherry-picking, enforce MUSTs |Sends prioritised tasks +to both agents +|=== + +==== Communication Protocol + +.... +TSDM reads STATE → produces initial priority queue + ↓ (queue items tagged: divergent / convergent / either) +Diverge takes divergent items Converge takes convergent items + ↓ ↓ +Diverge reports insights Converge reports found issues + ↓ ↓ + → Both report to TSDM → +TSDM re-evaluates, adjusts queue, checks coverage + ↓ +Next round... +.... + +==== What Each Agent Optimises For + +* *Diverge:* "`What makes this project special? Push that.`" +** Won’t fill gaps unless they’re in the project’s core strength +** Won’t standardise unless it amplifies uniqueness +** Will notice when convergent work is erasing what’s distinctive +* *Converge:* "`What’s missing? What’s broken? Fix that.`" +** Won’t add new features unless they complete existing ones +** Won’t explore unless exploration serves completeness +** Will notice when incomplete infrastructure blocks other work +* *TSDM:* "`What’s the current state? What MUSTs remain? Who’s +cherry-picking?`" +** Doesn’t write code — writes the priority queue +** Tracks coverage: which components have been visited? +** Detects cherry-picking: "`Converge has been in Ring 1 for 20 calls`" +** Detects scope creep: "`Diverge is designing Ring 5 without Ring 2 +passing`" +** Enforces the weighted priority system + +==== Advantages Over Current Approaches + +[arabic] +. *Natural tension prevents bias.* Diverge wants to amplify uniqueness; +Converge wants to standardise. TSDM mediates. Neither bias dominates. +. *TSDM prevents cherry-picking in real-time.* Current approach catches +it post-hoc (in the session-end report). With TSDM as live navigator, it +catches it mid-session and redirects. +. *Better task allocation.* Some work IS convergent (fix CI, update +docs). Some IS divergent (deepen type theory, explore novel +architecture). Instead of one agent context-switching between modes, +each agent stays in its natural mode. +. *Coverage guarantee + discovery.* TSDM ensures all MUSTs are visited. +Converge fills gaps systematically. Diverge finds surprises. Together +they cover what any single approach misses. + +==== Risks and Mitigations + +[width="100%",cols="23%,35%,42%",options="header",] +|=== +|Risk |Severity |Mitigation +|File contention (3 agents editing) |High |TSDM assigns exclusive file +scopes, not just dir scopes + +|Build mutex (only 1 compiler) |High |TSDM sequences build verification: +Converge builds first, then Diverge + +|Token cost (3x budget) |Medium |TSDM is read-only (~10K tokens). +Converge + Diverge share the build budget + +|Coordination overhead |Medium |TSDM is the single dispatcher — no +peer-to-peer communication needed + +|Diverge goes to Ring 5 |Medium |TSDM enforces ring ceiling on both +agents + +|Converge over-standardises |Low |Diverge’s reports flag when uniqueness +is being erased +|=== + +==== Implementation + +Could be implemented as: 1. *Three subagents* with TSDM as the main +context (cheapest) 2. *Three Claude instances* with shared task file +(most flexible) 3. *BoJ cartridge* that orchestrates the three roles +(most reusable) + +==== Decision + +*Status: Proposed.* Need to validate with a real session before +adopting. Suggested first test: a project with both infrastructure gaps +AND creative depth (IDApTIK? Ephapax?) where both convergent and +divergent work matter. diff --git a/decisions/ADR-001-three-agent-architecture.md b/decisions/ADR-001-three-agent-architecture.md deleted file mode 100644 index e5da05e..0000000 --- a/decisions/ADR-001-three-agent-architecture.md +++ /dev/null @@ -1,102 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# ADR-001: Three-Agent Architecture (Diverge / Converge / TSDM) -# Status: Proposed -# Date: 2026-03-23 - -## Context - -Current approaches use either: -- Pure meandering (1 agent, random walk) -- Parallel meandering (3 agents, same mode, exclusive scopes) -- Sequential alternating (TSDM reads → meander builds → TSDM re-evaluates) - -User proposed: could three bots with *different approaches* intercommunicate -and produce better results? - -## Proposal - -Three specialised agents running in parallel with intercommunication: - -### Agent Roles - -| Agent | Mode | Responsibility | Communication | -|-------|------|----------------|---------------| -| **Diverge** | Divergent meandering | Find what's unique/strongest, push it further. Identify novel patterns, creative connections, research avenues | Sends insights to TSDM for triage | -| **Converge** | Convergent meandering | Find gaps, fill them. Build infrastructure, fix broken things. Standard completeness | Sends found issues to TSDM for priority | -| **TSDM** | Systematic audit | Read state, maintain priority queue, track coverage, prevent cherry-picking, enforce MUSTs | Sends prioritised tasks to both agents | - -### Communication Protocol - -``` -TSDM reads STATE → produces initial priority queue - ↓ (queue items tagged: divergent / convergent / either) -Diverge takes divergent items Converge takes convergent items - ↓ ↓ -Diverge reports insights Converge reports found issues - ↓ ↓ - → Both report to TSDM → -TSDM re-evaluates, adjusts queue, checks coverage - ↓ -Next round... -``` - -### What Each Agent Optimises For - -- **Diverge:** "What makes this project special? Push that." - - Won't fill gaps unless they're in the project's core strength - - Won't standardise unless it amplifies uniqueness - - Will notice when convergent work is erasing what's distinctive - -- **Converge:** "What's missing? What's broken? Fix that." - - Won't add new features unless they complete existing ones - - Won't explore unless exploration serves completeness - - Will notice when incomplete infrastructure blocks other work - -- **TSDM:** "What's the current state? What MUSTs remain? Who's cherry-picking?" - - Doesn't write code — writes the priority queue - - Tracks coverage: which components have been visited? - - Detects cherry-picking: "Converge has been in Ring 1 for 20 calls" - - Detects scope creep: "Diverge is designing Ring 5 without Ring 2 passing" - - Enforces the weighted priority system - -### Advantages Over Current Approaches - -1. **Natural tension prevents bias.** Diverge wants to amplify uniqueness; - Converge wants to standardise. TSDM mediates. Neither bias dominates. - -2. **TSDM prevents cherry-picking in real-time.** Current approach catches - it post-hoc (in the session-end report). With TSDM as live navigator, - it catches it mid-session and redirects. - -3. **Better task allocation.** Some work IS convergent (fix CI, update docs). - Some IS divergent (deepen type theory, explore novel architecture). - Instead of one agent context-switching between modes, each agent stays - in its natural mode. - -4. **Coverage guarantee + discovery.** TSDM ensures all MUSTs are visited. - Converge fills gaps systematically. Diverge finds surprises. Together - they cover what any single approach misses. - -### Risks and Mitigations - -| Risk | Severity | Mitigation | -|------|----------|------------| -| File contention (3 agents editing) | High | TSDM assigns exclusive file scopes, not just dir scopes | -| Build mutex (only 1 compiler) | High | TSDM sequences build verification: Converge builds first, then Diverge | -| Token cost (3x budget) | Medium | TSDM is read-only (~10K tokens). Converge + Diverge share the build budget | -| Coordination overhead | Medium | TSDM is the single dispatcher — no peer-to-peer communication needed | -| Diverge goes to Ring 5 | Medium | TSDM enforces ring ceiling on both agents | -| Converge over-standardises | Low | Diverge's reports flag when uniqueness is being erased | - -### Implementation - -Could be implemented as: -1. **Three subagents** with TSDM as the main context (cheapest) -2. **Three Claude instances** with shared task file (most flexible) -3. **BoJ cartridge** that orchestrates the three roles (most reusable) - -### Decision - -**Status: Proposed.** Need to validate with a real session before adopting. -Suggested first test: a project with both infrastructure gaps AND creative -depth (IDApTIK? Ephapax?) where both convergent and divergent work matter. diff --git a/evaluations/README.adoc b/evaluations/README.adoc new file mode 100644 index 0000000..35f6b41 --- /dev/null +++ b/evaluations/README.adoc @@ -0,0 +1,31 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Evaluations + +Quantitative and qualitative comparisons of methodology effectiveness. +Each evaluation uses real session data — not hypothetical projections. + +=== Contents + +[width="100%",cols="17%,47%,36%",options="header",] +|=== +|File |What it compares |Data source +|`+productive-meandering-v0-v3.md+` |Straight-line vs v1 vs v2 vs v3 +|Ambientops A/B test (2026-03-23) +|=== + +=== Evaluation Framework + +We assess methodologies across 7 dimensions: + +[arabic] +. *Efficiency* — output per token (how much work per unit cost?) +. *Effectiveness* — did it solve the right problems? (coverage, priority +alignment) +. *Efficacy* — did outcomes match intent? (waste ratio, bot accuracy) +. *Economy* — cost vs value (bots launched, waves needed, perfective +waste) +. *Elegance* — how clean is the process? (stopping conditions, coverage +tracking) +. *Equity* — fair allocation of effort (maturity bias, cherry-picking) +. *Ethics* — responsible resource use (builds, tokens, disk, RAM) diff --git a/evaluations/README.md b/evaluations/README.md deleted file mode 100644 index ceb1f91..0000000 --- a/evaluations/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Evaluations - -Quantitative and qualitative comparisons of methodology effectiveness. -Each evaluation uses real session data — not hypothetical projections. - -## Contents - -| File | What it compares | Data source | -|------|-----------------|-------------| -| `productive-meandering-v0-v3.md` | Straight-line vs v1 vs v2 vs v3 | Ambientops A/B test (2026-03-23) | - -## Evaluation Framework - -We assess methodologies across 7 dimensions: - -1. **Efficiency** — output per token (how much work per unit cost?) -2. **Effectiveness** — did it solve the right problems? (coverage, priority alignment) -3. **Efficacy** — did outcomes match intent? (waste ratio, bot accuracy) -4. **Economy** — cost vs value (bots launched, waves needed, perfective waste) -5. **Elegance** — how clean is the process? (stopping conditions, coverage tracking) -6. **Equity** — fair allocation of effort (maturity bias, cherry-picking) -7. **Ethics** — responsible resource use (builds, tokens, disk, RAM) diff --git a/evaluations/productive-meandering-v0-v3.adoc b/evaluations/productive-meandering-v0-v3.adoc new file mode 100644 index 0000000..5103018 --- /dev/null +++ b/evaluations/productive-meandering-v0-v3.adoc @@ -0,0 +1,278 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Evaluation: Productive Meandering v0 → v3 + +== Date: 2026-03-23 + +== Target: ambientops (same repo, same session, A/B comparison) + +== Evaluator: Claude Opus 4.6 + +=== Context + +v2 and v3 were run on the same target (ambientops) in the same session, +making this a genuine A/B comparison. v0 and v1 data is from prior +sessions. + +=== Comparison Table + +[width="100%",cols="14%,20%,20%,23%,23%",options="header",] +|=== +|Metric |v0 (no prompt) |v1 (Gossamer) |v2 (Ambientops) |v3 (Ambientops) +|*Session* |Baseline |2026-03-22 |2026-03-23 wave 1-2 |2026-03-23 wave 3 + +| | | | | + +|*Efficiency* (output per token) | | | | + +|Tokens consumed |~50K (est.) |~400K (est.) |~296K (5 bots) |~170K (est. +2 bots) + +|Files created/modified |1-3 |100+ |23 |est. 3-5 + +|Meaningful fixes |1 (stated task) |17 apps |21 |TBD + +|Tokens per meaningful fix |~50K |~23K |~14K |TBD + +| | | | | + +|*Effectiveness* (did it solve the right problems?) | | | | + +|P1 items from STATE addressed |n/a |n/a (no STATE read) |4/8 directly +|2/2 P1 items targeted + +|Critical surprises found |0 |unknown |4 |TBD + +|MUSTs skipped for COULDs |unknown |unknown |yes (HCT main.rs was P1, +fixed in wave 2 not wave 1) |0 by design + +|Coverage of components |1 |14 repos |6/29 (21%) |29/29 audited (100% +visibility) + +|Constraint identified |no |no |no (found by accident) |yes (Phase 0) + +| | | | | + +|*Efficacy* (did outcomes match intent?) | | | | + +|Stated goal achieved |yes |yes + 16x more |yes |TBD + +|Waste ratio (off-critical-chain work) |0% (only did stated task) +|unknown |~40% (TOPOLOGY, SPDX, docs) |est. <10% + +|Bot factual errors |n/a |n/a |1 (schema miscount) |TBD (cross-verify +built in) + +|Needed follow-up wave |no |no |yes (wave 2 for HCT) |TBD + +| | | | | + +|*Economy* (cost vs value) | | | | + +|Bots launched |0 |many |5 |2 + +|Waves needed |1 |1 |2 |TBD + +|Perfective work % |0% |unknown |~30% (docs, SPDX, TOPOLOGY) |0% by +design + +|Work that fed critical chain |100% (trivially) |unknown |~60% |est. +~90% + +| | | | | + +|*Elegance* (how clean is the process?) | | | | + +|Phase 0 (MUST-first) |no |no |no |yes + +|Constraint identified before work |no |no |no |yes + +|Priority ordering enforced |no |no |no (equal weight) |yes (3x/2x/1x) + +|Stopping condition defined |"`done`" |"`user says stop`" |wave cap = 2 +|constraint resolved + termination test + +|Coverage tracked |no |no |no |yes (29/29 audited) + +|Meander debt list produced |no |no |informal |formal + +| | | | | + +|*Equity* (fair allocation of effort?) | | | | + +|Maturity bias |n/a |unknown |yes (well-structured code got more +attention) |countered (least-mature check) + +|Cherry-picking |n/a |unknown |likely (TOPOLOGY before main.rs) +|prevented (difficulty-impact matrix) + +|Bot scope overlap |n/a |n/a |low (exclusive dirs) |zero (constraint + +read-only tracker) + +| | | | | + +|*Ethics* (responsible resource use?) | | | | + +|Parallel builds |n/a |unknown |1 per bot (rule) |1 total (constraint +bot only) + +|Token budget set upfront |no |no |yes (~30 calls) |yes (~25 calls) + +|Disk check before launch |no |no |yes |yes + +|Cruft tracking |no |no |informal |formal +|=== + +=== Key Tradeoffs + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +| |Straight-line (v0) |Meandering (v1-v2) |Constraint-first (v3) +|*Best at* |Known tasks, speed |Discovery, breadth |Critical path, depth + +|*Worst at* |Finding hidden issues |Priority, completion |Serendipity + +|*Failure mode* |Misses adjacent problems |Never arrives, cherry-picks +|Misses off-chain opportunities + +|*Token efficiency* |Highest (minimal waste) |Lowest (exploration tax) +|Medium (audit overhead) + +|*Discovery rate* |Zero (only does what’s asked) |Highest (random walk +finds surprises) |Medium (audit finds MUSTs, constraint analysis finds +chains) + +|*Completion guarantee* |Yes (trivially) |No (random walk) |Yes +(constraint resolution = done) + +|*Right work guarantee* |Only if user knows what’s right |No +(interesting > important) |Yes (critical chain enforces) +|=== + +=== Headline Numbers (v2 vs v3) — FINAL + +[width="100%",cols="35%,16%,16%,33%",options="header",] +|=== +|Metric |v2 |v3 |Change +|Bots launched |5 |2 |*-60%* + +|Tokens (actual) |296K |89K |*-70%* + +|Tool calls |159 |73 |*-54%* + +|Files touched |23 |4 |v2 more output + +|Critical chain unblocked |accidentally (wave 2) |by design (wave 1) |*1 +wave faster* + +|Components with coverage visibility |6/29 (21%) |29/29 (100%) |*+383%* + +|Skipped MUSTs detected |0 |12 (incl. 1 P0, 3 P1) |*v3 found what v2 +missed* + +|Perfective work (waste) |~30% of effort |0% |*eliminated* + +|Constraint identified |never (found by accident) |Phase 0, before any +bot launched |*systematic* + +|Cherry-picking confirmed |yes (by v3 audit) |no (matrix enforced) +|*structural fix* + +|Schema violations fixed |0 |7 |*v3 found the real work* +|=== + +==== What v3 found that v2 missed (skipped MUSTs) + +[cols=",,",options="header",] +|=== +|Priority |Component |Issue +|P0 |session-sentinel |56 SIGABRTs/4 days, disabled, D-Bus race +|P1 |nano-aider |Wrong author email (gmail.com) +|P1 |panoptes |MIT license, should be PMPL +|P1 |cicada |Stale "`Palimpsest v0.4`" naming +|P2 |total-recall |Uncustomised RSR template placeholder +|P2 |total-update |Same — \{\{PROJECT}} throughout +|P2 |reasonably-good-token-vault |Missing Idris2 ABI layer +|=== + +==== What v2 found that v3 wouldn’t have + +[width="100%",cols="57%,43%",options="header",] +|=== +|Finding |Value +|Duplicate observatory in system-tools/ |Structural (prevents future +confusion) + +|Stale Python in stale/ |Cleanup (removes banned code) + +|TOPOLOGY.md missing 25+ components |Documentation (onboarding) + +|broad-spectrum is a real ReScript project |Discovery (unknown component +found) +|=== + +=== Honest Caveats + +[arabic] +. *v3 completed and final numbers are in.* Updated 2026-03-23. +. *v3 benefits from v2’s work.* HCT compiles because v2 fixed main.rs. +The constraint analysis was easier because v2 built the components. v3 +on a fresh repo would need to do v2’s structural work first. This is not +a clean A/B — it’s a sequential comparison where v3 builds on v2’s +foundation. +. *v2 found more surprises.* v3’s constraint focus means it won’t +discover the duplicate observatory dir, the stale Python, or the 9th +schema debate. Those were genuinely useful v2 finds. Constraint-first +trades serendipity for precision. +. *v1 produced the most raw output.* 17 apps, a CLI, mobile support. Raw +output volume favours meandering. But output volume != the right output. +Many of those apps may never be used. +. *v0 is still the fastest for known tasks.* If you know exactly what to +do, just do it. The methodology overhead only pays off when you don’t +know what you don’t know. + +=== Progression Model + +.... +v0: Does what you say +v1: Discovers what you missed (but no priority) +v2: Discovers what you missed + wave discipline (but cherry-picks) +v3: Discovers what you missed + works on what matters most + (constraint-first + weighted priority + coverage tracking) +.... + +Each version keeps the previous version’s strengths and patches its +weaknesses. + +=== When to Use Which + +[width="100%",cols="46%,54%",options="header",] +|=== +|Situation |Best version +|"`Fix this one bug`" |v0 (straight-line) + +|"`Get this repo up to spec`" |v1-v2 (convergent meander) + +|"`What’s blocking this project?`" |v3 (constraint-first) + +|"`Explore what makes this special`" |v1 divergent mode + +|First session on a repo |v2 (discovery value is highest) + +|Second+ session on a repo |v3 (diminishing discovery returns, +constraint focus) + +|Pre-release audit |v3 + parallel audit v2 + +|Multiple surfaces at different maturity |v3 hybrid (audit-then-focus) +|=== + +=== Relationship to Other Methodologies + +* *TSDM* provides the navigator role that v3’s coverage tracker fills +* *Event Chain + Critical Chain* provides the constraint identification +that v3’s Phase 0 uses +* *Parallel Audit* provides the exclusive scoping that all versions use +for bots +* *Hypatia Feedback Loop* will eventually learn which version works best +for which repo type diff --git a/evaluations/productive-meandering-v0-v3.md b/evaluations/productive-meandering-v0-v3.md deleted file mode 100644 index e7dbe6e..0000000 --- a/evaluations/productive-meandering-v0-v3.md +++ /dev/null @@ -1,163 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Evaluation: Productive Meandering v0 → v3 -# Date: 2026-03-23 -# Target: ambientops (same repo, same session, A/B comparison) -# Evaluator: Claude Opus 4.6 - -## Context - -v2 and v3 were run on the same target (ambientops) in the same session, -making this a genuine A/B comparison. v0 and v1 data is from prior sessions. - -## Comparison Table - -| Metric | v0 (no prompt) | v1 (Gossamer) | v2 (Ambientops) | v3 (Ambientops) | -|--------|---------------|---------------|-----------------|-----------------| -| **Session** | Baseline | 2026-03-22 | 2026-03-23 wave 1-2 | 2026-03-23 wave 3 | -| | | | | | -| **Efficiency** (output per token) | | | | | -| Tokens consumed | ~50K (est.) | ~400K (est.) | ~296K (5 bots) | ~170K (est. 2 bots) | -| Files created/modified | 1-3 | 100+ | 23 | est. 3-5 | -| Meaningful fixes | 1 (stated task) | 17 apps | 21 | TBD | -| Tokens per meaningful fix | ~50K | ~23K | ~14K | TBD | -| | | | | | -| **Effectiveness** (did it solve the right problems?) | | | | | -| P1 items from STATE addressed | n/a | n/a (no STATE read) | 4/8 directly | 2/2 P1 items targeted | -| Critical surprises found | 0 | unknown | 4 | TBD | -| MUSTs skipped for COULDs | unknown | unknown | yes (HCT main.rs was P1, fixed in wave 2 not wave 1) | 0 by design | -| Coverage of components | 1 | 14 repos | 6/29 (21%) | 29/29 audited (100% visibility) | -| Constraint identified | no | no | no (found by accident) | yes (Phase 0) | -| | | | | | -| **Efficacy** (did outcomes match intent?) | | | | | -| Stated goal achieved | yes | yes + 16x more | yes | TBD | -| Waste ratio (off-critical-chain work) | 0% (only did stated task) | unknown | ~40% (TOPOLOGY, SPDX, docs) | est. <10% | -| Bot factual errors | n/a | n/a | 1 (schema miscount) | TBD (cross-verify built in) | -| Needed follow-up wave | no | no | yes (wave 2 for HCT) | TBD | -| | | | | | -| **Economy** (cost vs value) | | | | | -| Bots launched | 0 | many | 5 | 2 | -| Waves needed | 1 | 1 | 2 | TBD | -| Perfective work % | 0% | unknown | ~30% (docs, SPDX, TOPOLOGY) | 0% by design | -| Work that fed critical chain | 100% (trivially) | unknown | ~60% | est. ~90% | -| | | | | | -| **Elegance** (how clean is the process?) | | | | | -| Phase 0 (MUST-first) | no | no | no | yes | -| Constraint identified before work | no | no | no | yes | -| Priority ordering enforced | no | no | no (equal weight) | yes (3x/2x/1x) | -| Stopping condition defined | "done" | "user says stop" | wave cap = 2 | constraint resolved + termination test | -| Coverage tracked | no | no | no | yes (29/29 audited) | -| Meander debt list produced | no | no | informal | formal | -| | | | | | -| **Equity** (fair allocation of effort?) | | | | | -| Maturity bias | n/a | unknown | yes (well-structured code got more attention) | countered (least-mature check) | -| Cherry-picking | n/a | unknown | likely (TOPOLOGY before main.rs) | prevented (difficulty-impact matrix) | -| Bot scope overlap | n/a | n/a | low (exclusive dirs) | zero (constraint + read-only tracker) | -| | | | | | -| **Ethics** (responsible resource use?) | | | | | -| Parallel builds | n/a | unknown | 1 per bot (rule) | 1 total (constraint bot only) | -| Token budget set upfront | no | no | yes (~30 calls) | yes (~25 calls) | -| Disk check before launch | no | no | yes | yes | -| Cruft tracking | no | no | informal | formal | - -## Key Tradeoffs - -| | Straight-line (v0) | Meandering (v1-v2) | Constraint-first (v3) | -|---|---|---|---| -| **Best at** | Known tasks, speed | Discovery, breadth | Critical path, depth | -| **Worst at** | Finding hidden issues | Priority, completion | Serendipity | -| **Failure mode** | Misses adjacent problems | Never arrives, cherry-picks | Misses off-chain opportunities | -| **Token efficiency** | Highest (minimal waste) | Lowest (exploration tax) | Medium (audit overhead) | -| **Discovery rate** | Zero (only does what's asked) | Highest (random walk finds surprises) | Medium (audit finds MUSTs, constraint analysis finds chains) | -| **Completion guarantee** | Yes (trivially) | No (random walk) | Yes (constraint resolution = done) | -| **Right work guarantee** | Only if user knows what's right | No (interesting > important) | Yes (critical chain enforces) | - -## Headline Numbers (v2 vs v3) — FINAL - -| Metric | v2 | v3 | Change | -|--------|----|----|--------| -| Bots launched | 5 | 2 | **-60%** | -| Tokens (actual) | 296K | 89K | **-70%** | -| Tool calls | 159 | 73 | **-54%** | -| Files touched | 23 | 4 | v2 more output | -| Critical chain unblocked | accidentally (wave 2) | by design (wave 1) | **1 wave faster** | -| Components with coverage visibility | 6/29 (21%) | 29/29 (100%) | **+383%** | -| Skipped MUSTs detected | 0 | 12 (incl. 1 P0, 3 P1) | **v3 found what v2 missed** | -| Perfective work (waste) | ~30% of effort | 0% | **eliminated** | -| Constraint identified | never (found by accident) | Phase 0, before any bot launched | **systematic** | -| Cherry-picking confirmed | yes (by v3 audit) | no (matrix enforced) | **structural fix** | -| Schema violations fixed | 0 | 7 | **v3 found the real work** | - -### What v3 found that v2 missed (skipped MUSTs) - -| Priority | Component | Issue | -|----------|-----------|-------| -| P0 | session-sentinel | 56 SIGABRTs/4 days, disabled, D-Bus race | -| P1 | nano-aider | Wrong author email (gmail.com) | -| P1 | panoptes | MIT license, should be PMPL | -| P1 | cicada | Stale "Palimpsest v0.4" naming | -| P2 | total-recall | Uncustomised RSR template placeholder | -| P2 | total-update | Same — {{PROJECT}} throughout | -| P2 | reasonably-good-token-vault | Missing Idris2 ABI layer | - -### What v2 found that v3 wouldn't have - -| Finding | Value | -|---------|-------| -| Duplicate observatory in system-tools/ | Structural (prevents future confusion) | -| Stale Python in stale/ | Cleanup (removes banned code) | -| TOPOLOGY.md missing 25+ components | Documentation (onboarding) | -| broad-spectrum is a real ReScript project | Discovery (unknown component found) | - -## Honest Caveats - -1. **v3 completed and final numbers are in.** Updated 2026-03-23. - -2. **v3 benefits from v2's work.** HCT compiles because v2 fixed main.rs. The - constraint analysis was easier because v2 built the components. v3 on a fresh - repo would need to do v2's structural work first. This is not a clean A/B — - it's a sequential comparison where v3 builds on v2's foundation. - -3. **v2 found more surprises.** v3's constraint focus means it won't discover - the duplicate observatory dir, the stale Python, or the 9th schema debate. - Those were genuinely useful v2 finds. Constraint-first trades serendipity - for precision. - -4. **v1 produced the most raw output.** 17 apps, a CLI, mobile support. Raw - output volume favours meandering. But output volume != the right output. - Many of those apps may never be used. - -5. **v0 is still the fastest for known tasks.** If you know exactly what to do, - just do it. The methodology overhead only pays off when you don't know what - you don't know. - -## Progression Model - -``` -v0: Does what you say -v1: Discovers what you missed (but no priority) -v2: Discovers what you missed + wave discipline (but cherry-picks) -v3: Discovers what you missed + works on what matters most - (constraint-first + weighted priority + coverage tracking) -``` - -Each version keeps the previous version's strengths and patches its weaknesses. - -## When to Use Which - -| Situation | Best version | -|-----------|-------------| -| "Fix this one bug" | v0 (straight-line) | -| "Get this repo up to spec" | v1-v2 (convergent meander) | -| "What's blocking this project?" | v3 (constraint-first) | -| "Explore what makes this special" | v1 divergent mode | -| First session on a repo | v2 (discovery value is highest) | -| Second+ session on a repo | v3 (diminishing discovery returns, constraint focus) | -| Pre-release audit | v3 + parallel audit v2 | -| Multiple surfaces at different maturity | v3 hybrid (audit-then-focus) | - -## Relationship to Other Methodologies - -- **TSDM** provides the navigator role that v3's coverage tracker fills -- **Event Chain + Critical Chain** provides the constraint identification that v3's Phase 0 uses -- **Parallel Audit** provides the exclusive scoping that all versions use for bots -- **Hypatia Feedback Loop** will eventually learn which version works best for which repo type diff --git a/evaluations/v3-cross-project-consistency.adoc b/evaluations/v3-cross-project-consistency.adoc new file mode 100644 index 0000000..8b6c1c6 --- /dev/null +++ b/evaluations/v3-cross-project-consistency.adoc @@ -0,0 +1,130 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Evaluation: v3 Cross-Project Consistency Test + +== Date: 2026-03-23 + +== Projects: ambientops (infra), burble (platform), proven (research) + +=== Question + +Does v3 methodology produce consistent results across different project +types, and does it correctly adapt its mode +(convergent/divergent/hybrid)? + +=== Results + +[width="100%",cols="30%,28%,21%,21%",options="header",] +|=== +|Dimension |ambientops |burble |proven +|*Type* |Infrastructure |Platform |Research + +|*Mode selected* |Convergent |Convergent |Divergent + +|*Mode correct?* |Yes |Yes |Yes + +|*Constraint found?* |Yes (envelope flow) |Yes (missing deps) |Yes +(build unverified) + +|*Constraint type* |Wiring gap |Dependency gap |Pipeline gap + +|*Phase 0 worked?* |Yes (STATE valid) |Partial (STATE = template) +|Partial (STATE empty) + +|*v3 quality score* |8/10 |7/10 |8/10 +|=== + +=== Key Findings + +==== 1. Constraint identification is consistent (3/3) + +All three projects had a critical chain with a clear +first-unresolved-link. The constraint types varied (wiring, deps, +pipeline) but the identification method (build dependency graph → find +longest chain → find first break) worked identically across all three. + +==== 2. Mode selection is correct (3/3) + +v3 correctly chose convergent for infrastructure/platform and divergent +for research. The signals were clear in all cases. + +==== 3. Phase 0 has a STATE file reliability problem (2/3 failures) + +Only ambientops had a valid STATE.a2ml. Burble’s was an uncustomised +template. Proven’s was empty after SCM→A2ML migration. This means Phase +0 falls back to TODO.md/ROADMAP.adoc in most cases. + +*New refinement needed:* Validate STATE before trusting it: - Check for +\{\{PLACEHOLDER}} tokens - Check project name matches repo name - Check +last-updated within 90 days - Fall back to TODO/ROADMAP if validation +fails + +==== 4. Convergent gravity in divergent mode (proven-specific) + +The coverage audit step naturally pulls attention toward empty +components (102 scaffolded bindings, 12 stub apps). In convergent mode +this is correct (fill gaps). In divergent mode this is wrong (deepening +> breadth). The 70/30 budget split mitigates but doesn’t eliminate the +pull. + +*New refinement needed:* In divergent mode, the coverage audit should +ask "`which components carry the unique strength?`" not "`which +components are empty?`" Empty components are acceptable in divergent +projects. + +==== 5. "`Silent fallback`" is a new constraint pattern (burble-specific) + +Burble had fully-written QUIC and LMDB code that silently fell back to +WebSocket/ETS because the deps weren’t in mix.exs. This is invisible to +code review — the code looks complete. Only the constraint analysis +(tracing the dependency graph to find what’s actually wired) revealed +it. + +This pattern may exist in other projects: code that looks done but is +secretly using a fallback path because a dependency/config/flag is +missing. + +=== Consistency Verdict + +*v3 is consistent across project types.* The core mechanism (read state +→ build dependency graph → find constraint → work it) produces the right +priorities in infrastructure, platform, and research contexts. The mode +selection (convergent vs divergent) correctly adapts. + +The two weak points (STATE reliability, convergent gravity in divergent +mode) are addressable with refinements #25 and #26 to the methodology. + +=== What v3 Works Better For + +[width="100%",cols="46%,54%",options="header",] +|=== +|Situation |v3 Advantage +|Infrastructure with hidden wiring gaps |Strong — constraint analysis +finds silent failures + +|Platform with dependency issues |Strong — traces dep graph to find +missing links + +|Research with deep proof needs |Good — divergent mode focuses on unique +strength + +|Multi-component monorepos |Strong — coverage audit catches skipped +MUSTs + +|Projects with valid STATE files |Ideal — Phase 0 works perfectly +|=== + +=== What v3 Works Less Well For + +[width="100%",cols="62%,38%",options="header",] +|=== +|Situation |Issue +|Projects with broken/template STATE |Phase 0 starts with bad data + +|Divergent projects with many stubs |Coverage audit tempts convergent +filling + +|Very small projects (1-3 files) |Overhead not justified + +|Exploratory/greenfield work |No state to read, no constraint to find +|=== diff --git a/evaluations/v3-cross-project-consistency.md b/evaluations/v3-cross-project-consistency.md deleted file mode 100644 index 9438742..0000000 --- a/evaluations/v3-cross-project-consistency.md +++ /dev/null @@ -1,97 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Evaluation: v3 Cross-Project Consistency Test -# Date: 2026-03-23 -# Projects: ambientops (infra), burble (platform), proven (research) - -## Question - -Does v3 methodology produce consistent results across different project -types, and does it correctly adapt its mode (convergent/divergent/hybrid)? - -## Results - -| Dimension | ambientops | burble | proven | -|-----------|-----------|--------|--------| -| **Type** | Infrastructure | Platform | Research | -| **Mode selected** | Convergent | Convergent | Divergent | -| **Mode correct?** | Yes | Yes | Yes | -| **Constraint found?** | Yes (envelope flow) | Yes (missing deps) | Yes (build unverified) | -| **Constraint type** | Wiring gap | Dependency gap | Pipeline gap | -| **Phase 0 worked?** | Yes (STATE valid) | Partial (STATE = template) | Partial (STATE empty) | -| **v3 quality score** | 8/10 | 7/10 | 8/10 | - -## Key Findings - -### 1. Constraint identification is consistent (3/3) - -All three projects had a critical chain with a clear first-unresolved-link. -The constraint types varied (wiring, deps, pipeline) but the identification -method (build dependency graph → find longest chain → find first break) -worked identically across all three. - -### 2. Mode selection is correct (3/3) - -v3 correctly chose convergent for infrastructure/platform and divergent -for research. The signals were clear in all cases. - -### 3. Phase 0 has a STATE file reliability problem (2/3 failures) - -Only ambientops had a valid STATE.a2ml. Burble's was an uncustomised -template. Proven's was empty after SCM→A2ML migration. This means Phase 0 -falls back to TODO.md/ROADMAP.adoc in most cases. - -**New refinement needed:** Validate STATE before trusting it: -- Check for {{PLACEHOLDER}} tokens -- Check project name matches repo name -- Check last-updated within 90 days -- Fall back to TODO/ROADMAP if validation fails - -### 4. Convergent gravity in divergent mode (proven-specific) - -The coverage audit step naturally pulls attention toward empty components -(102 scaffolded bindings, 12 stub apps). In convergent mode this is -correct (fill gaps). In divergent mode this is wrong (deepening > breadth). -The 70/30 budget split mitigates but doesn't eliminate the pull. - -**New refinement needed:** In divergent mode, the coverage audit should -ask "which components carry the unique strength?" not "which components -are empty?" Empty components are acceptable in divergent projects. - -### 5. "Silent fallback" is a new constraint pattern (burble-specific) - -Burble had fully-written QUIC and LMDB code that silently fell back to -WebSocket/ETS because the deps weren't in mix.exs. This is invisible to -code review — the code looks complete. Only the constraint analysis -(tracing the dependency graph to find what's actually wired) revealed it. - -This pattern may exist in other projects: code that looks done but is -secretly using a fallback path because a dependency/config/flag is missing. - -## Consistency Verdict - -**v3 is consistent across project types.** The core mechanism (read state → -build dependency graph → find constraint → work it) produces the right -priorities in infrastructure, platform, and research contexts. The mode -selection (convergent vs divergent) correctly adapts. - -The two weak points (STATE reliability, convergent gravity in divergent mode) -are addressable with refinements #25 and #26 to the methodology. - -## What v3 Works Better For - -| Situation | v3 Advantage | -|-----------|-------------| -| Infrastructure with hidden wiring gaps | Strong — constraint analysis finds silent failures | -| Platform with dependency issues | Strong — traces dep graph to find missing links | -| Research with deep proof needs | Good — divergent mode focuses on unique strength | -| Multi-component monorepos | Strong — coverage audit catches skipped MUSTs | -| Projects with valid STATE files | Ideal — Phase 0 works perfectly | - -## What v3 Works Less Well For - -| Situation | Issue | -|-----------|-------| -| Projects with broken/template STATE | Phase 0 starts with bad data | -| Divergent projects with many stubs | Coverage audit tempts convergent filling | -| Very small projects (1-3 files) | Overhead not justified | -| Exploratory/greenfield work | No state to read, no constraint to find | diff --git a/field-reports/2026-03-23-ambientops-meander.adoc b/field-reports/2026-03-23-ambientops-meander.adoc new file mode 100644 index 0000000..f8d7950 --- /dev/null +++ b/field-reports/2026-03-23-ambientops-meander.adoc @@ -0,0 +1,98 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Field Report: Ambientops Productive Meander + +== Date: 2026-03-23 + +== Methodology: Productive Meandering v2 (then self-critiqued to inform v3) + +== Mode: Convergent + +=== Task + +"`Meander your bots through ambientops`" + +=== Execution + +==== Wave 1 (3 parallel bots) + +[width="100%",cols="15%,14%,21%,24%,26%",options="header",] +|=== +|Bot |Zone |Created |Modified |Surprises +|1 (ER+HCT) |emergency-room, hardware-crash-team |2 V files |3 files +|HCT main.rs broken skeleton + +|2 (Obs+Records) |observatory, records |10 Elixir files |2 files |No +NVMe weather category + +|3 (Infra) |CI, contracts, Justfile, docs |0 |6 files |TOPOLOGY.md +missing 25+ components +|=== + +*Wave 1 tokens:* ~205K across 3 bots *Wave 1 commit:* c8d8f5e (+2,517 +lines, 24 files) + +==== Wave 2 (2 parallel bots) + +[width="100%",cols="21%,23%,26%,30%",options="header",] +|=== +|Bot |Zone |Tasks |Result +|4 (HCT+Cleanup) |main.rs, stale Python, .gitignore |Fix compilation, +cleanup |HCT now compiles + +|5 (STATE+Docs) |STATE.a2ml, bt_sentinel, CLAUDE.md |Update state, add +stub |Schema count corrected +|=== + +*Wave 2 tokens:* ~92K across 2 bots *Wave 2 commit:* d1b0274 (+324 +lines, -573 lines) + +=== Surprise Test Results + +[cols=",",options="header",] +|=== +|Metric |Count +|Stated goals |8 +|Total fixes/improvements |21 +|Production-critical (would have failed) |4 +|Bot factual errors caught |1 +|=== + +==== Critical surprises: + +[arabic] +. HCT main.rs was a broken skeleton — no compilation possible +(pre-existing) +. Observatory had no NVMe weather category — sentinel would emit into +void +. TOPOLOGY.md missing 25+ components — any onboarding/audit would fail +. Duplicate observatory at `+system-tools/monitoring/observatory/+` + +==== Bot accuracy issue: + +Bot 3 claimed 9 contract schemas. Bot 5 verified 8. Cross-verification +prevented false documentation. + +=== What Worked + +* Ring 2 ceiling prevented cross-repo modification +* "`Note don’t action`" prevented scope creep into PanLL, +BundleIngestion +* Resource guardrails prevented parallel Rust builds +* Wave structure provided natural commit checkpoints + +=== What Didn’t Work + +* No priority ordering — bots treated docs and compilation equally +* Bot accuracy degraded at edges (schema miscount) +* No natural stopping condition — would have launched Wave 3 if not +stopped +* Convergence bias pulled toward polishing docs over finding structural +issues + +=== Methodology Improvements Identified + +→ These became v3 refinements: - Weighted priority (MUST 3x > SHOULD 2x +> COULD 1x) - MUST-first pass before meandering - Wave cap at 2 default +- Cross-verification of bot claims - Convergence budget (70/20/10) - +Meander debt list as committed artifact diff --git a/field-reports/2026-03-23-ambientops-meander.md b/field-reports/2026-03-23-ambientops-meander.md deleted file mode 100644 index e6a87bc..0000000 --- a/field-reports/2026-03-23-ambientops-meander.md +++ /dev/null @@ -1,71 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Field Report: Ambientops Productive Meander -# Date: 2026-03-23 -# Methodology: Productive Meandering v2 (then self-critiqued to inform v3) -# Mode: Convergent - -## Task -"Meander your bots through ambientops" - -## Execution - -### Wave 1 (3 parallel bots) - -| Bot | Zone | Created | Modified | Surprises | -|-----|------|---------|----------|-----------| -| 1 (ER+HCT) | emergency-room, hardware-crash-team | 2 V files | 3 files | HCT main.rs broken skeleton | -| 2 (Obs+Records) | observatory, records | 10 Elixir files | 2 files | No NVMe weather category | -| 3 (Infra) | CI, contracts, Justfile, docs | 0 | 6 files | TOPOLOGY.md missing 25+ components | - -**Wave 1 tokens:** ~205K across 3 bots -**Wave 1 commit:** c8d8f5e (+2,517 lines, 24 files) - -### Wave 2 (2 parallel bots) - -| Bot | Zone | Tasks | Result | -|-----|------|-------|--------| -| 4 (HCT+Cleanup) | main.rs, stale Python, .gitignore | Fix compilation, cleanup | HCT now compiles | -| 5 (STATE+Docs) | STATE.a2ml, bt_sentinel, CLAUDE.md | Update state, add stub | Schema count corrected | - -**Wave 2 tokens:** ~92K across 2 bots -**Wave 2 commit:** d1b0274 (+324 lines, -573 lines) - -## Surprise Test Results - -| Metric | Count | -|--------|-------| -| Stated goals | 8 | -| Total fixes/improvements | 21 | -| Production-critical (would have failed) | 4 | -| Bot factual errors caught | 1 | - -### Critical surprises: -1. HCT main.rs was a broken skeleton — no compilation possible (pre-existing) -2. Observatory had no NVMe weather category — sentinel would emit into void -3. TOPOLOGY.md missing 25+ components — any onboarding/audit would fail -4. Duplicate observatory at `system-tools/monitoring/observatory/` - -### Bot accuracy issue: -Bot 3 claimed 9 contract schemas. Bot 5 verified 8. Cross-verification -prevented false documentation. - -## What Worked -- Ring 2 ceiling prevented cross-repo modification -- "Note don't action" prevented scope creep into PanLL, BundleIngestion -- Resource guardrails prevented parallel Rust builds -- Wave structure provided natural commit checkpoints - -## What Didn't Work -- No priority ordering — bots treated docs and compilation equally -- Bot accuracy degraded at edges (schema miscount) -- No natural stopping condition — would have launched Wave 3 if not stopped -- Convergence bias pulled toward polishing docs over finding structural issues - -## Methodology Improvements Identified -→ These became v3 refinements: -- Weighted priority (MUST 3x > SHOULD 2x > COULD 1x) -- MUST-first pass before meandering -- Wave cap at 2 default -- Cross-verification of bot claims -- Convergence budget (70/20/10) -- Meander debt list as committed artifact diff --git a/field-reports/2026-03-23-multi-session-synthesis.adoc b/field-reports/2026-03-23-multi-session-synthesis.adoc new file mode 100644 index 0000000..ee8e789 --- /dev/null +++ b/field-reports/2026-03-23-multi-session-synthesis.adoc @@ -0,0 +1,82 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Field Report: Multi-Session Synthesis + +== Date: 2026-03-23 + +== Sessions: Ambientops, Stapeln x2, OPSM, ECHIDNA + +== Purpose: Cross-session pattern analysis informing Productive Meandering v3 + +=== Overview + +Five parallel Claude sessions on 2026-03-23 all independently assessed +Productive Meandering and identified overlapping failure modes. This +synthesis produced v3 of the methodology. + +=== Common Findings Across All Sessions + +==== 1. Cherry-Picking Bias (found by: ECHIDNA, Stapeln, Ambientops) + +Agents gravitate toward satisfying, completable work and avoid hard, +tedious work. The ECHIDNA agent wrote 35 easy examples while ignoring 98 +parser unwraps. The Stapeln agent polished the web UI (7/10 maturity) +while ignoring the TUI (2/10 maturity, has a MUST). + +==== 2. No Systematic MUST Coverage (found by: all 5 sessions) + +The random walk visits ~30% of a codebase. The other 70% goes untouched. +Nothing forces the meander to distinguish "`nice to complete`" from +"`blocks other work.`" Gate structures, deadlines, and priority lists +exist but the meander ignores them. + +==== 3. Scope Monotonic Expansion (found by: OPSM, Stapeln-2) + +Each discovery opens more questions than it closes. The OPSM session +went from "`fix asdf notice`" (5 min) to "`design entire runtime +extension`" (rest of session, zero code). The scope expanded at every +step, each step was logical, none was wrong, but the destination kept +moving. + +==== 4. Convergence Toward Infrastructure (found by: Stapeln-2, ECHIDNA) + +Meandering’s convergent bias pulls toward developer-facing cleanup +(routers, imports, deprecation fixes) rather than user-facing goals. The +task "`develop the UI`" produced 2 commits of wiring and 0 commits of +actual UI features. Users see the same interface. + +==== 5. Design Without Verification (found by: OPSM) + +The OPSM session designed an entire runtime extension against README +claims (101 registry adapters, 547 tests, SLSA L3) without reading the +actual code. If those claims were scaffolded, the design was built on +sand. + +=== Unique Findings Per Session + +[cols=",",options="header",] +|=== +|Session |Unique Finding +|Ambientops |Bot accuracy degrades at edges (schema miscount) +|Stapeln-1 |"`While I’m here`" quick features create tech debt +|Stapeln-2 |Linear `+build→fix→build+` is sometimes faster +|OPSM |Agent must actively gate ring transitions +|ECHIDNA |Regressions found but not fixed (Lean4 sorry 20→46) +|=== + +=== Methodology Changes Resulting + +All findings were folded into Productive Meandering v3: - Weighted +priority with maturity bias counter - Ring transition discipline (active +gating) - Verify before designing - Spike requirement (must ship code) - +Hybrid audit-then-focus mode (new default) - Regression handling - +Self-termination signals - Difficulty-impact matrix - Systematic +coverage tracking - When NOT to meander + +=== Meta-Observation + +The most valuable output of this synthesis is not any single fix but the +*pattern*: running the same methodology across multiple sessions +simultaneously produces convergent failure reports. The failures are +structural to the methodology, not incidental to any session. This gives +high confidence that the v3 fixes address real problems. diff --git a/field-reports/2026-03-23-multi-session-synthesis.md b/field-reports/2026-03-23-multi-session-synthesis.md deleted file mode 100644 index 5c384c2..0000000 --- a/field-reports/2026-03-23-multi-session-synthesis.md +++ /dev/null @@ -1,75 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Field Report: Multi-Session Synthesis -# Date: 2026-03-23 -# Sessions: Ambientops, Stapeln x2, OPSM, ECHIDNA -# Purpose: Cross-session pattern analysis informing Productive Meandering v3 - -## Overview - -Five parallel Claude sessions on 2026-03-23 all independently assessed -Productive Meandering and identified overlapping failure modes. This -synthesis produced v3 of the methodology. - -## Common Findings Across All Sessions - -### 1. Cherry-Picking Bias (found by: ECHIDNA, Stapeln, Ambientops) -Agents gravitate toward satisfying, completable work and avoid hard, -tedious work. The ECHIDNA agent wrote 35 easy examples while ignoring -98 parser unwraps. The Stapeln agent polished the web UI (7/10 maturity) -while ignoring the TUI (2/10 maturity, has a MUST). - -### 2. No Systematic MUST Coverage (found by: all 5 sessions) -The random walk visits ~30% of a codebase. The other 70% goes untouched. -Nothing forces the meander to distinguish "nice to complete" from -"blocks other work." Gate structures, deadlines, and priority lists -exist but the meander ignores them. - -### 3. Scope Monotonic Expansion (found by: OPSM, Stapeln-2) -Each discovery opens more questions than it closes. The OPSM session -went from "fix asdf notice" (5 min) to "design entire runtime extension" -(rest of session, zero code). The scope expanded at every step, each -step was logical, none was wrong, but the destination kept moving. - -### 4. Convergence Toward Infrastructure (found by: Stapeln-2, ECHIDNA) -Meandering's convergent bias pulls toward developer-facing cleanup -(routers, imports, deprecation fixes) rather than user-facing goals. -The task "develop the UI" produced 2 commits of wiring and 0 commits -of actual UI features. Users see the same interface. - -### 5. Design Without Verification (found by: OPSM) -The OPSM session designed an entire runtime extension against README -claims (101 registry adapters, 547 tests, SLSA L3) without reading -the actual code. If those claims were scaffolded, the design was built -on sand. - -## Unique Findings Per Session - -| Session | Unique Finding | -|---------|---------------| -| Ambientops | Bot accuracy degrades at edges (schema miscount) | -| Stapeln-1 | "While I'm here" quick features create tech debt | -| Stapeln-2 | Linear `build→fix→build` is sometimes faster | -| OPSM | Agent must actively gate ring transitions | -| ECHIDNA | Regressions found but not fixed (Lean4 sorry 20→46) | - -## Methodology Changes Resulting - -All findings were folded into Productive Meandering v3: -- Weighted priority with maturity bias counter -- Ring transition discipline (active gating) -- Verify before designing -- Spike requirement (must ship code) -- Hybrid audit-then-focus mode (new default) -- Regression handling -- Self-termination signals -- Difficulty-impact matrix -- Systematic coverage tracking -- When NOT to meander - -## Meta-Observation - -The most valuable output of this synthesis is not any single fix but -the **pattern**: running the same methodology across multiple sessions -simultaneously produces convergent failure reports. The failures are -structural to the methodology, not incidental to any session. This -gives high confidence that the v3 fixes address real problems. diff --git a/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.adoc b/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.adoc new file mode 100644 index 0000000..7625e22 --- /dev/null +++ b/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.adoc @@ -0,0 +1,66 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Field Report: TSDM + Meander Hybrid Validation (Stapeln) + +== Date: 2026-03-23 + +== Methodology: Hybrid TSDM-Meander (first full cycle) + +=== Result: VALIDATED + +The hybrid approach — TSDM navigator producing priorities, meander +executing them — gave both systematic coverage AND discovery. + +=== What Happened + +==== Pass 1 (TSDM agent) + +* Read 9 project documents +* Produced 18-item prioritised queue +* *Critical finding:* Both previous meander sessions had ZERO overlap +with the project’s own documented MUSTs. The meander never read +STATUS.md or ROADMAP.adoc. + +==== Pass 2 (Meander on TSDM top-3) + +* Implemented MUSTs 3, 4, 5 (undo/redo, auto-save, dark mode) +* Meander naturally caught: +** Dark mode needing HTML class sync for Tailwind +** alignSelf not in Sx.make +** Auto-save needing a MarkClean dispatch path +* These are things a linear implementation might have missed + +=== Three Commits + +[width="99%",cols="39%,33%,28%",options="header",] +|=== +|Commit |Lines |What +|712c945 (session 1) |+6,124 / -252 |Pipeline wiring, build fixes, +Tailwind + +|3340e79 (session 2a) |+147 / -358 |Real canvas, URL routing, import fix + +|43ff8e8 (session 2b) |+743 / -140 |Undo/redo, auto-save, dark mode +(TSDM MUSTs) +|=== + +=== Key Insight + +____ +The TSDM agent found what the project needs. The meander found what the +code needs. Together they covered both. +____ + +Without TSDM: meander polishes infrastructure but misses documented +MUSTs. Without meander: TSDM implements features but misses code-level +surprises. Together: documented priorities + code-level discovery = +complete coverage. + +=== Remaining TSDM Queue + +[arabic] +. MUST-1: Wire SecurityInspector + GapAnalysis to live validation API +. MUST-2: Build AttackSurfaceAnalyzer.res (entire new panel) +. MUST-6: Conversational errors with [Fix It] buttons +. SHOULD-7: Simulation dry-run summary +. SHOULD-11: Update TOPOLOGY.md and STATUS.md diff --git a/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.md b/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.md deleted file mode 100644 index 5038f83..0000000 --- a/field-reports/2026-03-23-stapeln-tsdm-hybrid-validation.md +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Field Report: TSDM + Meander Hybrid Validation (Stapeln) -# Date: 2026-03-23 -# Methodology: Hybrid TSDM-Meander (first full cycle) - -## Result: VALIDATED - -The hybrid approach — TSDM navigator producing priorities, meander -executing them — gave both systematic coverage AND discovery. - -## What Happened - -### Pass 1 (TSDM agent) -- Read 9 project documents -- Produced 18-item prioritised queue -- **Critical finding:** Both previous meander sessions had ZERO overlap - with the project's own documented MUSTs. The meander never read - STATUS.md or ROADMAP.adoc. - -### Pass 2 (Meander on TSDM top-3) -- Implemented MUSTs 3, 4, 5 (undo/redo, auto-save, dark mode) -- Meander naturally caught: - - Dark mode needing HTML class sync for Tailwind - - alignSelf not in Sx.make - - Auto-save needing a MarkClean dispatch path -- These are things a linear implementation might have missed - -## Three Commits - -| Commit | Lines | What | -|--------|-------|------| -| 712c945 (session 1) | +6,124 / -252 | Pipeline wiring, build fixes, Tailwind | -| 3340e79 (session 2a) | +147 / -358 | Real canvas, URL routing, import fix | -| 43ff8e8 (session 2b) | +743 / -140 | Undo/redo, auto-save, dark mode (TSDM MUSTs) | - -## Key Insight - -> The TSDM agent found what the project needs. -> The meander found what the code needs. -> Together they covered both. - -Without TSDM: meander polishes infrastructure but misses documented MUSTs. -Without meander: TSDM implements features but misses code-level surprises. -Together: documented priorities + code-level discovery = complete coverage. - -## Remaining TSDM Queue - -1. MUST-1: Wire SecurityInspector + GapAnalysis to live validation API -2. MUST-2: Build AttackSurfaceAnalyzer.res (entire new panel) -3. MUST-6: Conversational errors with [Fix It] buttons -4. SHOULD-7: Simulation dry-run summary -5. SHOULD-11: Update TOPOLOGY.md and STATUS.md diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..e8903c3 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — methodologies (Developer) + +=== What is methodologies? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 9accb11..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — methodologies (Developer) - -## What is methodologies? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..6f698fb --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — methodologies (User) + +=== What is methodologies? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 1887300..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — methodologies (User) - -## What is methodologies? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/methodologies/breadth-first-engineering/README.adoc b/methodologies/breadth-first-engineering/README.adoc new file mode 100644 index 0000000..0a91ff2 --- /dev/null +++ b/methodologies/breadth-first-engineering/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Breadth-First Language Engineering + +=== Summary + +Work across all languages in sweeps by layer rather than completing one +at a time. + +=== Source + +Memory file: `+nextgen-layer0-complete.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/breadth-first-engineering/README.md b/methodologies/breadth-first-engineering/README.md deleted file mode 100644 index d191218..0000000 --- a/methodologies/breadth-first-engineering/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Breadth-First Language Engineering - -## Summary - -Work across all languages in sweeps by layer rather than completing one at a time. - -## Source - -Memory file: `nextgen-layer0-complete.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/contractile-lifecycle/README.adoc b/methodologies/contractile-lifecycle/README.adoc new file mode 100644 index 0000000..49dbf5d --- /dev/null +++ b/methodologies/contractile-lifecycle/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Contractile Lifecycle + +=== Summary + +Five contractile files (Mustfile, Trustfile, Dustfile, Intentfile, K9) +per repo. + +=== Source + +Memory file: `+contractile-cli.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/contractile-lifecycle/README.md b/methodologies/contractile-lifecycle/README.md deleted file mode 100644 index 215d151..0000000 --- a/methodologies/contractile-lifecycle/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Contractile Lifecycle - -## Summary - -Five contractile files (Mustfile, Trustfile, Dustfile, Intentfile, K9) per repo. - -## Source - -Memory file: `contractile-cli.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/cross-project-propagation/README.adoc b/methodologies/cross-project-propagation/README.adoc new file mode 100644 index 0000000..177aed4 --- /dev/null +++ b/methodologies/cross-project-propagation/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Cross-Project Pattern Propagation + +=== Summary + +After building a pattern, document which other projects should adopt it +and how. + +=== Source + +Memory file: `+gsa-cross-pollination.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/cross-project-propagation/README.md b/methodologies/cross-project-propagation/README.md deleted file mode 100644 index 9dfc0c1..0000000 --- a/methodologies/cross-project-propagation/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Cross-Project Pattern Propagation - -## Summary - -After building a pattern, document which other projects should adopt it and how. - -## Source - -Memory file: `gsa-cross-pollination.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/ecosystem-surface-campaign/README.adoc b/methodologies/ecosystem-surface-campaign/README.adoc new file mode 100644 index 0000000..225ca47 --- /dev/null +++ b/methodologies/ecosystem-surface-campaign/README.adoc @@ -0,0 +1,16 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Ecosystem Surface Area Campaign + +=== Summary + +14-touchpoint playbook for maximising exposure of new formats and tools. + +=== Source + +Memory file: `+a2ml-k9-ecosystem-surface.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/ecosystem-surface-campaign/README.md b/methodologies/ecosystem-surface-campaign/README.md deleted file mode 100644 index bb2f76d..0000000 --- a/methodologies/ecosystem-surface-campaign/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Ecosystem Surface Area Campaign - -## Summary - -14-touchpoint playbook for maximising exposure of new formats and tools. - -## Source - -Memory file: `a2ml-k9-ecosystem-surface.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/event-chain-critical-chain/README.adoc b/methodologies/event-chain-critical-chain/README.adoc new file mode 100644 index 0000000..8e7d6a1 --- /dev/null +++ b/methodologies/event-chain-critical-chain/README.adoc @@ -0,0 +1,235 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Event Chain Methodology + Critical Chain for AI Agent Work + +=== Overview + +Event Chain Methodology (ECM) combined with Critical Chain Project +Management (CCPM, from Goldratt’s Theory of Constraints). Applied to +AI-assisted software development, this focuses agent work on *the actual +constraint* — the bottleneck that limits throughput — rather than +whatever happens to be interesting or easy. + +=== Why This Matters for AI Agents + +Every methodology we’ve built (Productive Meandering, TSDM, Parallel +Audit) shares one failure mode: *agents work on non-constraints*. They +polish docs while compilation is broken. They write examples while +parsers panic. They design architectures while the foundation is +unverified. + +The Theory of Constraints says: 1. *Identify* the constraint (what +limits the system’s throughput?) 2. *Exploit* the constraint (maximise +its output with current resources) 3. *Subordinate* everything else to +the constraint (non-constraint work that doesn’t feed the constraint is +waste) 4. *Elevate* the constraint (invest to remove it) 5. *Repeat* — +the constraint has moved, find the new one + +=== Event Chains in AI Development + +An *event* is anything that affects a task’s duration, cost, or outcome. +Events chain — one triggers another: + +.... +Event: "HCT main.rs is a broken skeleton" + → Chain: Can't compile HCT + → Chain: Can't run SARIF tests + → Chain: Can't verify HCT010/HCT011 rules + → Chain: Can't ship new NVMe monitoring + → Chain: Can't detect CC-003 boot loops + → CONSTRAINT: System stability at risk +.... + +The event chain reveals that fixing main.rs isn’t just "`a cleanup +task`" — it’s the *constraint* that blocks the entire NVMe monitoring +pipeline. Without event chain analysis, an agent might classify it as a +SHOULD and work on TOPOLOGY.md instead. + +=== The Constraint-First Agent Protocol + +==== For Single Agents + +Before starting work, identify the critical chain: + +.... +1. Read STATE file → list all tasks +2. Build dependency graph (what blocks what?) +3. Find the LONGEST CHAIN of dependencies → this is the critical chain +4. Find the FIRST UNRESOLVED LINK in that chain → this is the constraint +5. Work on the constraint FIRST +6. After resolving: re-evaluate (the constraint has moved) +.... + +==== For Multi-Agent Systems + +The three-agent architecture (ADR-001) maps naturally: + +[width="100%",cols="22%,30%,48%",options="header",] +|=== +|Agent |ToC Role |Responsibility +|*TSDM* |Identify + Monitor |Builds the dependency graph. Identifies the +critical chain. Spots when the constraint moves. + +|*Converge* |Exploit + Subordinate |Works the constraint directly. +Everything it does must feed the critical chain. Non-constraint work is +deferred. + +|*Diverge* |Elevate |Finds creative solutions to remove the constraint +entirely. Novel approaches, architectural shortcuts, tool-building that +eliminates whole classes of constraints. +|=== + +==== Subordination Rule (CRITICAL) + +*Everything subordinates to the constraint.* This means: + +* If the constraint is "`HCT doesn’t compile`", then ALL agent work must +either (a) fix HCT compilation, or (b) prepare work that’s blocked by +HCT compilation so it’s ready when the constraint clears. +* Work that doesn’t feed the constraint is *not just low priority — it’s +waste.* Updating TOPOLOGY.md while HCT can’t compile is waste. Writing +new Elixir modules that depend on HCT output is waste. +* *Exception:* If non-constraint work is completely independent (doesn’t +feed into or depend on the critical chain), it can proceed in parallel +at lower priority. But verify independence — most things connect. + +==== Buffer Management + +Critical Chain uses *buffers* to absorb uncertainty: + +* *Project buffer:* Time/budget reserved at the end of the critical +chain. For AI agents: reserve 20% of token budget for constraint +resolution. +* *Feeding buffers:* Time/budget at merge points where non-critical work +joins the critical chain. For AI agents: when a parallel bot’s output +feeds into the critical chain, ensure it completes before the constraint +resolution needs it. +* *Resource buffer:* Signal to have the right resource ready. For AI +agents: don’t launch a Rust bot if the constraint is an Elixir +compilation issue. + +=== Event Chain Analysis for Meander Bots + +When a meander bot discovers an issue, it should classify it: + +.... +1. Is this ON the critical chain? + YES → This is or feeds the constraint. Fix immediately. + NO → Continue to question 2. + +2. Does fixing this CREATE a new path that's LONGER than the current + critical chain? + YES → This changes the constraint. Report to TSDM for re-evaluation. + NO → Continue to question 3. + +3. Is this completely independent of the critical chain? + YES → Add to meander debt list. Fix if budget allows. + NO → It feeds the critical chain indirectly. Fix if on the + feeding path, defer if not. +.... + +=== Integration with Hypatia Learning Loop + +The constraint identification feeds directly into Hypatia’s feedback +loop: + +.... +Constraint identified → panic-attack scans affected repos + → PatternAnalyzer classifies the constraint type + → OutcomeTracker records whether constraint resolution succeeded + → LearningScheduler updates confidence for that constraint class + → Next time this constraint type appears, Hypatia knows: + - How hard it typically is to resolve + - Which bot/recipe works best + - Whether it's really a constraint or a red herring +.... + +*Key connection:* Hypatia’s `+Rules.Learning+` module tracks fix +outcomes per issue type. If we tag constraint resolutions distinctly +from non-constraint fixes, Hypatia can learn which types of constraints +the agents handle well and which need human intervention. This is the +feedback loop the user wants. + +==== Proposed Hypatia Tags + +[source,jsonl] +---- +{"type": "constraint_resolution", "chain_depth": 6, "resolved": true, "method": "direct_fix"} +{"type": "constraint_resolution", "chain_depth": 3, "resolved": true, "method": "elevation"} +{"type": "non_constraint_fix", "on_feeding_path": true, "resolved": true} +{"type": "waste_detected", "reason": "worked_off_critical_chain", "tokens_spent": 15000} +---- + +Over time, Hypatia learns: - Average chain depth of real constraints +(short chains = easy, long = hard) - Success rate per resolution method +(direct fix vs elevation vs creative) - Waste ratio (% of tokens spent +off critical chain — lower is better) - Which constraint types recur +(chronic conditions vs one-offs) + +=== Integration with Productive Meandering v3 + +Event Chain + Critical Chain strengthens several v3 mechanisms: + +[width="100%",cols="38%,62%",options="header",] +|=== +|v3 Mechanism |ECM/CCPM Enhancement +|Weighted priority (MUST 3x) |Constraints are always MUSTs. +Non-constraint MUSTs subordinate to constraint MUSTs. + +|Cherry-picking counter |"`Am I working on the constraint?`" replaces +"`Am I avoiding hard work?`" — more precise. + +|Difficulty-impact matrix |Impact = "`on critical chain?`" Hard+High = +constraint. Easy+High = feeding the constraint. + +|TSDM navigator |TSDM agent builds the dependency graph and identifies +the critical chain explicitly. + +|Self-termination |"`Constraint resolved, no new constraint found`" is a +clean stopping condition. + +|Hybrid audit-then-focus |Audit phase identifies the critical chain. +Focus phase works the constraint. +|=== + +=== Example: Ambientops Meander (Re-Evaluated) + +What actually happened (v2): - Wave 1: Built 4 components + 2 SARIF +rules + infra sweep (parallel, no priority) - Wave 2: Fixed HCT main.rs ++ cleanup + +What should have happened (v3 + ECM/CCPM): + +.... +Critical chain analysis: + CC-003 (boot loops) → boot-guardian → HCT010 SARIF rule → HCT compiles + ← CONSTRAINT: HCT doesn't compile (broken main.rs) + +Wave 1 (constraint-first): + Bot 1: Fix HCT main.rs (THE CONSTRAINT) + HCT010/HCT011 + Bot 2: Build boot-guardian (feeds constraint output) + Bot 3: Build nvme-sentinel (independent — can proceed in parallel) + +Wave 1 result: Critical chain UNBLOCKED. HCT compiles. Boot-guardian +can consume SARIF output. NVMe sentinel ready independently. + +Wave 2 (new constraint): + Re-evaluate: what's the constraint NOW? + → shutdown-marshal + service-autopsy + wiring + → Constraint: no cross-component Evidence Envelope flow + Work the new constraint. +.... + +The constraint-first approach would have: - Unblocked HCT compilation in +Wave 1 (not Wave 2) - Built boot-guardian against a compilable HCT +(verified, not assumed) - Produced fewer total files but a more +coherent, tested system + +=== References + +* Goldratt, E.M. (1997). _Critical Chain_. North River Press. +* Virine, L. & Trumper, M. (2013). _ProjectThink_. Gower. +* Event Chain Methodology: +https://en.wikipedia.org/wiki/Event_chain_methodology +* Theory of Constraints: +https://en.wikipedia.org/wiki/Theory_of_constraints diff --git a/methodologies/event-chain-critical-chain/README.md b/methodologies/event-chain-critical-chain/README.md deleted file mode 100644 index f983010..0000000 --- a/methodologies/event-chain-critical-chain/README.md +++ /dev/null @@ -1,205 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Event Chain Methodology + Critical Chain for AI Agent Work - -## Overview - -Event Chain Methodology (ECM) combined with Critical Chain Project Management -(CCPM, from Goldratt's Theory of Constraints). Applied to AI-assisted software -development, this focuses agent work on **the actual constraint** — the -bottleneck that limits throughput — rather than whatever happens to be -interesting or easy. - -## Why This Matters for AI Agents - -Every methodology we've built (Productive Meandering, TSDM, Parallel Audit) -shares one failure mode: **agents work on non-constraints**. They polish -docs while compilation is broken. They write examples while parsers panic. -They design architectures while the foundation is unverified. - -The Theory of Constraints says: -1. **Identify** the constraint (what limits the system's throughput?) -2. **Exploit** the constraint (maximise its output with current resources) -3. **Subordinate** everything else to the constraint (non-constraint work - that doesn't feed the constraint is waste) -4. **Elevate** the constraint (invest to remove it) -5. **Repeat** — the constraint has moved, find the new one - -## Event Chains in AI Development - -An **event** is anything that affects a task's duration, cost, or outcome. -Events chain — one triggers another: - -``` -Event: "HCT main.rs is a broken skeleton" - → Chain: Can't compile HCT - → Chain: Can't run SARIF tests - → Chain: Can't verify HCT010/HCT011 rules - → Chain: Can't ship new NVMe monitoring - → Chain: Can't detect CC-003 boot loops - → CONSTRAINT: System stability at risk -``` - -The event chain reveals that fixing main.rs isn't just "a cleanup task" — -it's the **constraint** that blocks the entire NVMe monitoring pipeline. -Without event chain analysis, an agent might classify it as a SHOULD and -work on TOPOLOGY.md instead. - -## The Constraint-First Agent Protocol - -### For Single Agents - -Before starting work, identify the critical chain: - -``` -1. Read STATE file → list all tasks -2. Build dependency graph (what blocks what?) -3. Find the LONGEST CHAIN of dependencies → this is the critical chain -4. Find the FIRST UNRESOLVED LINK in that chain → this is the constraint -5. Work on the constraint FIRST -6. After resolving: re-evaluate (the constraint has moved) -``` - -### For Multi-Agent Systems - -The three-agent architecture (ADR-001) maps naturally: - -| Agent | ToC Role | Responsibility | -|-------|----------|----------------| -| **TSDM** | Identify + Monitor | Builds the dependency graph. Identifies the critical chain. Spots when the constraint moves. | -| **Converge** | Exploit + Subordinate | Works the constraint directly. Everything it does must feed the critical chain. Non-constraint work is deferred. | -| **Diverge** | Elevate | Finds creative solutions to remove the constraint entirely. Novel approaches, architectural shortcuts, tool-building that eliminates whole classes of constraints. | - -### Subordination Rule (CRITICAL) - -**Everything subordinates to the constraint.** This means: - -- If the constraint is "HCT doesn't compile", then ALL agent work must - either (a) fix HCT compilation, or (b) prepare work that's blocked - by HCT compilation so it's ready when the constraint clears. -- Work that doesn't feed the constraint is **not just low priority — - it's waste.** Updating TOPOLOGY.md while HCT can't compile is waste. - Writing new Elixir modules that depend on HCT output is waste. -- **Exception:** If non-constraint work is completely independent (doesn't - feed into or depend on the critical chain), it can proceed in parallel - at lower priority. But verify independence — most things connect. - -### Buffer Management - -Critical Chain uses **buffers** to absorb uncertainty: - -- **Project buffer:** Time/budget reserved at the end of the critical chain. - For AI agents: reserve 20% of token budget for constraint resolution. -- **Feeding buffers:** Time/budget at merge points where non-critical work - joins the critical chain. For AI agents: when a parallel bot's output - feeds into the critical chain, ensure it completes before the constraint - resolution needs it. -- **Resource buffer:** Signal to have the right resource ready. For AI agents: - don't launch a Rust bot if the constraint is an Elixir compilation issue. - -## Event Chain Analysis for Meander Bots - -When a meander bot discovers an issue, it should classify it: - -``` -1. Is this ON the critical chain? - YES → This is or feeds the constraint. Fix immediately. - NO → Continue to question 2. - -2. Does fixing this CREATE a new path that's LONGER than the current - critical chain? - YES → This changes the constraint. Report to TSDM for re-evaluation. - NO → Continue to question 3. - -3. Is this completely independent of the critical chain? - YES → Add to meander debt list. Fix if budget allows. - NO → It feeds the critical chain indirectly. Fix if on the - feeding path, defer if not. -``` - -## Integration with Hypatia Learning Loop - -The constraint identification feeds directly into Hypatia's feedback loop: - -``` -Constraint identified → panic-attack scans affected repos - → PatternAnalyzer classifies the constraint type - → OutcomeTracker records whether constraint resolution succeeded - → LearningScheduler updates confidence for that constraint class - → Next time this constraint type appears, Hypatia knows: - - How hard it typically is to resolve - - Which bot/recipe works best - - Whether it's really a constraint or a red herring -``` - -**Key connection:** Hypatia's `Rules.Learning` module tracks fix outcomes -per issue type. If we tag constraint resolutions distinctly from non-constraint -fixes, Hypatia can learn which types of constraints the agents handle well -and which need human intervention. This is the feedback loop the user wants. - -### Proposed Hypatia Tags - -```jsonl -{"type": "constraint_resolution", "chain_depth": 6, "resolved": true, "method": "direct_fix"} -{"type": "constraint_resolution", "chain_depth": 3, "resolved": true, "method": "elevation"} -{"type": "non_constraint_fix", "on_feeding_path": true, "resolved": true} -{"type": "waste_detected", "reason": "worked_off_critical_chain", "tokens_spent": 15000} -``` - -Over time, Hypatia learns: -- Average chain depth of real constraints (short chains = easy, long = hard) -- Success rate per resolution method (direct fix vs elevation vs creative) -- Waste ratio (% of tokens spent off critical chain — lower is better) -- Which constraint types recur (chronic conditions vs one-offs) - -## Integration with Productive Meandering v3 - -Event Chain + Critical Chain strengthens several v3 mechanisms: - -| v3 Mechanism | ECM/CCPM Enhancement | -|-------------|----------------------| -| Weighted priority (MUST 3x) | Constraints are always MUSTs. Non-constraint MUSTs subordinate to constraint MUSTs. | -| Cherry-picking counter | "Am I working on the constraint?" replaces "Am I avoiding hard work?" — more precise. | -| Difficulty-impact matrix | Impact = "on critical chain?" Hard+High = constraint. Easy+High = feeding the constraint. | -| TSDM navigator | TSDM agent builds the dependency graph and identifies the critical chain explicitly. | -| Self-termination | "Constraint resolved, no new constraint found" is a clean stopping condition. | -| Hybrid audit-then-focus | Audit phase identifies the critical chain. Focus phase works the constraint. | - -## Example: Ambientops Meander (Re-Evaluated) - -What actually happened (v2): -- Wave 1: Built 4 components + 2 SARIF rules + infra sweep (parallel, no priority) -- Wave 2: Fixed HCT main.rs + cleanup - -What should have happened (v3 + ECM/CCPM): - -``` -Critical chain analysis: - CC-003 (boot loops) → boot-guardian → HCT010 SARIF rule → HCT compiles - ← CONSTRAINT: HCT doesn't compile (broken main.rs) - -Wave 1 (constraint-first): - Bot 1: Fix HCT main.rs (THE CONSTRAINT) + HCT010/HCT011 - Bot 2: Build boot-guardian (feeds constraint output) - Bot 3: Build nvme-sentinel (independent — can proceed in parallel) - -Wave 1 result: Critical chain UNBLOCKED. HCT compiles. Boot-guardian -can consume SARIF output. NVMe sentinel ready independently. - -Wave 2 (new constraint): - Re-evaluate: what's the constraint NOW? - → shutdown-marshal + service-autopsy + wiring - → Constraint: no cross-component Evidence Envelope flow - Work the new constraint. -``` - -The constraint-first approach would have: -- Unblocked HCT compilation in Wave 1 (not Wave 2) -- Built boot-guardian against a compilable HCT (verified, not assumed) -- Produced fewer total files but a more coherent, tested system - -## References - -- Goldratt, E.M. (1997). *Critical Chain*. North River Press. -- Virine, L. & Trumper, M. (2013). *ProjectThink*. Gower. -- Event Chain Methodology: https://en.wikipedia.org/wiki/Event_chain_methodology -- Theory of Constraints: https://en.wikipedia.org/wiki/Theory_of_constraints diff --git a/methodologies/explainme-standard/README.adoc b/methodologies/explainme-standard/README.adoc new file mode 100644 index 0000000..4cd7e9b --- /dev/null +++ b/methodologies/explainme-standard/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== EXPLAINME.adoc Standard + +=== Summary + +Show-me-the-receipts file backing README claims with code paths and +honest caveats. + +=== Source + +Memory file: `+explainme-standard.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/explainme-standard/README.md b/methodologies/explainme-standard/README.md deleted file mode 100644 index 28ba063..0000000 --- a/methodologies/explainme-standard/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# EXPLAINME.adoc Standard - -## Summary - -Show-me-the-receipts file backing README claims with code paths and honest caveats. - -## Source - -Memory file: `explainme-standard.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/external-link-crosscheck/README.adoc b/methodologies/external-link-crosscheck/README.adoc new file mode 100644 index 0000000..66eff1c --- /dev/null +++ b/methodologies/external-link-crosscheck/README.adoc @@ -0,0 +1,16 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== External Link Cross-Check + +=== Summary + +Check open PRs and submissions before archiving or reorganising repos. + +=== Source + +Memory file: `+feedback_crosscheck_external_links.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/external-link-crosscheck/README.md b/methodologies/external-link-crosscheck/README.md deleted file mode 100644 index 2fa5530..0000000 --- a/methodologies/external-link-crosscheck/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# External Link Cross-Check - -## Summary - -Check open PRs and submissions before archiving or reorganising repos. - -## Source - -Memory file: `feedback_crosscheck_external_links.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/floor-raise-campaign/README.adoc b/methodologies/floor-raise-campaign/README.adoc new file mode 100644 index 0000000..18bf23e --- /dev/null +++ b/methodologies/floor-raise-campaign/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Floor Raise Campaign + +=== Summary + +Audit all repos for missing standards, generate dispatch manifests, run +idempotent fixes. + +=== Source + +Memory file: `+floor-raise-campaign.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/floor-raise-campaign/README.md b/methodologies/floor-raise-campaign/README.md deleted file mode 100644 index 62c7166..0000000 --- a/methodologies/floor-raise-campaign/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Floor Raise Campaign - -## Summary - -Audit all repos for missing standards, generate dispatch manifests, run idempotent fixes. - -## Source - -Memory file: `floor-raise-campaign.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/git-cycle/README.adoc b/methodologies/git-cycle/README.adoc new file mode 100644 index 0000000..2058866 --- /dev/null +++ b/methodologies/git-cycle/README.adoc @@ -0,0 +1,16 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Full Git Cycle + +=== Summary + +Commit + .gitignore + push + mirror in one pass. Never ask at each step. + +=== Source + +Memory file: `+feedback_git_workflow.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/git-cycle/README.md b/methodologies/git-cycle/README.md deleted file mode 100644 index 3a025df..0000000 --- a/methodologies/git-cycle/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Full Git Cycle - -## Summary - -Commit + .gitignore + push + mirror in one pass. Never ask at each step. - -## Source - -Memory file: `feedback_git_workflow.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/hypatia-feedback-loop/README.adoc b/methodologies/hypatia-feedback-loop/README.adoc new file mode 100644 index 0000000..91c6b05 --- /dev/null +++ b/methodologies/hypatia-feedback-loop/README.adoc @@ -0,0 +1,127 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Hypatia Feedback Loop — Automated Methodology Learning + +=== Overview + +Hypatia is the neurosymbolic CI/CD intelligence layer for the +hyperpolymath ecosystem. Its built-in learning agent forms a closed +feedback loop that learns from every fix, every failure, and every +constraint resolution across the entire 500+ repo fleet. + +=== The Loop (4 stages) + +.... +1. SCAN panic-attack assail → JSONL outcomes + ↓ +2. DISPATCH PatternAnalyzer → TriangleRouter → FleetDispatcher + (confidence-gated: ≥0.95 auto, 0.85-0.94 PR, <0.85 advisory) + ↓ +3. RECORD OutcomeTracker → Beta-distribution confidence updating + (prior strength 10, floor 0.10, cap 0.99) + ↓ +4. LEARN LearningScheduler polls every 5 minutes + Rules.Learning promotes patterns (≥5 occurrences, ≥75% success, + <30% false-positive → permanent rule) + ↓ + → back to 1 (closed loop) +.... + +=== Key Components + +[width="100%",cols="40%,30%,30%",options="header",] +|=== +|Module |Path |Role +|`+LearningScheduler+` |`+hypatia/lib/learning_scheduler.ex+` |Polls new +outcomes, updates recipe confidence, reports drift + +|`+Rules.Learning+` |`+hypatia/lib/rules/learning.ex+` |Per-issue-type +tracking, recency-weighted confidence, false-positive decay + +|`+OutcomeTracker+` |`+hypatia/lib/outcome_tracker.ex+` |Bayesian +confidence updates from fix results + +|`+Neural Coordinator+` |`+hypatia/lib/neural/coordinator.ex+` |5 neural +networks: Graph of Trust, Mixture of Experts, Liquid State Machine, Echo +State Network, Radial Neural Network +|=== + +=== Connection to Methodology Repo + +This is where methodology learning becomes *automated*: + +==== What Hypatia Can Learn From Methodologies + +[arabic] +. *Constraint resolution outcomes* — when Event Chain + Critical Chain +identifies a constraint and an agent resolves it, Hypatia records: +* Was the constraint correctly identified? (precision) +* Did resolving it unblock the chain? (effectiveness) +* How many tokens were spent? (efficiency) +. *Meander surprise rates* — Hypatia can track the Surprise Test across +sessions: +* Ring 0 only: N fixes (baseline) +* Ring 1+: M additional fixes (meander value) +* Critical surprises: K (production failures prevented) +* Over time: is the meander finding fewer surprises? (diminishing +returns) +. *Cherry-picking detection* — Hypatia’s pattern analyzer can flag when +agents consistently choose Easy+Low work over Hard+High: +* Recipe: "`agent chose COULD over MUST`" +* Confidence: how often does this lead to unresolved MUSTs at session +end? +* Promotion: if pattern is reliable, auto-flag in TSDM navigator +. *Methodology selection* — which methodology works best for which type +of project? +* Convergent meander: best for infrastructure repos (Hypatia can learn +this) +* Divergent meander: best for creative repos +* TSDM: best for pre-release audits +* Hybrid: best for most sessions (but is this always true?) + +==== Proposed JSONL Schema for Methodology Outcomes + +[source,jsonl] +---- +{"session": "2026-03-23", "repo": "ambientops", "methodology": "productive-meandering-v3", + "mode": "convergent", "waves": 2, "bots": 5, "tokens": 296000, + "ring0_fixes": 8, "ring1plus_fixes": 13, "critical_surprises": 4, + "bot_errors": 1, "constraint_resolved": true, "constraint_type": "compilation_failure", + "waste_ratio": 0.12, "coverage": 0.30} + +{"session": "2026-03-23", "repo": "stapeln", "methodology": "hybrid-tsdm-meander", + "mode": "hybrid", "waves": 2, "bots": 3, "tokens": 180000, + "tsdm_queue_items": 18, "tsdm_musts_found_by_meander": 0, + "tsdm_musts_in_project_docs": 5, "musts_completed": 3, + "constraint_resolved": true, "constraint_type": "missing_features"} +---- + +==== The Feedback Goal + +Over time, Hypatia should be able to answer: - "`Given this repo type, +which methodology maximises fixes per token?`" - "`Given this constraint +type, which agent role resolves it fastest?`" - "`Is the meander still +finding critical surprises, or should we switch to TSDM?`" - "`Which +agents cherry-pick most? What prompt changes reduce it?`" + +This turns methodology selection from human intuition into data-driven +decision-making — while keeping human override for creative/novel +situations. + +=== Current Status + +* Hypatia learning loop: *Built* (Elixir GenServers, neural coordinator) +* Scanner binary: *Gap* (hypatia-cli.sh / hypatia-v2 escript may not be +runnable) +* Methodology outcome JSONL: *Proposed* (schema above, not yet +implemented) +* Cross-methodology learning: *Not started* (needs the JSONL pipeline) + +=== Next Steps + +[arabic] +. Verify Hypatia scanner binary exists and runs +. Implement methodology outcome JSONL writer (in LearningScheduler) +. Add constraint resolution tags to OutcomeTracker +. Train neural coordinator on methodology outcome data +. Build PanLL panel for methodology effectiveness dashboard diff --git a/methodologies/hypatia-feedback-loop/README.md b/methodologies/hypatia-feedback-loop/README.md deleted file mode 100644 index 1328617..0000000 --- a/methodologies/hypatia-feedback-loop/README.md +++ /dev/null @@ -1,111 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Hypatia Feedback Loop — Automated Methodology Learning - -## Overview - -Hypatia is the neurosymbolic CI/CD intelligence layer for the hyperpolymath -ecosystem. Its built-in learning agent forms a closed feedback loop that -learns from every fix, every failure, and every constraint resolution across -the entire 500+ repo fleet. - -## The Loop (4 stages) - -``` -1. SCAN panic-attack assail → JSONL outcomes - ↓ -2. DISPATCH PatternAnalyzer → TriangleRouter → FleetDispatcher - (confidence-gated: ≥0.95 auto, 0.85-0.94 PR, <0.85 advisory) - ↓ -3. RECORD OutcomeTracker → Beta-distribution confidence updating - (prior strength 10, floor 0.10, cap 0.99) - ↓ -4. LEARN LearningScheduler polls every 5 minutes - Rules.Learning promotes patterns (≥5 occurrences, ≥75% success, - <30% false-positive → permanent rule) - ↓ - → back to 1 (closed loop) -``` - -## Key Components - -| Module | Path | Role | -|--------|------|------| -| `LearningScheduler` | `hypatia/lib/learning_scheduler.ex` | Polls new outcomes, updates recipe confidence, reports drift | -| `Rules.Learning` | `hypatia/lib/rules/learning.ex` | Per-issue-type tracking, recency-weighted confidence, false-positive decay | -| `OutcomeTracker` | `hypatia/lib/outcome_tracker.ex` | Bayesian confidence updates from fix results | -| `Neural Coordinator` | `hypatia/lib/neural/coordinator.ex` | 5 neural networks: Graph of Trust, Mixture of Experts, Liquid State Machine, Echo State Network, Radial Neural Network | - -## Connection to Methodology Repo - -This is where methodology learning becomes **automated**: - -### What Hypatia Can Learn From Methodologies - -1. **Constraint resolution outcomes** — when Event Chain + Critical Chain - identifies a constraint and an agent resolves it, Hypatia records: - - Was the constraint correctly identified? (precision) - - Did resolving it unblock the chain? (effectiveness) - - How many tokens were spent? (efficiency) - -2. **Meander surprise rates** — Hypatia can track the Surprise Test across - sessions: - - Ring 0 only: N fixes (baseline) - - Ring 1+: M additional fixes (meander value) - - Critical surprises: K (production failures prevented) - - Over time: is the meander finding fewer surprises? (diminishing returns) - -3. **Cherry-picking detection** — Hypatia's pattern analyzer can flag when - agents consistently choose Easy+Low work over Hard+High: - - Recipe: "agent chose COULD over MUST" - - Confidence: how often does this lead to unresolved MUSTs at session end? - - Promotion: if pattern is reliable, auto-flag in TSDM navigator - -4. **Methodology selection** — which methodology works best for which type - of project? - - Convergent meander: best for infrastructure repos (Hypatia can learn this) - - Divergent meander: best for creative repos - - TSDM: best for pre-release audits - - Hybrid: best for most sessions (but is this always true?) - -### Proposed JSONL Schema for Methodology Outcomes - -```jsonl -{"session": "2026-03-23", "repo": "ambientops", "methodology": "productive-meandering-v3", - "mode": "convergent", "waves": 2, "bots": 5, "tokens": 296000, - "ring0_fixes": 8, "ring1plus_fixes": 13, "critical_surprises": 4, - "bot_errors": 1, "constraint_resolved": true, "constraint_type": "compilation_failure", - "waste_ratio": 0.12, "coverage": 0.30} - -{"session": "2026-03-23", "repo": "stapeln", "methodology": "hybrid-tsdm-meander", - "mode": "hybrid", "waves": 2, "bots": 3, "tokens": 180000, - "tsdm_queue_items": 18, "tsdm_musts_found_by_meander": 0, - "tsdm_musts_in_project_docs": 5, "musts_completed": 3, - "constraint_resolved": true, "constraint_type": "missing_features"} -``` - -### The Feedback Goal - -Over time, Hypatia should be able to answer: -- "Given this repo type, which methodology maximises fixes per token?" -- "Given this constraint type, which agent role resolves it fastest?" -- "Is the meander still finding critical surprises, or should we switch - to TSDM?" -- "Which agents cherry-pick most? What prompt changes reduce it?" - -This turns methodology selection from human intuition into data-driven -decision-making — while keeping human override for creative/novel situations. - -## Current Status - -- Hypatia learning loop: **Built** (Elixir GenServers, neural coordinator) -- Scanner binary: **Gap** (hypatia-cli.sh / hypatia-v2 escript may not be runnable) -- Methodology outcome JSONL: **Proposed** (schema above, not yet implemented) -- Cross-methodology learning: **Not started** (needs the JSONL pipeline) - -## Next Steps - -1. Verify Hypatia scanner binary exists and runs -2. Implement methodology outcome JSONL writer (in LearningScheduler) -3. Add constraint resolution tags to OutcomeTracker -4. Train neural coordinator on methodology outcome data -5. Build PanLL panel for methodology effectiveness dashboard diff --git a/methodologies/language-repo-taxonomy/README.adoc b/methodologies/language-repo-taxonomy/README.adoc new file mode 100644 index 0000000..47b31e9 --- /dev/null +++ b/methodologies/language-repo-taxonomy/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Language Repo File Taxonomy + +=== Summary + +14-section naming convention covering spec to deployment for any +language repo. + +=== Source + +Memory file: `+language_repo_standard_names.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/language-repo-taxonomy/README.md b/methodologies/language-repo-taxonomy/README.md deleted file mode 100644 index cbf677e..0000000 --- a/methodologies/language-repo-taxonomy/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Language Repo File Taxonomy - -## Summary - -14-section naming convention covering spec to deployment for any language repo. - -## Source - -Memory file: `language_repo_standard_names.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/multi-agent-coordination/README.adoc b/methodologies/multi-agent-coordination/README.adoc new file mode 100644 index 0000000..dce2a2d --- /dev/null +++ b/methodologies/multi-agent-coordination/README.adoc @@ -0,0 +1,84 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Multi-Agent Coordination Patterns + +=== Status: Design Phase (v0) + +=== Problem + +When running 2+ Claude instances (or mixed LLMs) simultaneously, they: - +Step on each other’s work (editing same files, pushing conflicting +changes) - Don’t know what the other completed (ask user to do +already-done tasks) - Can’t coordinate push/merge/mirror sequences +across repos - Duplicate effort on shared task lists + +=== Core Capabilities Needed + +[arabic] +. *Workspace locking* — "`I’m working on repo X, don’t touch it`" +. *Task list sharing* — shared completion state (if A finishes task 5, B +skips it) +. *Completion monitoring* — watch another instance’s progress, +auto-advance +. *Conflict prevention* — file-level or repo-level advisory locks +. *Cross-instance messaging* — "`I changed the API in X, update your +imports`" +. *Dogfooding awareness* — when work in one area affects another area +being worked on by another instance + +=== Implementation Options + +[width="100%",cols="24%,24%,28%,24%",options="header",] +|=== +|Approach |Complexity |Reliability |Cross-LLM +|Shared lockfile dir (`+~/.claude/coordination/+`) |Low |Medium |Yes +|VeriSimDB instance (task graphs, conflict detection) |Medium |High |Yes +|File-based message queue |Low |Low |Yes +|BoJ cartridge |Medium |High |Claude-only +|=== + +=== Practical Patterns (validated) + +==== Sequential Alternating Passes + +Best for single-repo work with multiple concerns (e.g., TSDM + Meander): + +.... +Pass 1: Agent A reads state → produces priority queue +Pass 2: Agent B works top items, reports discoveries +Pass 3: Agent A re-evaluates, adjusts queue +Pass 4: Agent B works next items +.... + +Avoids file contention entirely. TSDM passes are cheap (~10K tokens), +meander passes are expensive (~50-100K tokens). + +==== Parallel with Exclusive Scoping + +Best for multi-repo or multi-directory work: + +.... +Agent 1: OWNS emergency-room/, hardware-crash-team/ +Agent 2: OWNS observatory/, records/ +Agent 3: OWNS .github/, contracts/, Justfile +.... + +No file contention if scopes don’t overlap. Build mutex still applies +(only one compiler at a time). + +==== The Build Mutex Problem + +Only one compiler can run at a time per workspace: - `+rescript build+` +locks the whole project - `+cargo build+` locks the workspace - +`+mix compile+` locks the project + +Solution: Stagger builds. Agent A builds, reports, then Agent B builds. +Or give each agent a separate workspace (git worktrees). + +=== Observed Failure Modes + +* Deprecation bot edited PipelineDesigner.res while main agent was +modifying the same file → build break +* Two agents both running `+cargo check+` → OOM on 32GB machine +* Agent A pushed a commit, Agent B’s working tree was now behind → merge +conflict diff --git a/methodologies/multi-agent-coordination/README.md b/methodologies/multi-agent-coordination/README.md deleted file mode 100644 index 45ffb95..0000000 --- a/methodologies/multi-agent-coordination/README.md +++ /dev/null @@ -1,70 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Multi-Agent Coordination Patterns - -## Status: Design Phase (v0) - -## Problem - -When running 2+ Claude instances (or mixed LLMs) simultaneously, they: -- Step on each other's work (editing same files, pushing conflicting changes) -- Don't know what the other completed (ask user to do already-done tasks) -- Can't coordinate push/merge/mirror sequences across repos -- Duplicate effort on shared task lists - -## Core Capabilities Needed - -1. **Workspace locking** — "I'm working on repo X, don't touch it" -2. **Task list sharing** — shared completion state (if A finishes task 5, B skips it) -3. **Completion monitoring** — watch another instance's progress, auto-advance -4. **Conflict prevention** — file-level or repo-level advisory locks -5. **Cross-instance messaging** — "I changed the API in X, update your imports" -6. **Dogfooding awareness** — when work in one area affects another area being - worked on by another instance - -## Implementation Options - -| Approach | Complexity | Reliability | Cross-LLM | -|----------|-----------|-------------|-----------| -| Shared lockfile dir (`~/.claude/coordination/`) | Low | Medium | Yes | -| VeriSimDB instance (task graphs, conflict detection) | Medium | High | Yes | -| File-based message queue | Low | Low | Yes | -| BoJ cartridge | Medium | High | Claude-only | - -## Practical Patterns (validated) - -### Sequential Alternating Passes -Best for single-repo work with multiple concerns (e.g., TSDM + Meander): -``` -Pass 1: Agent A reads state → produces priority queue -Pass 2: Agent B works top items, reports discoveries -Pass 3: Agent A re-evaluates, adjusts queue -Pass 4: Agent B works next items -``` -Avoids file contention entirely. TSDM passes are cheap (~10K tokens), -meander passes are expensive (~50-100K tokens). - -### Parallel with Exclusive Scoping -Best for multi-repo or multi-directory work: -``` -Agent 1: OWNS emergency-room/, hardware-crash-team/ -Agent 2: OWNS observatory/, records/ -Agent 3: OWNS .github/, contracts/, Justfile -``` -No file contention if scopes don't overlap. Build mutex still applies -(only one compiler at a time). - -### The Build Mutex Problem -Only one compiler can run at a time per workspace: -- `rescript build` locks the whole project -- `cargo build` locks the workspace -- `mix compile` locks the project - -Solution: Stagger builds. Agent A builds, reports, then Agent B builds. -Or give each agent a separate workspace (git worktrees). - -## Observed Failure Modes - -- Deprecation bot edited PipelineDesigner.res while main agent was - modifying the same file → build break -- Two agents both running `cargo check` → OOM on 32GB machine -- Agent A pushed a commit, Agent B's working tree was now behind → merge conflict diff --git a/methodologies/panel-harness-autowiring/README.adoc b/methodologies/panel-harness-autowiring/README.adoc new file mode 100644 index 0000000..c5c74d7 --- /dev/null +++ b/methodologies/panel-harness-autowiring/README.adoc @@ -0,0 +1,16 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== PanelHarness Autowiring Protocol + +=== Summary + +panels/manifest.json schema for PanLL auto-discovery and health probing. + +=== Source + +Memory file: `+panelharness-protocol.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/panel-harness-autowiring/README.md b/methodologies/panel-harness-autowiring/README.md deleted file mode 100644 index 5a0b1a4..0000000 --- a/methodologies/panel-harness-autowiring/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# PanelHarness Autowiring Protocol - -## Summary - -panels/manifest.json schema for PanLL auto-discovery and health probing. - -## Source - -Memory file: `panelharness-protocol.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/parallel-audit/README.adoc b/methodologies/parallel-audit/README.adoc new file mode 100644 index 0000000..f5ec858 --- /dev/null +++ b/methodologies/parallel-audit/README.adoc @@ -0,0 +1,60 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Parallel Audit Methodology v2 + +=== Overview + +Send multiple agents to audit the same repo from different angles with +exclusive scoping. Each agent goes deep in their domain (~200 files +total vs ~80 for a single pass). Triple-confirmation on critical +findings. + +=== When to Use + +* Pre-milestone comprehensive audit (NLnet submission, awesome-list PR, +Show HN) +* Any time a repo needs thorough review before external visibility +* Large repos where a single agent can’t cover everything in one pass + +=== Prompt Template (v2) + +[arabic] +. *Exclusive scoping* — "`You OWN: [dirs]. You SKIP: [dirs].`" +Eliminates overlap completely. +. *Standardized output format* — Force: +`+[SEVERITY] file:line — description / Evidence / Impact / Fix+` +. *Severity definitions* — Define MUST/SHOULD/COULD/STALE precisely +upfront (not left to agent interpretation). +. *"`Read files FRESH`" instruction* — Important when the repo was +modified in-session. +. *Concrete task lists* — "`Count exact unwrap() calls with line +numbers`" beats "`check for issues`". +. *Include negative checks* — "`Are there files NOT included in any +Cargo.toml?`" catches orphans. + +=== What v3 Should Add + +* *Execution testing* — one agent should actually RUN `+just build+`, +`+just test+`, not just verify files exist +* *Temporal marking* — distinguish "`this was like this before our +session`" vs "`we introduced this`" +* *Confidence levels* — "`HIGH: read the file`" vs "`MEDIUM: inferred +from name`" vs "`LOW: couldn’t find`" +* *Cross-agent summary format* — agents end with a machine-parseable +findings list for automatic reconciliation + +=== What Parallel Audits Catch Well + +* License inconsistencies (found by all 3 from different angles — high +confidence) +* Stale metadata (TOPOLOGY.md, STATE.a2ml, arXiv papers vs actual proof +status) +* Orphan files (not in module tree) +* Template variable leaks (`+{{OWNER}}+` in workflow) +* Count accuracy (78 unwraps, not "`~35`") + +=== Validated + +Tested 2026-03-22 on typed-wasm. Three agents covered ~200 files total +with zero overlap. Triple-confirmation on license inconsistencies gave +high confidence in findings. diff --git a/methodologies/parallel-audit/README.md b/methodologies/parallel-audit/README.md deleted file mode 100644 index b09a5ca..0000000 --- a/methodologies/parallel-audit/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Parallel Audit Methodology v2 - -## Overview - -Send multiple agents to audit the same repo from different angles with -exclusive scoping. Each agent goes deep in their domain (~200 files total -vs ~80 for a single pass). Triple-confirmation on critical findings. - -## When to Use - -- Pre-milestone comprehensive audit (NLnet submission, awesome-list PR, Show HN) -- Any time a repo needs thorough review before external visibility -- Large repos where a single agent can't cover everything in one pass - -## Prompt Template (v2) - -1. **Exclusive scoping** — "You OWN: [dirs]. You SKIP: [dirs]." - Eliminates overlap completely. -2. **Standardized output format** — Force: - `[SEVERITY] file:line — description / Evidence / Impact / Fix` -3. **Severity definitions** — Define MUST/SHOULD/COULD/STALE precisely - upfront (not left to agent interpretation). -4. **"Read files FRESH" instruction** — Important when the repo was - modified in-session. -5. **Concrete task lists** — "Count exact unwrap() calls with line - numbers" beats "check for issues". -6. **Include negative checks** — "Are there files NOT included in any - Cargo.toml?" catches orphans. - -## What v3 Should Add - -- **Execution testing** — one agent should actually RUN `just build`, - `just test`, not just verify files exist -- **Temporal marking** — distinguish "this was like this before our - session" vs "we introduced this" -- **Confidence levels** — "HIGH: read the file" vs "MEDIUM: inferred - from name" vs "LOW: couldn't find" -- **Cross-agent summary format** — agents end with a machine-parseable - findings list for automatic reconciliation - -## What Parallel Audits Catch Well - -- License inconsistencies (found by all 3 from different angles — high confidence) -- Stale metadata (TOPOLOGY.md, STATE.a2ml, arXiv papers vs actual proof status) -- Orphan files (not in module tree) -- Template variable leaks (`{{OWNER}}` in workflow) -- Count accuracy (78 unwraps, not "~35") - -## Validated - -Tested 2026-03-22 on typed-wasm. Three agents covered ~200 files total -with zero overlap. Triple-confirmation on license inconsistencies gave -high confidence in findings. diff --git a/methodologies/pre-commit-gate/README.adoc b/methodologies/pre-commit-gate/README.adoc new file mode 100644 index 0000000..c9ab45f --- /dev/null +++ b/methodologies/pre-commit-gate/README.adoc @@ -0,0 +1,16 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== panic-attack Pre-Commit Gate + +=== Summary + +Always run panic-attack assail before every commit across all repos. + +=== Source + +Memory file: `+feedback_panic_attack_precommit.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/pre-commit-gate/README.md b/methodologies/pre-commit-gate/README.md deleted file mode 100644 index c68396a..0000000 --- a/methodologies/pre-commit-gate/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# panic-attack Pre-Commit Gate - -## Summary - -Always run panic-attack assail before every commit across all repos. - -## Source - -Memory file: `feedback_panic_attack_precommit.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/productive-meandering/README.md b/methodologies/productive-meandering/README.adoc similarity index 71% rename from methodologies/productive-meandering/README.md rename to methodologies/productive-meandering/README.adoc index 7f9523c..8ffe12d 100644 --- a/methodologies/productive-meandering/README.md +++ b/methodologies/productive-meandering/README.adoc @@ -1,12 +1,14 @@ -# Productive Meandering — Task Execution Methodology +== Productive Meandering — Task Execution Methodology -## The Prompt +=== The Prompt -Paste this into your CLAUDE.md, session instructions, or invoke with "meander on [task]": +Paste this into your CLAUDE.md, session instructions, or invoke with +"`meander on [task]`": ---- +''''' -```markdown +[source,markdown] +---- ## Task Execution: Productive Meandering v3 When given a task, do NOT take the shortest path. Instead, take the **maximal @@ -248,19 +250,25 @@ Every meander produces a **debt list** — things found but not fixed. This is NOT a failure. It's the meander's most valuable output after the code itself. Format: -``` -## Meander Debt (ambientops, 2026-03-23) +---- -### Would fix next wave (SHOULD) -- [ ] system-tools/monitoring/observatory/ is a stale duplicate of observatory/ -- [ ] ECOSYSTEM.a2ml and META.a2ml are minimal stubs -- [ ] CLAUDE.md says 9 SARIF rules, should say 11 -- [ ] `needs_sudo` parsed from JSON but discarded — add to PlanStep struct? +=== Meander Debt (ambientops, 2026-03-23) -### Would fix eventually (COULD) -- [ ] Empty stale/ directory can be removed -- [ ] Envelope flag on Scan parsed but not wired -``` +==== Would fix next wave (SHOULD) + +* [ ] system-tools/monitoring/observatory/ is a stale duplicate of +observatory/ +* [ ] ECOSYSTEM.a2ml and META.a2ml are minimal stubs +* [ ] CLAUDE.md says 9 SARIF rules, should say 11 +* [ ] `+needs_sudo+` parsed from JSON but discarded — add to PlanStep +struct? + +==== Would fix eventually (COULD) + +* [ ] Empty stale/ directory can be removed +* [ ] Envelope flag on Scan parsed but not wired + +.... The debt list: - Gets committed to the repo (as `MEANDER-DEBT.md` or appended to STATE) @@ -518,13 +526,13 @@ ask: "Am I avoiding something harder?" The answer is usually yes. ### Systematic Coverage (gated task lists) When meandering through a numbered/gated task list, track coverage: +.... -``` -Phase A coverage: - Audited: Gates 1, 1.5, 3D, 3G, 3N, 3O - Skipped: Gates 2A, 3F, 3H, 3I, 4, 5, Hypatia ops, game servers - MUSTs in skipped sections: [none / list them] -``` +Phase A coverage: Audited: Gates 1, 1.5, 3D, 3G, 3N, 3O Skipped: Gates +2A, 3F, 3H, 3I, 4, 5, Hypatia ops, game servers MUSTs in skipped +sections: [none / list them] + +.... Before starting Phase B, verify no skipped section contains a MUST. At session end, include this coverage report — it forces accountability @@ -603,14 +611,15 @@ For complex projects with multiple components at different maturity levels, a **sequential alternating pass** architecture outperforms both pure TSDM (systematic but misses hidden issues) and pure meandering (discovers but doesn't guarantee coverage). +.... + +Pass 1: TSDM agent reads project state → produces prioritised queue Pass +2: Meander agent works top 3 items from queue (Ring 0-2, no stubbing) +Pass 3: TSDM agent re-evaluates based on meander discoveries Pass 4: +Meander agent works next 3 items … (alternate until done or budget +exhausted) -``` -Pass 1: TSDM agent reads project state → produces prioritised queue -Pass 2: Meander agent works top 3 items from queue (Ring 0-2, no stubbing) -Pass 3: TSDM agent re-evaluates based on meander discoveries -Pass 4: Meander agent works next 3 items -... (alternate until done or budget exhausted) -``` +.... **Why sequential, not parallel:** - File contention: two agents editing the same files cause build breaks @@ -635,24 +644,27 @@ Rings 0-2 around each. It produces code + a discovery report. After the audit phase (hybrid mode's first 20%), you have a list of discovered issues. Don't just pick the highest-weighted — use a difficulty-impact matrix to select what to work on: - -``` - HIGH IMPACT - | - +--------------+--------------+ - | HARD+HIGH | EASY+HIGH | - | Do these | Do these | - | (most | FIRST | - | important) | (quick wins)| - +--------------+--------------+ - | HARD+LOW | EASY+LOW | - | Debt list | Skip or | - | (not worth | debt list | - | the cost) | | - +--------------+--------------+ - | - LOW IMPACT -``` +.... + +.... + HIGH IMPACT + | + +--------------+--------------+ + | HARD+HIGH | EASY+HIGH | + | Do these | Do these | + | (most | FIRST | + | important) | (quick wins)| + +--------------+--------------+ + | HARD+LOW | EASY+LOW | + | Debt list | Skip or | + | (not worth | debt list | + | the cost) | | + +--------------+--------------+ + | + LOW IMPACT +.... + +.... **Selection order:** 1. Easy + High Impact (quick wins that matter) @@ -670,25 +682,30 @@ Meandering gives depth on what you touch but no guarantee of breadth. Track coverage explicitly to prevent blind spots. **At audit start, list all components/modules/gates:** -``` -## Coverage (project-name, date) -- [x] PipelineDesigner (Ring 2, 3 fixes) -- [x] AppRouter (Ring 1, wired) -- [ ] TUI (NOT VISITED — has MUST: doesn't compile) -- [ ] ContainerStack (NOT VISITED) -- [ ] BatchProcessor (NOT VISITED) -... -Coverage: 15/50 modules (30%) -``` +.... + +=== Coverage (project-name, date) + +* [x] PipelineDesigner (Ring 2, 3 fixes) +* [x] AppRouter (Ring 1, wired) +* [ ] TUI (NOT VISITED — has MUST: doesn’t compile) +* [ ] ContainerStack (NOT VISITED) +* [ ] BatchProcessor (NOT VISITED) … Coverage: 15/50 modules (30%) + +.... **At session end, report what was skipped and why:** -``` -## Skipped (with reason) -- TUI: MUST (doesn't compile) — skipped because web UI was more interesting - → THIS IS A BUG IN THE MEANDER. TUI MUST should have been worked first. -- ContainerStack: No known issues — acceptable to skip -- BatchProcessor: COULD (style cleanup) — correctly deferred -``` +.... + +=== Skipped (with reason) + +* TUI: MUST (doesn’t compile) — skipped because web UI was more +interesting → THIS IS A BUG IN THE MEANDER. TUI MUST should have been +worked first. +* ContainerStack: No known issues — acceptable to skip +* BatchProcessor: COULD (style cleanup) — correctly deferred + +.... **The accountability rule:** If the session-end report shows a skipped MUST that was ignored in favour of COULDs, the meander failed to follow @@ -753,212 +770,215 @@ signals ensure the meander stops when it stops being productive. The methodology's value is not in the walking — it's in the **arriving having walked through territory you would otherwise have missed.** If you're walking but not arriving, stop walking. -``` +.... ---- +''''' -## Origin +=== Origin -Developed during the Gossamer migration session (2026-03-22) where a simple -"convert Tauri panels" request produced: -- 17 Gossamer apps (14 converted + 3 native) -- A complete CLI tool (7 commands) -- 46 FFI symbols (was 20) -- 8 Ephapax modules -- Full mobile support (iOS + Android) -- Config schema + JSON Schema + reference docs -- 2 ReScript binding packages (15 modules) -- Panel harness v2 -- Minter template updates -- Cross-project learnings for Burble, IDApTIK, PanLL +Developed during the Gossamer migration session (2026-03-22) where a +simple "`convert Tauri panels`" request produced: - 17 Gossamer apps (14 +converted + 3 native) - A complete CLI tool (7 commands) - 46 FFI +symbols (was 20) - 8 Ephapax modules - Full mobile support (iOS + +Android) - Config schema + JSON Schema + reference docs - 2 ReScript +binding packages (15 modules) - Panel harness v2 - Minter template +updates - Cross-project learnings for Burble, IDApTIK, PanLL All from one request. The meandering was the method. -## Validation: Burble v1.0 Test Run (2026-03-22) +=== Validation: Burble v1.0 Test Run (2026-03-22) -Applied the methodology to "fix 3 Burble release blockers": +Applied the methodology to "`fix 3 Burble release blockers`": -- **Ring 0:** Fixed the 3 blockers (release.yml, OTP rel/, VeriSimDB migrations) -- **Ring 1:** Found 3 more issues in adjacent workflows (placeholder, duplicate SPDX, missing CodeQL language) -- **Ring 2:** Found 4 critical issues (Containerfile paths wrong, port mismatch, health_check function missing, no HTTP health endpoint) -- **Ring 3:** Found 1 broken cross-reference (admin panel.json missing) -- **Total:** 11 fixes from a 3-item task. **4 would have caused production failures.** +* *Ring 0:* Fixed the 3 blockers (release.yml, OTP rel/, VeriSimDB +migrations) +* *Ring 1:* Found 3 more issues in adjacent workflows (placeholder, +duplicate SPDX, missing CodeQL language) +* *Ring 2:* Found 4 critical issues (Containerfile paths wrong, port +mismatch, health_check function missing, no HTTP health endpoint) +* *Ring 3:* Found 1 broken cross-reference (admin panel.json missing) +* *Total:* 11 fixes from a 3-item task. *4 would have caused production +failures.* -## Validation: Ambientops Meander (2026-03-23) +=== Validation: Ambientops Meander (2026-03-23) Applied v2 methodology (with v1 prompt, then self-critiqued): -- **Wave 1 (3 bots):** Built 4 new components (boot-guardian, shutdown-marshal, - nvme-sentinel, service-autopsy), 2 SARIF rules, infrastructure sweep. - 12 files created, 11 modified. 4 critical surprises found. -- **Wave 2 (2 bots):** Fixed HCT main.rs skeleton (now compiles), deleted - banned Python, updated STATE.a2ml, added BT sentinel stub. -- **Bot accuracy issue:** Bot 3 claimed 9 schemas, Bot 5 verified 8. - Cross-verification prevented false documentation. -- **Total:** 8 stated goals → 21 fixes. 4 production-critical. - ~296K tokens across 5 bots over 2 waves. +* *Wave 1 (3 bots):* Built 4 new components (boot-guardian, +shutdown-marshal, nvme-sentinel, service-autopsy), 2 SARIF rules, +infrastructure sweep. 12 files created, 11 modified. 4 critical +surprises found. +* *Wave 2 (2 bots):* Fixed HCT main.rs skeleton (now compiles), deleted +banned Python, updated STATE.a2ml, added BT sentinel stub. +* *Bot accuracy issue:* Bot 3 claimed 9 schemas, Bot 5 verified 8. +Cross-verification prevented false documentation. +* *Total:* 8 stated goals → 21 fixes. 4 production-critical. ~296K +tokens across 5 bots over 2 waves. -## Validation: Stapeln UI Meander (2026-03-23) +=== Validation: Stapeln UI Meander (2026-03-23) Applied convergent meandering to Stapeln web UI: -- **Ring 0:** Fixed 3 annotation rendering issues -- **Ring 1:** Found 2 GUI bugs (PanLL sync, search) -- **Ring 2:** Found 7 type mismatches with Rust backend (deserialization would fail) -- **Ring 3 (user-unlocked):** Added 5 features (creation, persistence, shortcuts) -- **Issue:** Ring 3 features used `prompt()` dialogs — quick but ugly, creating - technical debt. The "while I'm here" trap in action. -- **Maturity bias observed:** Web UI (7/10) got polished while TUI (2/10) was ignored. - A MUST on the TUI (doesn't compile) should have outranked SHOULDs on the web UI. +* *Ring 0:* Fixed 3 annotation rendering issues +* *Ring 1:* Found 2 GUI bugs (PanLL sync, search) +* *Ring 2:* Found 7 type mismatches with Rust backend (deserialization +would fail) +* *Ring 3 (user-unlocked):* Added 5 features (creation, persistence, +shortcuts) +* *Issue:* Ring 3 features used `+prompt()+` dialogs — quick but ugly, +creating technical debt. The "`while I’m here`" trap in action. +* *Maturity bias observed:* Web UI (7/10) got polished while TUI (2/10) +was ignored. A MUST on the TUI (doesn’t compile) should have outranked +SHOULDs on the web UI. -## Validation: OPSM Runtime Meander (2026-03-23) +=== Validation: OPSM Runtime Meander (2026-03-23) Applied meandering to an asdf shell notice fix: -- **Ring 0:** Fixed asdf binary (5 minutes) ✓ -- **Ring 1-2:** Should have validated and stopped ✗ -- **Ring 3+:** Designed entire OPSM runtime extension, competitive analysis, - GUI strategy, market research. Zero code produced. Session ended with a - design document and no deliverable. -- **Root cause:** Ring transition discipline was not enforced. Each discovery - naturally led to the next question. The agent never said "this is Ring 3, - I'll note it." The scope expanded monotonically. -- **Lesson:** The prompt's rules were sufficient — they just weren't followed. - Added explicit ring-gating language and the spike requirement to v3. +* *Ring 0:* Fixed asdf binary (5 minutes) ✓ +* *Ring 1-2:* Should have validated and stopped ✗ +* *Ring 3+:* Designed entire OPSM runtime extension, competitive +analysis, GUI strategy, market research. Zero code produced. Session +ended with a design document and no deliverable. +* *Root cause:* Ring transition discipline was not enforced. Each +discovery naturally led to the next question. The agent never said +"`this is Ring 3, I’ll note it.`" The scope expanded monotonically. +* *Lesson:* The prompt’s rules were sufficient — they just weren’t +followed. Added explicit ring-gating language and the spike requirement +to v3. -## Validation: Stapeln Session 2 — Diminishing Returns (2026-03-23) +=== Validation: Stapeln Session 2 — Diminishing Returns (2026-03-23) Applied convergent meandering to Stapeln UI, second session: -- **Ring 0-1:** Found CanvasPlaceholder disconnect, broken Import flow, - missing URL routing. Real issues, well-caught. -- **But:** 50 modules in the project, only ~15 deeply touched. The other - 35 might have equally critical issues the random walk never visits. -- **Goal drift:** Task was "develop the UI" (user-facing). Meander - converged on infrastructure (routers, import flows, deprecation fixes). - Good for developers, not what was asked. -- **The linear alternative:** `rescript build → fix all errors → build again` - would have found the same compilation issues faster and with guaranteed - coverage. Meandering is not always the best tool. -- **Over-convergence:** Added URL routing and popstate listeners to code - that was deliberately simple (manual tab state). Added complexity the - project might not need yet. -- **Lesson:** Session 1 meandering (find hidden failures) was high-value. - Session 2 meandering (clean up infrastructure) was diminishing returns. - Meander should self-terminate when it shifts from "finding critical - issues" to "developer cleanup". Added hybrid mode transition rule. - -## Validation: ECHIDNA Gate Meander (2026-03-23) +* *Ring 0-1:* Found CanvasPlaceholder disconnect, broken Import flow, +missing URL routing. Real issues, well-caught. +* *But:* 50 modules in the project, only ~15 deeply touched. The other +35 might have equally critical issues the random walk never visits. +* *Goal drift:* Task was "`develop the UI`" (user-facing). Meander +converged on infrastructure (routers, import flows, deprecation fixes). +Good for developers, not what was asked. +* *The linear alternative:* +`+rescript build → fix all errors → build again+` would have found the +same compilation issues faster and with guaranteed coverage. Meandering +is not always the best tool. +* *Over-convergence:* Added URL routing and popstate listeners to code +that was deliberately simple (manual tab state). Added complexity the +project might not need yet. +* *Lesson:* Session 1 meandering (find hidden failures) was high-value. +Session 2 meandering (clean up infrastructure) was diminishing returns. +Meander should self-terminate when it shifts from "`finding critical +issues`" to "`developer cleanup`". Added hybrid mode transition rule. + +=== Validation: ECHIDNA Gate Meander (2026-03-23) Applied meandering to ECHIDNA proof gate audit: -- **Breadth:** 6 areas touched (Gate 1 audit, Gate 1.5A, Gate 3G, Gate 3D, - EUPL fix, PR status). Good discovery coverage. -- **Cherry-picking bias:** Bot wrote 35 easy examples and 7 backends while - ignoring 98 parser unwraps (safety) and a Lean4 regression (20→46 sorries). - Easy completions were chosen over hard MUSTs. -- **Widening without deepening:** Created surface area (examples, backends) - without depth (no integration tests, no parser hardening). -- **Lesson:** Added cherry-picking counter-measures, weighted priority - enforcement, and hybrid audit-then-focus mode to v3. - -## Validation: ECHIDNA Gate Meander — Self-Correction (2026-03-23) - -Same session, after user asked "are we at risk of never arriving?": - -- **Honest self-assessment identified 5 failure modes:** cherry-picking bias, - no regression prioritisation, widening without deepening, regression - blindness, efficiency loss from context switching. -- **Root cause:** The prompt had the MUST-first pass and weighted priorities, - but no concrete SELECTION ALGORITHM for Phase B. Agent knew parser unwraps - were important but had no mechanism forcing it to choose them over backends. -- **Fix:** Added Difficulty-Impact Matrix (2x2 grid with "DO FIRST" in - hard+high-impact quadrant), Systematic Coverage tracking (Touched/Skipped - checklist), Session-End Accountability Report (structured, not informal). -- **Key insight:** Invariants prevent scope VIOLATIONS but not scope AVOIDANCE. - The matrix and coverage tracking prevent avoidance by making it visible. -- **Meta-lesson:** The methodology improves fastest when the agent is asked - to critique its own execution mid-session, not just post-session. - -### Methodology Refinements - -**v1 refinements (2026-03-22, Burble session):** -1. Hard ceiling at Ring 2 — Ring 3+ only with explicit user permission -2. "Note, don't action" rule for cross-project insights -3. The Surprise Test — measure value by counting what Ring 1+ found -4. Container validation added to Ring 2 checklist - -**v2 refinements (2026-03-23, Ambientops session):** -5. **MUST-first pass** — read state file, assign P1 items to bots before - meandering. Prevents random walk from ignoring critical path. -6. **Wave cap at 2** — default stop after Wave 2. Each wave should be - smaller than the last. Natural termination condition. -7. **Cross-verification** — scan parallel bot reports for contradictions - before committing. Bots degrade in accuracy at knowledge edges. -8. **Meander debt list** — committed artifact of things found but not - fixed. Prevents "one more wave" loop. Feeds next session. -9. **Convergence budget (70/20/10)** — 70% structural, 20% corrective, - 10% perfective. Prevents over-polishing while structural work waits. - -**v3 refinements (2026-03-23, multi-session field reports):** -10. **Weighted priority (MUST 3x > SHOULD 2x > COULD 1x)** — explicit - weighting forces agents to pick hard important work over easy - satisfying work. Prevents cherry-picking bias. -11. **Maturity bias counter** — agents must check least-mature component - in their zone for ignored MUSTs. Prevents "good code gets better, - broken code stays broken" pattern. -12. **Ring transition discipline** — agents must actively gate ring - transitions, not passively drift. Say "this is Ring 3, noting it" - rather than designing in full. -13. **Scope expansion test** — if each discovery opens more questions - than it closes, you're diverging. Stop and report. -14. **"While I'm here" trap** — quick features that aren't MUSTs go - on the debt list, not into the code. Prevents technical debt from - prompt() dialogs and stub implementations. -15. **Verify before designing** — design against code, not READMEs. - Read the source, check what's real vs scaffolded, run tests. - A 15-minute verification can save hours of fantasy architecture. -16. **Spike requirement** — every session must ship at least one - concrete deliverable (code that compiles, not design documents). - 80% building, 20% exploring. -17. **Hybrid mode (audit-then-focus)** — new default mode. First 20% - of budget meanders broadly (discover). Remaining 80% goes deep - on the 1-2 highest-weighted MUSTs found. Best of both worlds. -18. **Regression handling** — regressions are always MUSTs. Don't - document a regression and move on to easier work. -19. **Cherry-picking counter** — after completing any satisfying task, - ask "What am I avoiding?" If the answer is hard work, go do it. - -**v4 refinements (2026-03-23, ECHIDNA gate meander continued):** -20. **Difficulty-Impact Matrix** — after audit, classify every actionable - item into a 2x2 grid (Hard/Easy vs High/Low Impact). Work top-left - (hard + high impact) FIRST. These are exactly what cherry-picking - avoids. Easy + high impact second. Easy + low impact only if budget - remains. Impact = blocks other work, fixes safety issue, fixes - regression, unblocks user action, or is on a deadline path. -21. **Systematic coverage tracking** — when meandering through a gated - task list, maintain a Touched/Skipped checklist during Phase A. - Before starting Phase B, verify no skipped section contains a MUST. - At session end, report explicitly: "Touched: [list]. Skipped: [list]. - No known MUSTs in skipped sections (verified by reading headers)." - Prevents systematic blind spots from the random walk. -22. **The 30% regression ceiling** — spend at most 30% of Phase B on - regression repair. If regressions exceed that, report as critical - and let user prioritise. Prevents regression triage from consuming - the entire session while new work stalls. -23. **Session-end accountability report** — every session must end with: - (a) what was completed, (b) what was skipped and why, (c) regressions - found, (d) difficulty-impact classification of remaining work, - (e) recommended focus for next session. This forces honest accounting - of what the meander chose NOT to do. - -**v5 refinement (2026-03-23, divergent safety):** -24. **Divergent Invariant Preservation** — "amplify uniqueness" means - deepen, not broaden. Before any divergent work, read the AI manifest - and CLAUDE.md for invariants. Diverge within the riverbanks, not - across them. Test: "Does this deepen the existing strength, or add - a parallel strength?" If parallel → stop. The broadening trap - (adding Lean4 proofs to an Idris2-only repo, adding a Haskell - backend to a Rust compiler) is the divergent equivalent of - convergent's over-polishing — it feels productive but violates - the project's architectural identity. +* *Breadth:* 6 areas touched (Gate 1 audit, Gate 1.5A, Gate 3G, Gate 3D, +EUPL fix, PR status). Good discovery coverage. +* *Cherry-picking bias:* Bot wrote 35 easy examples and 7 backends while +ignoring 98 parser unwraps (safety) and a Lean4 regression (20→46 +sorries). Easy completions were chosen over hard MUSTs. +* *Widening without deepening:* Created surface area (examples, +backends) without depth (no integration tests, no parser hardening). +* *Lesson:* Added cherry-picking counter-measures, weighted priority +enforcement, and hybrid audit-then-focus mode to v3. + +=== Validation: ECHIDNA Gate Meander — Self-Correction (2026-03-23) + +Same session, after user asked "`are we at risk of never arriving?`": + +* *Honest self-assessment identified 5 failure modes:* cherry-picking +bias, no regression prioritisation, widening without deepening, +regression blindness, efficiency loss from context switching. +* *Root cause:* The prompt had the MUST-first pass and weighted +priorities, but no concrete SELECTION ALGORITHM for Phase B. Agent knew +parser unwraps were important but had no mechanism forcing it to choose +them over backends. +* *Fix:* Added Difficulty-Impact Matrix (2x2 grid with "`DO FIRST`" in +hard+high-impact quadrant), Systematic Coverage tracking +(Touched/Skipped checklist), Session-End Accountability Report +(structured, not informal). +* *Key insight:* Invariants prevent scope VIOLATIONS but not scope +AVOIDANCE. The matrix and coverage tracking prevent avoidance by making +it visible. +* *Meta-lesson:* The methodology improves fastest when the agent is +asked to critique its own execution mid-session, not just post-session. + +==== Methodology Refinements + +*v1 refinements (2026-03-22, Burble session):* 1. Hard ceiling at Ring 2 +— Ring 3+ only with explicit user permission 2. "`Note, don’t action`" +rule for cross-project insights 3. The Surprise Test — measure value by +counting what Ring 1+ found 4. Container validation added to Ring 2 +checklist + +*v2 refinements (2026-03-23, Ambientops session):* 5. *MUST-first pass* +— read state file, assign P1 items to bots before meandering. Prevents +random walk from ignoring critical path. 6. *Wave cap at 2* — default +stop after Wave 2. Each wave should be smaller than the last. Natural +termination condition. 7. *Cross-verification* — scan parallel bot +reports for contradictions before committing. Bots degrade in accuracy +at knowledge edges. 8. *Meander debt list* — committed artifact of +things found but not fixed. Prevents "`one more wave`" loop. Feeds next +session. 9. *Convergence budget (70/20/10)* — 70% structural, 20% +corrective, 10% perfective. Prevents over-polishing while structural +work waits. + +*v3 refinements (2026-03-23, multi-session field reports):* 10. +*Weighted priority (MUST 3x > SHOULD 2x > COULD 1x)* — explicit +weighting forces agents to pick hard important work over easy satisfying +work. Prevents cherry-picking bias. 11. *Maturity bias counter* — agents +must check least-mature component in their zone for ignored MUSTs. +Prevents "`good code gets better, broken code stays broken`" pattern. +12. *Ring transition discipline* — agents must actively gate ring +transitions, not passively drift. Say "`this is Ring 3, noting it`" +rather than designing in full. 13. *Scope expansion test* — if each +discovery opens more questions than it closes, you’re diverging. Stop +and report. 14. *"`While I’m here`" trap* — quick features that aren’t +MUSTs go on the debt list, not into the code. Prevents technical debt +from prompt() dialogs and stub implementations. 15. *Verify before +designing* — design against code, not READMEs. Read the source, check +what’s real vs scaffolded, run tests. A 15-minute verification can save +hours of fantasy architecture. 16. *Spike requirement* — every session +must ship at least one concrete deliverable (code that compiles, not +design documents). 80% building, 20% exploring. 17. *Hybrid mode +(audit-then-focus)* — new default mode. First 20% of budget meanders +broadly (discover). Remaining 80% goes deep on the 1-2 highest-weighted +MUSTs found. Best of both worlds. 18. *Regression handling* — +regressions are always MUSTs. Don’t document a regression and move on to +easier work. 19. *Cherry-picking counter* — after completing any +satisfying task, ask "`What am I avoiding?`" If the answer is hard work, +go do it. + +*v4 refinements (2026-03-23, ECHIDNA gate meander continued):* 20. +*Difficulty-Impact Matrix* — after audit, classify every actionable item +into a 2x2 grid (Hard/Easy vs High/Low Impact). Work top-left (hard + +high impact) FIRST. These are exactly what cherry-picking avoids. Easy + +high impact second. Easy + low impact only if budget remains. Impact = +blocks other work, fixes safety issue, fixes regression, unblocks user +action, or is on a deadline path. 21. *Systematic coverage tracking* — +when meandering through a gated task list, maintain a Touched/Skipped +checklist during Phase A. Before starting Phase B, verify no skipped +section contains a MUST. At session end, report explicitly: "`Touched: +[list]. Skipped: [list]. No known MUSTs in skipped sections (verified by +reading headers).`" Prevents systematic blind spots from the random +walk. 22. *The 30% regression ceiling* — spend at most 30% of Phase B on +regression repair. If regressions exceed that, report as critical and +let user prioritise. Prevents regression triage from consuming the +entire session while new work stalls. 23. *Session-end accountability +report* — every session must end with: (a) what was completed, (b) what +was skipped and why, (c) regressions found, (d) difficulty-impact +classification of remaining work, (e) recommended focus for next +session. This forces honest accounting of what the meander chose NOT to +do. + +*v5 refinement (2026-03-23, divergent safety):* 24. *Divergent Invariant +Preservation* — "`amplify uniqueness`" means deepen, not broaden. Before +any divergent work, read the AI manifest and CLAUDE.md for invariants. +Diverge within the riverbanks, not across them. Test: "`Does this deepen +the existing strength, or add a parallel strength?`" If parallel → stop. +The broadening trap (adding Lean4 proofs to an Idris2-only repo, adding +a Haskell backend to a Rust compiler) is the divergent equivalent of +convergent’s over-polishing — it feels productive but violates the +project’s architectural identity. diff --git a/methodologies/proven-first-resolution/README.adoc b/methodologies/proven-first-resolution/README.adoc new file mode 100644 index 0000000..fda1625 --- /dev/null +++ b/methodologies/proven-first-resolution/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Proven-First Error Resolution + +=== Summary + +Check the proven repo for formally verified alternatives before writing +manual fixes. + +=== Source + +Memory file: `+feedback_proven_alternatives.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/proven-first-resolution/README.md b/methodologies/proven-first-resolution/README.md deleted file mode 100644 index 1e84de0..0000000 --- a/methodologies/proven-first-resolution/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Proven-First Error Resolution - -## Summary - -Check the proven repo for formally verified alternatives before writing manual fixes. - -## Source - -Memory file: `feedback_proven_alternatives.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/repo-enrollment/README.adoc b/methodologies/repo-enrollment/README.adoc new file mode 100644 index 0000000..ce3986e --- /dev/null +++ b/methodologies/repo-enrollment/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Three-Tier Repo Enrollment + +=== Summary + +Every new repo: (1) git-private-farm, (2) Hypatia scanning, (3) +gitbot-fleet. + +=== Source + +Memory file: `+standards-and-conventions.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/repo-enrollment/README.md b/methodologies/repo-enrollment/README.md deleted file mode 100644 index fb33484..0000000 --- a/methodologies/repo-enrollment/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Three-Tier Repo Enrollment - -## Summary - -Every new repo: (1) git-private-farm, (2) Hypatia scanning, (3) gitbot-fleet. - -## Source - -Memory file: `standards-and-conventions.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/resource-management/README.adoc b/methodologies/resource-management/README.adoc new file mode 100644 index 0000000..82075d8 --- /dev/null +++ b/methodologies/resource-management/README.adoc @@ -0,0 +1,89 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Resource Management for AI-Assisted Development + +=== Overview + +AI agents create real resource costs that compound quickly during +exploratory or parallel work. These guardrails were learned from +production incidents — OOM crashes, disk exhaustion, and token waste. + +=== System Constraints (hyperpolymath workstation) + +[cols=",,",options="header",] +|=== +|Resource |Limit |Notes +|RAM |32GB total |25GB available typically +|Disk (Eclipse) |477GB, ~200GB free |All repos here +|Disk (Fedora) |232GB, limited free |OS only +|Parallel agents |3 max |Prevent crashes +|Parallel Bash |2 max |Prevent I/O saturation +|=== + +=== Cost Profiles + +==== Rust Builds + +* `+cargo build+` spikes 2-3GB RAM per invocation +* `+target/debug/+` grows to 1-6GB per crate +* Three parallel Rust builds WILL OOM on 32GB +* *Rule:* Build once, reuse. Never build same crate from 2 agents. + +==== Elixir Builds + +* `+mix compile+` is lighter (~500MB RAM) +* `+_build/+` grows to ~200MB per project +* Can run 2 parallel mix compiles safely + +==== Token Budgets + +* Each exploration agent: 50-100K tokens +* Three parallel agents: 150-300K tokens per wave +* TSDM pass (read-only): ~10K tokens +* *Rule:* Set scope: "`~30 tool calls then report`" + +==== Disk Artifacts + +* Rust `+target/+`: 1-6GB per workspace +* Zig `+zig-out/+` + `+zig-cache/+`: 100MB-1GB +* Elixir `+_build/+` + `+deps/+`: 200-500MB per project +* *Rule:* At end of session, report sizes, offer cleanup + +=== Pre-Flight Checklist + +Before launching parallel agents: + +[source,bash] +---- +df -h /var$ECLIPSE_DIR # Check disk (need > 10GB free) +free -h # Check RAM (need > 10GB available) +---- + +=== Incident Log + +[width="100%",cols="23%,35%,25%,17%",options="header",] +|=== +|Date |Incident |Cause |Fix +|2026-03-22 |Eclexia bot consumed 6.3GB disk |`+cargo build+` ran 23 +times |"`Build once`" rule + +|2026-03-22 |OOM crash during parallel audit |3 agents × `+cargo check+` +|Stagger builds + +|2026-03-20 |System hang during heavy session |Full context + large tool +results |Resource awareness caps +|=== + +=== Rules Summary + +[arabic] +. Check `+df -h+` and `+free -h+` before spawning builder agents +. Tell agents "`build once, reuse the binary`" explicitly +. Set scope limits: "`explore for ~30 tool calls then report`" +. After session: `+cargo clean+`, `+rm -rf zig-out/+` for Zig +. If crash appears, check if OOM before assuming logic bug +. Never 2+ agents building same Rust workspace simultaneously +. Stagger builds across agents (each spikes 2-3GB RAM) +. Use `+model: "haiku"+` for simple search/read subagents +. Never glob/grep the full `+/var$REPOS_DIR/+` +. Use `+limit+` on Read for files > 500 lines diff --git a/methodologies/resource-management/README.md b/methodologies/resource-management/README.md deleted file mode 100644 index 22607d6..0000000 --- a/methodologies/resource-management/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Resource Management for AI-Assisted Development - -## Overview - -AI agents create real resource costs that compound quickly during -exploratory or parallel work. These guardrails were learned from -production incidents — OOM crashes, disk exhaustion, and token waste. - -## System Constraints (hyperpolymath workstation) - -| Resource | Limit | Notes | -|----------|-------|-------| -| RAM | 32GB total | 25GB available typically | -| Disk (Eclipse) | 477GB, ~200GB free | All repos here | -| Disk (Fedora) | 232GB, limited free | OS only | -| Parallel agents | 3 max | Prevent crashes | -| Parallel Bash | 2 max | Prevent I/O saturation | - -## Cost Profiles - -### Rust Builds -- `cargo build` spikes 2-3GB RAM per invocation -- `target/debug/` grows to 1-6GB per crate -- Three parallel Rust builds WILL OOM on 32GB -- **Rule:** Build once, reuse. Never build same crate from 2 agents. - -### Elixir Builds -- `mix compile` is lighter (~500MB RAM) -- `_build/` grows to ~200MB per project -- Can run 2 parallel mix compiles safely - -### Token Budgets -- Each exploration agent: 50-100K tokens -- Three parallel agents: 150-300K tokens per wave -- TSDM pass (read-only): ~10K tokens -- **Rule:** Set scope: "~30 tool calls then report" - -### Disk Artifacts -- Rust `target/`: 1-6GB per workspace -- Zig `zig-out/` + `zig-cache/`: 100MB-1GB -- Elixir `_build/` + `deps/`: 200-500MB per project -- **Rule:** At end of session, report sizes, offer cleanup - -## Pre-Flight Checklist - -Before launching parallel agents: -```bash -df -h /var$ECLIPSE_DIR # Check disk (need > 10GB free) -free -h # Check RAM (need > 10GB available) -``` - -## Incident Log - -| Date | Incident | Cause | Fix | -|------|----------|-------|-----| -| 2026-03-22 | Eclexia bot consumed 6.3GB disk | `cargo build` ran 23 times | "Build once" rule | -| 2026-03-22 | OOM crash during parallel audit | 3 agents × `cargo check` | Stagger builds | -| 2026-03-20 | System hang during heavy session | Full context + large tool results | Resource awareness caps | - -## Rules Summary - -1. Check `df -h` and `free -h` before spawning builder agents -2. Tell agents "build once, reuse the binary" explicitly -3. Set scope limits: "explore for ~30 tool calls then report" -4. After session: `cargo clean`, `rm -rf zig-out/` for Zig -5. If crash appears, check if OOM before assuming logic bug -6. Never 2+ agents building same Rust workspace simultaneously -7. Stagger builds across agents (each spikes 2-3GB RAM) -8. Use `model: "haiku"` for simple search/read subagents -9. Never glob/grep the full `/var$REPOS_DIR/` -10. Use `limit` on Read for files > 500 lines diff --git a/methodologies/rsr/README.adoc b/methodologies/rsr/README.adoc new file mode 100644 index 0000000..7c125e5 --- /dev/null +++ b/methodologies/rsr/README.adoc @@ -0,0 +1,68 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Rhodium Standard Repositories (RSR) — as a Methodology + +=== Overview + +RSR is both a template (`+rsr-template-repo+`) and a methodology for +repository standardisation. Every hyperpolymath repo is created from the +template and maintains compliance with the standard. + +=== The RSR Methodology + +==== Core Principle + +All repos share the same structural DNA. A bot, human, or CI system that +understands one RSR repo understands all of them. + +==== What RSR Standardises + +* *17 CI workflows* (security, quality, mirroring, policy enforcement) +* *Checkpoint files* (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml in +`+.machine_readable/+`) +* *Documentation* (README.adoc, EXPLAINME.adoc, SECURITY.md, +CONTRIBUTING.md) +* *Build* (Justfile with standardised recipes) +* *License* (MPL-2.0 with MPL-2.0 fallback) +* *AI manifest* (0-AI-MANIFEST.a2ml or AI.a2ml) +* *Author attribution* (Jonathan D.A. Jewell, noreply email for git) + +==== RSR as Methodology — Open Questions + +[arabic] +. *Is RSR too heavy for docs-only repos?* This methodologies repo +doesn’t need 17 CI workflows, a Containerfile, or a Cargo.toml. Should +there be an RSR-lite variant? +. *Does RSR’s standardisation inhibit divergent work?* When every repo +looks the same, creative projects (languages, research) get pushed +toward the same "`complete`" shape. The Productive Meandering v3 prompt +explicitly warns about this (convergence bias). +. *Is `+just init+` sufficient onboarding?* New repos still need +significant placeholder replacement. Could the template be smarter +(detect language, auto-configure CodeQL matrix, set up correct +Cargo/Mix/Deno structure)? +. *Should RSR checkpoint files be A2ML or SCM?* The repo uses both +formats across different projects. Standardising on one would reduce +cognitive load. + +==== RSR + Other Methodologies + +[width="100%",cols="66%,34%",options="header",] +|=== +|Combined with |Effect +|TSDM |TSDM’s Axis 3 (Audit) naturally checks RSR compliance + +|Productive Meandering |Ring 1 naturally fixes RSR gaps (SPDX headers, +missing docs) + +|Parallel Audit |Agents can split by RSR category (CI, docs, contracts, +code) + +|panic-attack |`+assail+` is the automated RSR compliance checker +|=== + +=== Reference + +* Template: `+~/Documents/hyperpolymath-repos/rsr-template-repo+` +* Compliance tool: `+panic-attack assail .+` +* Verification: `+~/verify-repo-standards.jl+` diff --git a/methodologies/rsr/README.md b/methodologies/rsr/README.md deleted file mode 100644 index cc665c2..0000000 --- a/methodologies/rsr/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Rhodium Standard Repositories (RSR) — as a Methodology - -## Overview - -RSR is both a template (`rsr-template-repo`) and a methodology for repository -standardisation. Every hyperpolymath repo is created from the template and -maintains compliance with the standard. - -## The RSR Methodology - -### Core Principle -All repos share the same structural DNA. A bot, human, or CI system that -understands one RSR repo understands all of them. - -### What RSR Standardises -- **17 CI workflows** (security, quality, mirroring, policy enforcement) -- **Checkpoint files** (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml in `.machine_readable/`) -- **Documentation** (README.adoc, EXPLAINME.adoc, SECURITY.md, CONTRIBUTING.md) -- **Build** (Justfile with standardised recipes) -- **License** (MPL-2.0 with MPL-2.0 fallback) -- **AI manifest** (0-AI-MANIFEST.a2ml or AI.a2ml) -- **Author attribution** (Jonathan D.A. Jewell, noreply email for git) - -### RSR as Methodology — Open Questions - -1. **Is RSR too heavy for docs-only repos?** This methodologies repo doesn't - need 17 CI workflows, a Containerfile, or a Cargo.toml. Should there be - an RSR-lite variant? - -2. **Does RSR's standardisation inhibit divergent work?** When every repo - looks the same, creative projects (languages, research) get pushed toward - the same "complete" shape. The Productive Meandering v3 prompt explicitly - warns about this (convergence bias). - -3. **Is `just init` sufficient onboarding?** New repos still need significant - placeholder replacement. Could the template be smarter (detect language, - auto-configure CodeQL matrix, set up correct Cargo/Mix/Deno structure)? - -4. **Should RSR checkpoint files be A2ML or SCM?** The repo uses both formats - across different projects. Standardising on one would reduce cognitive load. - -### RSR + Other Methodologies - -| Combined with | Effect | -|---------------|--------| -| TSDM | TSDM's Axis 3 (Audit) naturally checks RSR compliance | -| Productive Meandering | Ring 1 naturally fixes RSR gaps (SPDX headers, missing docs) | -| Parallel Audit | Agents can split by RSR category (CI, docs, contracts, code) | -| panic-attack | `assail` is the automated RSR compliance checker | - -## Reference - -- Template: `~/Documents/hyperpolymath-repos/rsr-template-repo` -- Compliance tool: `panic-attack assail .` -- Verification: `~/verify-repo-standards.jl` diff --git a/methodologies/session-design-document/README.adoc b/methodologies/session-design-document/README.adoc new file mode 100644 index 0000000..43a667e --- /dev/null +++ b/methodologies/session-design-document/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Session Design Document + +=== Summary + +Create a dated design document at session start for cross-AI knowledge +transfer. + +=== Source + +Memory file: `+standards-and-conventions.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/session-design-document/README.md b/methodologies/session-design-document/README.md deleted file mode 100644 index 548fc96..0000000 --- a/methodologies/session-design-document/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Session Design Document - -## Summary - -Create a dated design document at session start for cross-AI knowledge transfer. - -## Source - -Memory file: `standards-and-conventions.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/spec-exhaustive-search/README.adoc b/methodologies/spec-exhaustive-search/README.adoc new file mode 100644 index 0000000..7b309c2 --- /dev/null +++ b/methodologies/spec-exhaustive-search/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Spec Exhaustive Search + +=== Summary + +Multi-extension multi-directory search before claiming a spec file +doesn’t exist. + +=== Source + +Memory file: `+feedback_protect_specs.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/spec-exhaustive-search/README.md b/methodologies/spec-exhaustive-search/README.md deleted file mode 100644 index d90115d..0000000 --- a/methodologies/spec-exhaustive-search/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Spec Exhaustive Search - -## Summary - -Multi-extension multi-directory search before claiming a spec file doesn't exist. - -## Source - -Memory file: `feedback_protect_specs.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/topology-standard/README.adoc b/methodologies/topology-standard/README.adoc new file mode 100644 index 0000000..cb74465 --- /dev/null +++ b/methodologies/topology-standard/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== TOPOLOGY.md Standard + +=== Summary + +ASCII architecture diagram + completion dashboard with 10-char progress +bars. + +=== Source + +Memory file: `+standards-and-conventions.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/topology-standard/README.md b/methodologies/topology-standard/README.md deleted file mode 100644 index c1fd2c6..0000000 --- a/methodologies/topology-standard/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# TOPOLOGY.md Standard - -## Summary - -ASCII architecture diagram + completion dashboard with 10-char progress bars. - -## Source - -Memory file: `standards-and-conventions.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/traversal-mode-selection/README.adoc b/methodologies/traversal-mode-selection/README.adoc new file mode 100644 index 0000000..3fab50c --- /dev/null +++ b/methodologies/traversal-mode-selection/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== AI Traversal Mode Selection + +=== Summary + +Ask depth-first / breadth-first / no-stubbing before large multi-file +work. + +=== Source + +Memory file: `+standards-and-conventions.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/traversal-mode-selection/README.md b/methodologies/traversal-mode-selection/README.md deleted file mode 100644 index adfc68d..0000000 --- a/methodologies/traversal-mode-selection/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# AI Traversal Mode Selection - -## Summary - -Ask depth-first / breadth-first / no-stubbing before large multi-file work. - -## Source - -Memory file: `standards-and-conventions.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/tsdm/README.adoc b/methodologies/tsdm/README.adoc new file mode 100644 index 0000000..c9b9fc2 --- /dev/null +++ b/methodologies/tsdm/README.adoc @@ -0,0 +1,99 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Triaxial Software Development Methodology (TSDM) + +=== Overview + +Three-axis methodology applied in strict order: *Scope → Maintenance → +Audit*. Each axis has its own priority ordering. Followed by a +cleanup/finish-off phase and mandatory maintainer dialogue. + +=== When to Use + +* Systematic project assessment (not random walk) +* Pre-release audits +* When guaranteed coverage matters more than serendipitous discovery +* As the "`navigator`" half of a TSDM-Meander alternating pass + +=== The Three Axes + +==== Axis 1: Scope + +*Priority:* must > intend > like + +*Inputs:* - README, roadmap, status docs, CI/security docs - Marker +scan: `+TODO+`, `+FIXME+`, `+XXX+`, `+HACK+`, `+STUB+`, `+PARTIAL+` - +Idris unsound scan: `+believe_me+`, `+assert_total+` + +*Output:* Scoped work assembly — the prioritised work list. + +==== Axis 2: Maintenance + +*Priority:* corrective > adaptive > perfective + +[width="100%",cols="32%,68%",options="header",] +|=== +|Type |Description +|*Corrective* |Defect/regression/safety/security fixes + +|*Adaptive* |Scope reconciliation, stale-reference removal, +obsolete-work culling + +|*Perfective* |Quality improvements derived from Axis 1 honest state +|=== + +==== Axis 3: Audit + +*Priority:* systems > compliance > effects + +[width="100%",cols="22%,46%,32%",options="header",] +|=== +|Type |Description |Tooling +|*Systems* |Required systems present and operating |— + +|*Compliance* |Exceptions explicit, bounded, drift-resistant +|panic-attack + +|*Effects* |Benchmark/operational impact evidence captured |sustainabot +|=== + +=== Cleanup/Finish-Off Phase + +[arabic] +. Root cleanup +. Stale work cull +. Docs sync (human + machine) +. Compliance audit +. Effects audit +. Release summary: must / should / could +. Next actions: corrective / adaptive / perfective + +=== Collaboration + +Maintainer dialogue is *REQUIRED* at the end. Topics: - What changed - +Why - Remaining risks + +=== Machine-Readable Source + +See `+SOFTWARE-DEVELOPMENT-APPROACH.a2ml+` in this directory. + +=== Relationship to Productive Meandering + +TSDM and Productive Meandering are complementary: + +[width="100%",cols="37%,21%,42%",options="header",] +|=== +|Property |TSDM |Meandering +|Coverage |Guaranteed (systematic) |Probabilistic (random walk) + +|Discovery |Low (follows checklist) |High (finds surprises) + +|Completion |Predictable |Unpredictable + +|Best for |Audits, releases, compliance |Exploration, migration, +integration +|=== + +The *TSDM-Meander alternating pass* combines both: TSDM provides the +priority queue, meandering provides the discovery. See the Productive +Meandering v3 prompt for details. diff --git a/methodologies/tsdm/README.md b/methodologies/tsdm/README.md deleted file mode 100644 index c897883..0000000 --- a/methodologies/tsdm/README.md +++ /dev/null @@ -1,84 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Triaxial Software Development Methodology (TSDM) - -## Overview - -Three-axis methodology applied in strict order: **Scope → Maintenance → Audit**. -Each axis has its own priority ordering. Followed by a cleanup/finish-off phase -and mandatory maintainer dialogue. - -## When to Use - -- Systematic project assessment (not random walk) -- Pre-release audits -- When guaranteed coverage matters more than serendipitous discovery -- As the "navigator" half of a TSDM-Meander alternating pass - -## The Three Axes - -### Axis 1: Scope - -**Priority:** must > intend > like - -**Inputs:** -- README, roadmap, status docs, CI/security docs -- Marker scan: `TODO`, `FIXME`, `XXX`, `HACK`, `STUB`, `PARTIAL` -- Idris unsound scan: `believe_me`, `assert_total` - -**Output:** Scoped work assembly — the prioritised work list. - -### Axis 2: Maintenance - -**Priority:** corrective > adaptive > perfective - -| Type | Description | -|------|-------------| -| **Corrective** | Defect/regression/safety/security fixes | -| **Adaptive** | Scope reconciliation, stale-reference removal, obsolete-work culling | -| **Perfective** | Quality improvements derived from Axis 1 honest state | - -### Axis 3: Audit - -**Priority:** systems > compliance > effects - -| Type | Description | Tooling | -|------|-------------|---------| -| **Systems** | Required systems present and operating | — | -| **Compliance** | Exceptions explicit, bounded, drift-resistant | panic-attack | -| **Effects** | Benchmark/operational impact evidence captured | sustainabot | - -## Cleanup/Finish-Off Phase - -1. Root cleanup -2. Stale work cull -3. Docs sync (human + machine) -4. Compliance audit -5. Effects audit -6. Release summary: must / should / could -7. Next actions: corrective / adaptive / perfective - -## Collaboration - -Maintainer dialogue is **REQUIRED** at the end. Topics: -- What changed -- Why -- Remaining risks - -## Machine-Readable Source - -See `SOFTWARE-DEVELOPMENT-APPROACH.a2ml` in this directory. - -## Relationship to Productive Meandering - -TSDM and Productive Meandering are complementary: - -| Property | TSDM | Meandering | -|----------|------|------------| -| Coverage | Guaranteed (systematic) | Probabilistic (random walk) | -| Discovery | Low (follows checklist) | High (finds surprises) | -| Completion | Predictable | Unpredictable | -| Best for | Audits, releases, compliance | Exploration, migration, integration | - -The **TSDM-Meander alternating pass** combines both: TSDM provides the -priority queue, meandering provides the discovery. See the Productive -Meandering v3 prompt for details. diff --git a/methodologies/v-api-quality-gate/README.adoc b/methodologies/v-api-quality-gate/README.adoc new file mode 100644 index 0000000..386cbf6 --- /dev/null +++ b/methodologies/v-api-quality-gate/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== zig API Quality Gate + +=== Summary + +Seven-category checklist for zig implementations before awesome-v +submission. + +=== Source + +Memory file: `+v-api-awesome-checklist.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/v-api-quality-gate/README.md b/methodologies/v-api-quality-gate/README.md deleted file mode 100644 index 4af3920..0000000 --- a/methodologies/v-api-quality-gate/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# zig API Quality Gate - -## Summary - -Seven-category checklist for zig implementations before awesome-v submission. - -## Source - -Memory file: `v-api-awesome-checklist.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/verisimdb-instance-policy/README.adoc b/methodologies/verisimdb-instance-policy/README.adoc new file mode 100644 index 0000000..8df1747 --- /dev/null +++ b/methodologies/verisimdb-instance-policy/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== VeriSimDB Instance Policy + +=== Summary + +Every project gets its own VeriSimDB instance with unique port and +volume. + +=== Source + +Memory file: `+feedback_verisimdb_instance_policy.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/verisimdb-instance-policy/README.md b/methodologies/verisimdb-instance-policy/README.md deleted file mode 100644 index 010a174..0000000 --- a/methodologies/verisimdb-instance-policy/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# VeriSimDB Instance Policy - -## Summary - -Every project gets its own VeriSimDB instance with unique port and volume. - -## Source - -Memory file: `feedback_verisimdb_instance_policy.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details. diff --git a/methodologies/visibility-triad/README.adoc b/methodologies/visibility-triad/README.adoc new file mode 100644 index 0000000..edfad77 --- /dev/null +++ b/methodologies/visibility-triad/README.adoc @@ -0,0 +1,17 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Visibility Triad Campaign + +=== Summary + +Four coordinated campaigns: claim-forge + avatar-foundry + git-seo + +palimpsest-plasma. + +=== Source + +Memory file: `+visibility-triad.md+` + +=== Status + +Stub — full documentation to be extracted from memory and expanded. See +the source memory file for current details. diff --git a/methodologies/visibility-triad/README.md b/methodologies/visibility-triad/README.md deleted file mode 100644 index 6b715f5..0000000 --- a/methodologies/visibility-triad/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Visibility Triad Campaign - -## Summary - -Four coordinated campaigns: claim-forge + avatar-foundry + git-seo + palimpsest-plasma. - -## Source - -Memory file: `visibility-triad.md` - -## Status - -Stub — full documentation to be extracted from memory and expanded. -See the source memory file for current details.