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.