diff --git a/.claude/PROJECT.adoc b/.claude/PROJECT.adoc new file mode 100644 index 0000000..1668107 --- /dev/null +++ b/.claude/PROJECT.adoc @@ -0,0 +1,33 @@ +== Universal Chat Extractor - Claude Code Instructions + +This repository contains the Universal Chat Extractor tool. + +=== Project Structure + +.... +universal-chat-extractor/ +├── .claude/ # AI assistant instructions +├── .git/ # Version control +├── .gitignore # Git ignore rules +├── .editorconfig # Editor configuration +└── ... # Extractor files +.... + +=== Build Commands + +Refer to project-specific documentation. + +=== Coding Conventions + +* Follow hyperpolymath standards +* All code must have SPDX license headers +* Use approved languages only (see CLAUDE.md) +* Document all non-obvious decisions + +=== Security + +* No hardcoded secrets +* All secrets through environment variables or secret management +* SHA-pinned dependencies where applicable +* HTTPS only, no HTTP URLs +* No MD5/SHA1 for security purposes diff --git a/.claude/PROJECT.md b/.claude/PROJECT.md deleted file mode 100644 index 87444a5..0000000 --- a/.claude/PROJECT.md +++ /dev/null @@ -1,37 +0,0 @@ - -# Universal Chat Extractor - Claude Code Instructions - -This repository contains the Universal Chat Extractor tool. - -## Project Structure - -``` -universal-chat-extractor/ -├── .claude/ # AI assistant instructions -├── .git/ # Version control -├── .gitignore # Git ignore rules -├── .editorconfig # Editor configuration -└── ... # Extractor files -``` - -## Build Commands - -Refer to project-specific documentation. - -## Coding Conventions - -- Follow hyperpolymath standards -- All code must have SPDX license headers -- Use approved languages only (see CLAUDE.md) -- Document all non-obvious decisions - -## Security - -- No hardcoded secrets -- All secrets through environment variables or secret management -- SHA-pinned dependencies where applicable -- HTTPS only, no HTTP URLs -- No MD5/SHA1 for security purposes diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] 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..2f54479 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,65 @@ +== Changelog + +All notable changes to `+universal-chat-extractor+` 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 CLADE.a2ml — clade taxonomy declaration + +==== Fixed + +* fix(licence): #3 isolated — clear scaffold-placeholder leak +(universal-chat-extractor) (#54) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#51) +* fix(ci): sync hypatia-scan.yml to canonical (#50) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#53) +* ci: bump actions/upload-artifact SHA to current v4 (#48) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts +* ci: deploy dogfood-gate, add Groove manifest and CRG tests + +=== 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 +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 1776f98..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Changelog - -All notable changes to `universal-chat-extractor` 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 CLADE.a2ml — clade taxonomy declaration - -### Fixed - -- fix(licence): #3 isolated — clear scaffold-placeholder leak (universal-chat-extractor) (#54) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#51) -- fix(ci): sync hypatia-scan.yml to canonical (#50) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#53) -- ci: bump actions/upload-artifact SHA to current v4 (#48) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts -- ci: deploy dogfood-gate, add Groove manifest and CRG tests - -## 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 bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +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..d912cf5 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,110 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/universal-chat-extractor.git +cd universal-chat-extractor + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create universal-chat-extractor-dev toolbox enter +universal-chat-extractor-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +universal-chat-extractor/ ├── 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/universal-chat-extractor/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/universal-chat-extractor/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/universal-chat-extractor/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/universal-chat-extractor/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 b1445d8..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/universal-chat-extractor.git -cd universal-chat-extractor - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create universal-chat-extractor-dev -toolbox enter universal-chat-extractor-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -universal-chat-extractor/ -├── 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/universal-chat-extractor/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/universal-chat-extractor/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/universal-chat-extractor/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/universal-chat-extractor/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..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index fd95f90..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +0,0 @@ - -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. 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 ab42fae..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,28 +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..6955fbf --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,150 @@ +== TEST-NEEDS.md — CRG Grade C Achievement Record + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +This document records the test categories added to achieve CRG Grade C +for `+universal-chat-extractor+`. + +____ +*Test runner update (campaign #239 STEP 7, 2026-05-31)*: the seven +`+.ts+` test files described below were ported to Idris2 in commit +`+cdf791f+` ("`estate port 11/11 — FINAL`"). The canonical test sources +now live in `+tests/idris2/+` (`+UnitTest.idr+`, `+SmokeTest.idr+`, +`+PropertyTest.idr+`, `+E2ETest.idr+`, `+ContractTest.idr+`, +`+AspectTest.idr+`, `+BenchTest.idr+`) with `+Main.idr+` as the runner +entry point. Build via the `+.ipkg+` package: +`+idris2 --build universal-chat-extractor-tests.ipkg && ./build/exec/universal-chat-extractor-tests+`. +The original `+.ts+` paths in the sections below are kept as historical +reference for the CRG-C audit record. +____ + +''''' + +=== Context + +`+universal-chat-extractor+` is a pre-implementation scaffold. No +application source code exists yet — only the ABI/FFI skeleton +(`+src/abi/*.idr+`, `+ffi/zig/src/main.zig+`) and RSR standard files. +The ABI files still contain `+{{project}}+` template placeholders +requiring instantiation. + +All tests validate structural and policy invariants rather than +application logic. This is the correct approach for a scaffold-stage +repo. + +Additionally, the unit tests include domain-specific helper functions +for the eventual chat extraction use case (timestamp validation, +platform name normalisation, known-platform lookup) to provide a +meaningful unit-test baseline that can grow alongside the +implementation. + +''''' + +=== CRG C Test Categories + +==== 1. Unit Tests — `+tests/unit_test.ts+` + +Validates individual logical units in isolation: - SPDX header +extraction function (4 tests) - Placeholder detection function (3 tests) +- Chat extraction domain helpers: timestamp validation (3 tests), +platform lookup (3 tests) - STATE.a2ml metadata structure (3 tests) - +LICENSE file content (2 tests) - AI manifest presence (2 tests) + +*Total: 20 tests* + +==== 2. Smoke Tests — `+tests/smoke_test.ts+` + +Verifies the repo is in a functional, non-broken state: - 15 required +top-level files - 15 required directories (including `+src/abi/+`) - 6 +A2ML checkpoint files - 3 .well-known files - ABI/FFI scaffold files (5 +tests) - SECURITY.md content - README.adoc domain terminology + +*Total: 47 tests* + +==== 3. Property-Based (P2P) Tests — `+tests/property_test.ts+` + +Table-driven generative tests verifying invariants across file classes: +- All .a2ml files have SPDX headers (with documented exemptions for +scaffold files) - All .a2ml files use MPL-2.0 - All .idr ABI files have +SPDX headers - All hook scripts have shebangs - SPDX extraction is +deterministic across 5 comment styles - Platform name normalisation +across 4 cases - Contractile files exist and are non-empty - README.adoc +has minimum heading count + +*Total: 17 tests* + +==== 4. E2E / Reflexive Tests — `+tests/e2e_test.ts+` + +End-to-end validation from an external perspective: - Self-hosting SPDX +reflexive check - All test .ts files carry SPDX headers - 4 CI hook +scripts exist and are non-empty - ABI-FFI-README.md is coherent - +TOPOLOGY.md exists - NOTICE is non-trivial - Justfile has test recipe - +Deno runtime check - 3 QUICKSTART guides - 2 Idris2 ABI files are +non-empty + +*Total: 14 tests* + +==== 5. Contract Tests — `+tests/contract_test.ts+` + +Verifies obligations to consumers, RSR standard, ABI/FFI architecture, +and integrators: - RSR checkpoint file locations and anti-patterns (6 +tests) - ABI/FFI architecture contract: Idris2 + Zig (4 tests) - License +policy compliance (3 tests) - Hypatia CI integration (2 tests) - Author +attribution - Stapeln container definition - Contractile interface (2 +tests) + +*Total: 20 tests* + +==== 6. Aspect Tests — `+tests/aspect_test.ts+` + +Cross-cutting concerns spanning all modules: - Security policy (5 tests) +- Code of conduct (2 tests) - EditorConfig consistency (3 tests) - 7 +banned file patterns - No tsconfig.json - 4 documentation files +non-empty - Test files use Deno.test + +*Total: 23 tests* + +==== 7. Benchmarks — `+tests/bench_test.ts+` + +Baselined performance of core operations (run with `+deno bench+`): - +File I/O: LICENSE, README.adoc, STATE.a2ml, Layout.idr (4 ops) - Chat +parsing: single line, 100-line batch (2 ops) - Regex: SPDX match, +placeholder detection (2 ops) - Platform routing: Set.has known/unknown +(2 ops) - Parse: JSON.parse, JSON.stringify (2 ops) + +*Baseline results captured 2026-04-04:* - Single chat line parse: ~672 +ns/op - Platform Set.has (known): ~21 ns/op - SPDX regex match: ~699 +ns/op - File read (LICENSE): ~200 µs/op + +''''' + +=== Running Tests + +[source,sh] +---- +# All test categories +deno test tests/ --allow-read + +# Individual categories +deno test tests/unit_test.ts --allow-read +deno test tests/smoke_test.ts --allow-read +deno test tests/property_test.ts --allow-read +deno test tests/e2e_test.ts --allow-read +deno test tests/contract_test.ts --allow-read +deno test tests/aspect_test.ts --allow-read + +# Benchmarks (separate runner) +deno bench tests/bench_test.ts --allow-read +---- + +''''' + +=== Notes + +* Zig/Idris2 tests remain `+{{project}}+`-templated; run +`+zig build test+` after instantiation. +* When application code is added, extend unit tests with actual +extraction logic. +* Platform-specific extraction tests (Slack JSON, Discord exports, etc.) +belong in future integration tests as real chat log fixtures. +* Benchmarks should be re-baselined after implementation is uploaded. diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index c865152..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,169 +0,0 @@ - -# TEST-NEEDS.md — CRG Grade C Achievement Record - - - -## CRG Grade: C — ACHIEVED 2026-04-04 - -This document records the test categories added to achieve CRG Grade C for -`universal-chat-extractor`. - -> **Test runner update (campaign #239 STEP 7, 2026-05-31)**: the seven `.ts` -> test files described below were ported to Idris2 in commit `cdf791f` -> ("estate port 11/11 — FINAL"). The canonical test sources now live in -> `tests/idris2/` (`UnitTest.idr`, `SmokeTest.idr`, `PropertyTest.idr`, -> `E2ETest.idr`, `ContractTest.idr`, `AspectTest.idr`, `BenchTest.idr`) -> with `Main.idr` as the runner entry point. Build via the `.ipkg` package: -> `idris2 --build universal-chat-extractor-tests.ipkg && ./build/exec/universal-chat-extractor-tests`. -> The original `.ts` paths in the sections below are kept as historical -> reference for the CRG-C audit record. - ---- - -## Context - -`universal-chat-extractor` is a pre-implementation scaffold. No application -source code exists yet — only the ABI/FFI skeleton (`src/abi/*.idr`, -`ffi/zig/src/main.zig`) and RSR standard files. The ABI files still contain -`{{project}}` template placeholders requiring instantiation. - -All tests validate structural and policy invariants rather than application -logic. This is the correct approach for a scaffold-stage repo. - -Additionally, the unit tests include domain-specific helper functions for the -eventual chat extraction use case (timestamp validation, platform name -normalisation, known-platform lookup) to provide a meaningful unit-test -baseline that can grow alongside the implementation. - ---- - -## CRG C Test Categories - -### 1. Unit Tests — `tests/unit_test.ts` - -Validates individual logical units in isolation: -- SPDX header extraction function (4 tests) -- Placeholder detection function (3 tests) -- Chat extraction domain helpers: timestamp validation (3 tests), platform lookup (3 tests) -- STATE.a2ml metadata structure (3 tests) -- LICENSE file content (2 tests) -- AI manifest presence (2 tests) - -**Total: 20 tests** - -### 2. Smoke Tests — `tests/smoke_test.ts` - -Verifies the repo is in a functional, non-broken state: -- 15 required top-level files -- 15 required directories (including `src/abi/`) -- 6 A2ML checkpoint files -- 3 .well-known files -- ABI/FFI scaffold files (5 tests) -- SECURITY.md content -- README.adoc domain terminology - -**Total: 47 tests** - -### 3. Property-Based (P2P) Tests — `tests/property_test.ts` - -Table-driven generative tests verifying invariants across file classes: -- All .a2ml files have SPDX headers (with documented exemptions for scaffold files) -- All .a2ml files use MPL-2.0 -- All .idr ABI files have SPDX headers -- All hook scripts have shebangs -- SPDX extraction is deterministic across 5 comment styles -- Platform name normalisation across 4 cases -- Contractile files exist and are non-empty -- README.adoc has minimum heading count - -**Total: 17 tests** - -### 4. E2E / Reflexive Tests — `tests/e2e_test.ts` - -End-to-end validation from an external perspective: -- Self-hosting SPDX reflexive check -- All test .ts files carry SPDX headers -- 4 CI hook scripts exist and are non-empty -- ABI-FFI-README.md is coherent -- TOPOLOGY.md exists -- NOTICE is non-trivial -- Justfile has test recipe -- Deno runtime check -- 3 QUICKSTART guides -- 2 Idris2 ABI files are non-empty - -**Total: 14 tests** - -### 5. Contract Tests — `tests/contract_test.ts` - -Verifies obligations to consumers, RSR standard, ABI/FFI architecture, and integrators: -- RSR checkpoint file locations and anti-patterns (6 tests) -- ABI/FFI architecture contract: Idris2 + Zig (4 tests) -- License policy compliance (3 tests) -- Hypatia CI integration (2 tests) -- Author attribution -- Stapeln container definition -- Contractile interface (2 tests) - -**Total: 20 tests** - -### 6. Aspect Tests — `tests/aspect_test.ts` - -Cross-cutting concerns spanning all modules: -- Security policy (5 tests) -- Code of conduct (2 tests) -- EditorConfig consistency (3 tests) -- 7 banned file patterns -- No tsconfig.json -- 4 documentation files non-empty -- Test files use Deno.test - -**Total: 23 tests** - -### 7. Benchmarks — `tests/bench_test.ts` - -Baselined performance of core operations (run with `deno bench`): -- File I/O: LICENSE, README.adoc, STATE.a2ml, Layout.idr (4 ops) -- Chat parsing: single line, 100-line batch (2 ops) -- Regex: SPDX match, placeholder detection (2 ops) -- Platform routing: Set.has known/unknown (2 ops) -- Parse: JSON.parse, JSON.stringify (2 ops) - -**Baseline results captured 2026-04-04:** -- Single chat line parse: ~672 ns/op -- Platform Set.has (known): ~21 ns/op -- SPDX regex match: ~699 ns/op -- File read (LICENSE): ~200 µs/op - ---- - -## Running Tests - -```sh -# All test categories -deno test tests/ --allow-read - -# Individual categories -deno test tests/unit_test.ts --allow-read -deno test tests/smoke_test.ts --allow-read -deno test tests/property_test.ts --allow-read -deno test tests/e2e_test.ts --allow-read -deno test tests/contract_test.ts --allow-read -deno test tests/aspect_test.ts --allow-read - -# Benchmarks (separate runner) -deno bench tests/bench_test.ts --allow-read -``` - ---- - -## Notes - -- Zig/Idris2 tests remain `{{project}}`-templated; run `zig build test` after instantiation. -- When application code is added, extend unit tests with actual extraction logic. -- Platform-specific extraction tests (Slack JSON, Discord exports, etc.) belong in future - integration tests as real chat log fixtures. -- Benchmarks should be re-baselined after implementation is uploaded. diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 808234a..fb8e70e 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Universal Chat Extractor — Project Topology -# Universal Chat Extractor — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / USER │ │ (CLI Interface / Privacy HUD) │ @@ -47,11 +40,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Deno / ReScript 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── PARSER REGISTRY @@ -71,25 +64,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██░░░░░░░░ ~20% Specification Phase -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Chat Export ──────► Parser Registry ─────► Unified Schema ────► Export File │ │ │ │ ▼ ▼ ▼ ▼ Privacy Rules ───► Anonymization ──────► Local Processing ────► Report -``` +.... -## 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/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..1fddaca --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,70 @@ +== Tech-Debt Audit — universal-chat-extractor — 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:* `+2026-05-22+`. + +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 + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 11 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |152 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=152 docs=1/36+` +|=== + +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 6f95585..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Tech-Debt Audit — universal-chat-extractor — 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:** `2026-05-22`. - -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 - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 11 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 152 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=152 docs=1/36` | - - -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..ed92437 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-chat-extractor (Developer) + +=== What is universal-chat-extractor? + +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 9c8c982..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-chat-extractor (Developer) - -## What is universal-chat-extractor? -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..9ccd3a4 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-chat-extractor (User) + +=== What is universal-chat-extractor? + +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 95d2a10..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-chat-extractor (User) - -## What is universal-chat-extractor? -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