From 0d0b150a99a0d8c9a568be95f35f3f4e77fb2555 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:24:25 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++++++++ ARCHITECTURE.md | 47 ------- CHANGELOG.adoc | 130 ++++++++++---------- CHANGELOG.md | 72 ----------- CODE_OF_CONDUCT.adoc | 24 ++++ CODE_OF_CONDUCT.md | 27 ---- CONTRIBUTING.adoc | 108 ++++++++++++++++ CONTRIBUTING.md | 116 ----------------- GOVERNANCE.adoc | 60 +++++++++ GOVERNANCE.md | 60 --------- PROOF-NEEDS.adoc | 42 +++++++ PROOF-NEEDS.md | 26 ---- SECURITY.adoc | 24 ++++ SECURITY.md | 25 ---- TEST-NEEDS.adoc | 91 ++++++++++++++ TEST-NEEDS.md | 63 ---------- TOPOLOGY.md => TOPOLOGY.adoc | 39 +++--- docs/{TOC-ANALYSIS.md => TOC-ANALYSIS.adoc} | 112 ++++++++--------- docs/tech-debt-2026-05-26.adoc | 71 +++++++++++ docs/tech-debt-2026-05-26.md | 57 --------- llm-warmup-dev.adoc | 19 +++ llm-warmup-dev.md | 16 --- llm-warmup-user.adoc | 19 +++ llm-warmup-user.md | 16 --- 24 files changed, 649 insertions(+), 663 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (88%) rename docs/{TOC-ANALYSIS.md => TOC-ANALYSIS.adoc} (95%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md 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 index 660bd6f..660c537 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,69 +1,75 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025 Laminar Contributors +== Changelog + +All notable changes to `+laminar+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add Idris2 ABI, Zig FFI, and V-lang API +* feat: add Groove discovery manifest +* feat: update CLI, rclone client, and mix config +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add AI Gatekeeper Protocol manifest +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#24) +* fix(ci): sync hypatia-scan.yml to canonical (#23) +* fix(ci): adopt canonical hypatia-scan.yml (#22) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#21) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: remove duplicate SCM files from root +* fix(security): ERR-WF-008 and ERR-WF-009 fixes +* fix: correct author name in CITATION.cff +* fix: align CodeQL with repo languages (robot-cleaner) + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) -= Changelog -:toc: - -All notable changes to Laminar 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] - -=== Added -- Placeholder for upcoming features - -== [1.0.0] - 2025-11-27 - -=== Added +==== Documentation -==== Core Features -- Cloud-to-cloud streaming relay architecture -- Zero-persistence data transfer (RAM + NVMe caching) -- Parallel streaming with 32+ concurrent transfers -- Multi-thread streams for large files (BitTorrent-style logic) +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking -==== Intelligence Engine -- Pattern-matching rule system for file decisions -- Automatic filtering of build artifacts (node_modules, _build, target) -- OS junk removal (.DS_Store, Thumbs.db) -- Ghost Links for files > 5GB -- Format conversion support (WAV→FLAC, BMP→WebP) -- Compression for large text files (Zstd) +==== CI -==== Control Plane (Elixir) -- GraphQL API with Absinthe -- Real-time subscriptions for transfer progress -- REST API fallback endpoints -- Broadway-based 4-lane processing pipeline +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#26) +* ci: bump actions/upload-artifact SHA to current v4 (#19) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts +* ci: deploy dogfood-gate, add CRG tests and Groove manifest, update CI +config -==== Data Plane (Rclone) -- Integration with 40+ cloud providers -- Rclone RC API client -- Checksum verification -- Resume capability via checkpoint caching +=== Pre-history -==== Infrastructure -- Podman containers with Chainguard Wolfi base -- Network physics optimization (TCP BBR, GRO/LRO tuning) -- Tiered storage (RAM Tier 1, NVMe Tier 2) -- Oil Shell installer script +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. -==== Documentation -- Comprehensive wiki with user and developer guides -- AsciiDoc format throughout -- CLAUDE.adoc for AI-assisted development -- Cookbook with tuning recipes - -=== Security -- Non-root container execution -- Credentials never in container images -- TLS for all cloud connections -- eDNS for CDN optimization - -== [0.1.0] - 2025-11-27 - -=== Added -- Initial project structure -- Proof of concept implementation +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 610f4a5..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,72 +0,0 @@ - - -# Changelog - -All notable changes to `laminar` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add Idris2 ABI, Zig FFI, and V-lang API -- feat: add Groove discovery manifest -- feat: update CLI, rclone client, and mix config -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add AI Gatekeeper Protocol manifest -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#24) -- fix(ci): sync hypatia-scan.yml to canonical (#23) -- fix(ci): adopt canonical hypatia-scan.yml (#22) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#21) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: remove duplicate SCM files from root -- fix(security): ERR-WF-008 and ERR-WF-009 fixes -- fix: correct author name in CITATION.cff -- fix: align CodeQL with repo languages (robot-cleaner) - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#26) -- ci: bump actions/upload-artifact SHA to current v4 (#19) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts -- ci: deploy dogfood-gate, add CRG tests and Groove manifest, update CI config - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - 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..8a8faa4 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/laminar.git cd laminar + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create laminar-dev toolbox enter laminar-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +laminar/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── +workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # +This file ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── +README.adoc ├── SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── +Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/laminar/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/laminar/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/laminar/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/laminar/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 4939c45..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/laminar.git -cd laminar - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create laminar-dev -toolbox enter laminar-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -laminar/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/laminar/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/laminar/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/laminar/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/laminar/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] 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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..cbbe486 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,42 @@ +== PROOF-NEEDS.md — laminar + +=== Current State + +* **src/abi/*.idr**: YES — `+Types.idr+` +* *Dangerous patterns*: 0 in own code (hits are all in deps/ — Phoenix, +Absinthe, Credo, Mint) +* *LOC*: ~252,000 (Elixir + deps) +* *ABI layer*: Minimal Idris2 types + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|GraphQL schema validation |Absinthe schema produces valid responses +|Malformed GraphQL responses break all clients + +|Authentication/authorization |Access control decisions are correct and +complete |Auth bypass is a critical vulnerability + +|Data flow integrity |Pipeline transformations preserve data invariants +|Data corruption in transit affects all downstream + +|WebSocket channel safety |Channel join/leave state machine is correct +|Race conditions in real-time channels lose messages + +|ABI type coverage |Extend Types.idr beyond minimal definitions |Current +ABI layer is a skeleton +|=== + +=== Recommended Prover + +*Idris2* — Extend `+src/abi/Types.idr+` with auth decision proofs and +data pipeline invariants. Elixir property-based testing (StreamData) for +runtime validation. + +=== Priority + +*MEDIUM* — Large Elixir web application. Auth and data integrity are the +critical proof targets. Most of the LOC is in deps which are +third-party. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index a6c6366..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,26 +0,0 @@ -# PROOF-NEEDS.md — laminar - -## Current State - -- **src/abi/*.idr**: YES — `Types.idr` -- **Dangerous patterns**: 0 in own code (hits are all in deps/ — Phoenix, Absinthe, Credo, Mint) -- **LOC**: ~252,000 (Elixir + deps) -- **ABI layer**: Minimal Idris2 types - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| GraphQL schema validation | Absinthe schema produces valid responses | Malformed GraphQL responses break all clients | -| Authentication/authorization | Access control decisions are correct and complete | Auth bypass is a critical vulnerability | -| Data flow integrity | Pipeline transformations preserve data invariants | Data corruption in transit affects all downstream | -| WebSocket channel safety | Channel join/leave state machine is correct | Race conditions in real-time channels lose messages | -| ABI type coverage | Extend Types.idr beyond minimal definitions | Current ABI layer is a skeleton | - -## Recommended Prover - -**Idris2** — Extend `src/abi/Types.idr` with auth decision proofs and data pipeline invariants. Elixir property-based testing (StreamData) for runtime validation. - -## Priority - -**MEDIUM** — Large Elixir web application. Auth and data integrity are the critical proof targets. Most of the LOC is in deps which are third-party. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..3f3e562 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,91 @@ +== TEST-NEEDS.md — laminar + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== Current State + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |7 |cli, ghost_linker, intelligence, pipeline, +rclone_client, refinery, schema + +|Integration |1 |transfer_test.exs + +|E2E |0 |None + +|Benchmarks |0 |None +|=== + +*Source modules:* ~1119 Elixir source files (including deps in tree). +Own modules estimated at ~40-60 in apps/laminar_web/lib/ covering +pipeline, intelligence, ghost_linker, refinery, rclone_client, CLI, +schema, transfers. + +=== What’s Missing + +==== P2P (Property-Based) Tests + +* [ ] Pipeline processing: property tests for data transformation +invariants +* [ ] Ghost linker: link resolution property tests +* [ ] Refinery: data cleaning/transformation property tests +* [ ] Schema: arbitrary schema validation + +==== E2E Tests + +* [ ] Full pipeline: ingest -> process -> refine -> output +* [ ] Transfer lifecycle: initiate -> progress -> complete/rollback +* [ ] Intelligence: analysis request -> processing -> result delivery +* [ ] CLI: full command execution round-trips + +==== Aspect Tests + +* *Security:* No tests for transfer authentication, data sanitization in +pipeline, rclone credential handling +* *Performance:* No throughput benchmarks for pipeline stages, no +transfer speed measurements +* *Concurrency:* No tests for parallel pipeline execution, concurrent +transfers, GenServer contention +* *Error handling:* No tests for rclone failure, pipeline stage crash, +interrupted transfers, malformed input + +==== Build & Execution + +* [ ] `+mix test+` verification +* [ ] Zig FFI test (if applicable) +* [ ] Container build + smoke test + +==== Benchmarks Needed + +* [ ] Pipeline stage throughput +* [ ] Transfer speed vs file size +* [ ] Intelligence analysis latency +* [ ] Refinery processing rate +* [ ] Ghost linker resolution speed + +==== Self-Tests + +* [ ] Pipeline configuration self-validation +* [ ] rclone connectivity health check +* [ ] Schema migration verification + +=== Priority + +*CRITICAL.* 8 test files for what appears to be a substantial data +pipeline application. Pipeline processing — the core function — has 1 +test. No benchmarks for a data transfer tool is a major gap. No +concurrency tests for a system that inherently processes data in +parallel is negligent. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 148e394..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,63 +0,0 @@ -# TEST-NEEDS.md — laminar - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 7 | cli, ghost_linker, intelligence, pipeline, rclone_client, refinery, schema | -| Integration | 1 | transfer_test.exs | -| E2E | 0 | None | -| Benchmarks | 0 | None | - -**Source modules:** ~1119 Elixir source files (including deps in tree). Own modules estimated at ~40-60 in apps/laminar_web/lib/ covering pipeline, intelligence, ghost_linker, refinery, rclone_client, CLI, schema, transfers. - -## What's Missing - -### P2P (Property-Based) Tests -- [ ] Pipeline processing: property tests for data transformation invariants -- [ ] Ghost linker: link resolution property tests -- [ ] Refinery: data cleaning/transformation property tests -- [ ] Schema: arbitrary schema validation - -### E2E Tests -- [ ] Full pipeline: ingest -> process -> refine -> output -- [ ] Transfer lifecycle: initiate -> progress -> complete/rollback -- [ ] Intelligence: analysis request -> processing -> result delivery -- [ ] CLI: full command execution round-trips - -### Aspect Tests -- **Security:** No tests for transfer authentication, data sanitization in pipeline, rclone credential handling -- **Performance:** No throughput benchmarks for pipeline stages, no transfer speed measurements -- **Concurrency:** No tests for parallel pipeline execution, concurrent transfers, GenServer contention -- **Error handling:** No tests for rclone failure, pipeline stage crash, interrupted transfers, malformed input - -### Build & Execution -- [ ] `mix test` verification -- [ ] Zig FFI test (if applicable) -- [ ] Container build + smoke test - -### Benchmarks Needed -- [ ] Pipeline stage throughput -- [ ] Transfer speed vs file size -- [ ] Intelligence analysis latency -- [ ] Refinery processing rate -- [ ] Ghost linker resolution speed - -### Self-Tests -- [ ] Pipeline configuration self-validation -- [ ] rclone connectivity health check -- [ ] Schema migration verification - -## Priority - -**CRITICAL.** 8 test files for what appears to be a substantial data pipeline application. Pipeline processing — the core function — has 1 test. No benchmarks for a data transfer tool is a major gap. No concurrency tests for a system that inherently processes data in parallel is negligent. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index a0eebbd..2fd8e86 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Laminar — Project Topology -# Laminar — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / ADMIN │ │ (GraphQL API, CLI, Dashboard) │ @@ -40,11 +36,11 @@ │ Justfile Automation .machine_readable/ │ │ Wolfi Containers 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE RELAY @@ -65,25 +61,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~95% Production-ready cloud relay -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Network Tuning ───► Rclone Engine ──────► RAM Buffer ──────► Cloud Sync │ │ │ │ ▼ ▼ ▼ ▼ Elixir Brain ───► Stream Control ────► NVMe Stage ────► Integrity Check -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/TOC-ANALYSIS.md b/docs/TOC-ANALYSIS.adoc similarity index 95% rename from docs/TOC-ANALYSIS.md rename to docs/TOC-ANALYSIS.adoc index 7327b92..be50397 100644 --- a/docs/TOC-ANALYSIS.md +++ b/docs/TOC-ANALYSIS.adoc @@ -1,18 +1,19 @@ -# Theory of Constraints Analysis: Laminar File Transfer +== Theory of Constraints Analysis: Laminar File Transfer -## The Five Focusing Steps +=== The Five Focusing Steps -1. **IDENTIFY** the constraint -2. **EXPLOIT** the constraint (maximize its output) -3. **SUBORDINATE** everything else to the constraint -4. **ELEVATE** the constraint (add capacity if still bottlenecked) -5. **REPEAT** (find the new constraint) +[arabic] +. *IDENTIFY* the constraint +. *EXPLOIT* the constraint (maximize its output) +. *SUBORDINATE* everything else to the constraint +. *ELEVATE* the constraint (add capacity if still bottlenecked) +. *REPEAT* (find the new constraint) ---- +''''' -## Current System Flow +=== Current System Flow -``` +.... ┌─────────────────────────────────────────────────────────────────────────────┐ │ LAMINAR TRANSFER PIPELINE │ ├─────────────────────────────────────────────────────────────────────────────┤ @@ -37,13 +38,13 @@ │ └───────┘ └───────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -## Capacity Analysis (Per Stage) +=== Capacity Analysis (Per Stage) -``` +.... STAGE THEORETICAL MAX PRACTICAL MAX YOUR OBSERVED ───────────────────────────────────────────────────────────────── 1. Listing ~1000 files/sec ~200 files/sec ? (not measured) @@ -56,15 +57,15 @@ Per-Day Limits: Dropbox API Unlimited* ~10TB/day Not the limit Google Upload 750 GB/SA/day 750 GB/SA/day ← HARD CEILING Network 10 Gbps fiber ~1 GB/s Not the limit -``` +.... ---- +''''' -## Constraint Identification +=== Constraint Identification -### Scenario A: Single Service Account (Current) +==== Scenario A: Single Service Account (Current) -``` +.... CONSTRAINT │ ▼ @@ -77,11 +78,11 @@ Network 10 Gbps fiber ~1 GB/s Not the limit Bottleneck: Google Drive 750GB/day quota Throughput: 750GB / 86400s = 8.7 MB/s sustained (if spreading across day) 750GB / 8hrs = 26 MB/s (if transferring 8hrs/day) -``` +.... -### Scenario B: Multiple Service Accounts (N = 4) +==== Scenario B: Multiple Service Accounts (N = 4) -``` +.... PARALLEL UPLOADS │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┴───────┐ @@ -96,11 +97,11 @@ Throughput: 750GB / 86400s = 8.7 MB/s sustained (if spreading across day) = 3TB/day Bottleneck shifts to: DOWNLOAD from Dropbox (single source) -``` +.... -### Scenario C: N Service Accounts + Parallel Download +==== Scenario C: N Service Accounts + Parallel Download -``` +.... ┌──────────────────┐ ┌──────────────────┐ │ PARALLEL PULL │ │ PARALLEL PUSH │ │ (8 streams) │ │ (N × SAs) │ @@ -117,13 +118,13 @@ Bottleneck shifts to: DOWNLOAD from Dropbox (single source) /file aggregate /core /conn /day NEW BOTTLENECK: Network bandwidth OR Dropbox rate limits -``` +.... ---- +''''' -## The Constraint Migration Path +=== The Constraint Migration Path -``` +.... Step 1: You are HERE ──────────────────── Constraint: Google Drive 750GB/day (single SA) @@ -147,17 +148,18 @@ Step 4: After Sorting Optimization Constraint: Physical network bandwidth Action: Nothing more to do (you've hit physics) Result: THEORETICAL MAXIMUM ACHIEVED -``` +.... ---- +''''' -## Subordination Analysis +=== Subordination Analysis -Everything should be subordinated to the constraint. Here's what that means: +Everything should be subordinated to the constraint. Here’s what that +means: -### When Upload Quota is the Constraint (Single SA) +==== When Upload Quota is the Constraint (Single SA) -``` +.... SUBORDINATION RULES: ───────────────────── 1. Listing: RUN AHEAD - enumerate everything before upload starts @@ -172,11 +174,11 @@ SUBORDINATION RULES: 4. Upload: THE KING - everything serves this Never starve, never overload Track quota precisely, pause gracefully at limit -``` +.... -### When Download is the Constraint (Multiple SAs) +==== When Download is the Constraint (Multiple SAs) -``` +.... SUBORDINATION RULES: ───────────────────── 1. Listing: COMPLETE FIRST - full manifest before any transfer @@ -192,13 +194,13 @@ SUBORDINATION RULES: 4. Upload: FOLLOW DOWNLOAD - start as soon as data available Never accumulate more than buffer size Round-robin across SAs -``` +.... ---- +''''' -## Process Flow With Subordination Points +=== Process Flow With Subordination Points -``` +.... ┌─────────────────────────────────────────────────────────────────────────────────┐ │ OPTIMIZED FLOW (MULTI-SA MODE) │ ├─────────────────────────────────────────────────────────────────────────────────┤ @@ -262,13 +264,13 @@ SUBORDINATION RULES: │ └────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -## Throughput Calculation by Scenario +=== Throughput Calculation by Scenario -``` +.... ┌────────────────────────────────────────────────────────────────────────────────┐ │ THROUGHPUT PROJECTIONS │ ├────────────────────────────────────────────────────────────────────────────────┤ @@ -296,13 +298,13 @@ SUBORDINATION RULES: │ 5TB @ 125 MB/s = 11.4 hours │ │ │ └────────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -## Implementation Priority (Based on TOC) +=== Implementation Priority (Based on TOC) -``` +.... PRIORITY ORDER (Exploit before Elevate): ──────────────────────────────────────── @@ -330,13 +332,13 @@ PRIORITY ORDER (Exploit before Elevate): - Fire-and-forget uploads - Background checksum validation - Retry queue for failures -``` +.... ---- +''''' -## Key Metrics to Monitor +=== Key Metrics to Monitor -``` +.... CONSTRAINT INDICATORS: ───────────────────── @@ -348,4 +350,4 @@ Upload queue full, not moving → Upload rate/network CPU at 100% → Transform (skip compression) Memory exhausted → Buffer size (reduce) 403 Too Many Requests → API rate limit (add backoff) -``` +.... diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..2e164e6 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — laminar — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |143 +|`+docs/+` files |2 +|`+docs/+` LoC |387 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +143 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 15ba9cc..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — laminar — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 143 | -| `docs/` files | 2 | -| `docs/` LoC | 387 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 143 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..056d3c1 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — laminar (Developer) + +=== What is laminar? + +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 85fca66..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — laminar (Developer) - -## What is laminar? -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..d628057 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — laminar (User) + +=== What is laminar? + +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 977fc82..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — laminar (User) - -## What is laminar? -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