Standardize repo structure (hyperpolymath/mustfile pattern)

- Add .machine_readable/ with 6 SCM files (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK)
- Add Mustfile and justfile (replacing any Makefiles)
- Update .claude/CLAUDE.md with .machine_readable reference
- Clean up duplicate documentation files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Jonathan D.A. Jewell

.claude/CLAUDE.md

@@ -1,3 +1,16 @@
+## Machine-Readable Artefacts
+
+The following files in `.machine_readable/` contain structured project metadata:
+
+- `STATE.scm` - Current project state and progress
+- `META.scm` - Architecture decisions and development practices
+- `ECOSYSTEM.scm` - Position in the ecosystem and related projects
+- `AGENTIC.scm` - AI agent interaction patterns
+- `NEUROSYM.scm` - Neurosymbolic integration config
+- `PLAYBOOK.scm` - Operational runbook
+
+---
+
 # CLAUDE.md - AI Assistant Instructions
 
 ## Language Policy (Hyperpolymath Standard)
@@ -68,3 +81,4 @@ Both are FOSS with independent governance (no Big Tech).
 - No hardcoded secrets
 - SHA-pinned dependencies
 - SPDX license headers on all files
+

.machine_readable/AGENTIC.scm

@@ -0,0 +1,16 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; AGENTIC.scm - AI agent interaction patterns for conflow
+
+(define agentic-config
+  `((version . "1.0.0")
+    (claude-code
+      ((model . "claude-opus-4-5-20251101")
+       (tools . ("read" "edit" "bash" "grep" "glob"))
+       (permissions . "read-all")))
+    (patterns
+      ((code-review . "thorough")
+       (refactoring . "conservative")
+       (testing . "comprehensive")))
+    (constraints
+      ((languages . ())
+       (banned . ("typescript" "go" "python" "makefile"))))))

.machine_readable/ECOSYSTEM.scm

@@ -0,0 +1,20 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; ECOSYSTEM.scm - Ecosystem position for conflow
+;; Media-Type: application/vnd.ecosystem+scm
+
+(ecosystem
+  (version "1.0")
+  (name "conflow")
+  (type "")
+  (purpose "")
+
+  (position-in-ecosystem
+    (category "")
+    (subcategory "")
+    (unique-value ()))
+
+  (related-projects ())
+
+  (what-this-is ())
+
+  (what-this-is-not ()))

.machine_readable/META.scm

@@ -0,0 +1,17 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; META.scm - Meta-level information for conflow
+;; Media-Type: application/meta+scheme
+
+(meta
+  (architecture-decisions ())
+
+  (development-practices
+    (code-style ())
+    (security
+      (principle "Defense in depth"))
+    (testing ())
+    (versioning "SemVer")
+    (documentation "AsciiDoc")
+    (branching "main for stable"))
+
+  (design-rationale ()))

.machine_readable/NEUROSYM.scm

@@ -0,0 +1,13 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; NEUROSYM.scm - Neurosymbolic integration config for conflow
+
+(define neurosym-config
+  `((version . "1.0.0")
+    (symbolic-layer
+      ((type . "scheme")
+       (reasoning . "deductive")
+       (verification . "formal")))
+    (neural-layer
+      ((embeddings . false)
+       (fine-tuning . false)))
+    (integration . ())))

.machine_readable/PLAYBOOK.scm

@@ -0,0 +1,13 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; PLAYBOOK.scm - Operational runbook for conflow
+
+(define playbook
+  `((version . "1.0.0")
+    (procedures
+      ((deploy . (("build" . "just build")
+                  ("test" . "just test")
+                  ("release" . "just release")))
+       (rollback . ())
+       (debug . ())))
+    (alerts . ())
+    (contacts . ())))

.machine_readable/STATE.scm

@@ -0,0 +1,39 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; STATE.scm - Project state for conflow
+;; Media-Type: application/vnd.state+scm
+
+(state
+  (metadata
+    (version "0.0.1")
+    (schema-version "1.0")
+    (created "2026-01-03")
+    (updated "2026-01-03")
+    (project "conflow")
+    (repo "github.com/hyperpolymath/conflow"))
+
+  (project-context
+    (name "conflow")
+    (tagline "")
+    (tech-stack ()))
+
+  (current-position
+    (phase "initial")
+    (overall-completion 0)
+    (components ())
+    (working-features ()))
+
+  (route-to-mvp
+    (milestones ()))
+
+  (blockers-and-issues
+    (critical)
+    (high)
+    (medium)
+    (low))
+
+  (critical-next-actions
+    (immediate)
+    (this-week)
+    (this-month))
+
+  (session-history ()))

CONTRIBUTING.md

@@ -1,209 +1,3 @@
-# Contributing to conflow
+# Contributing
 
-Thank you for your interest in contributing to conflow! This document provides
-guidelines and information for contributors.
-
-## Tri-Perimeter Contribution Framework (TPCF)
-
-conflow uses a graduated trust model based on the RSR Tri-Perimeter Contribution
-Framework:
-
-### Perimeter 1: Core (Maintainers Only)
-
-Changes to critical infrastructure require maintainer review and approval:
-
-- Build system (`Cargo.toml`, `flake.nix`, `justfile`)
-- CI/CD configuration (`.gitlab-ci.yml`)
-- Security-sensitive code (`src/executors/shell.rs`)
-- Release processes
-
-### Perimeter 2: Expert (Trusted Contributors)
-
-Experienced contributors may work on:
-
-- New executor implementations
-- Pipeline validation logic
-- Cache algorithms
-- RSR integration features
-- Performance optimizations
-
-**Requirements**: Previous accepted contributions, demonstrated expertise
-
-### Perimeter 3: Community (Open to All)
-
-Everyone is welcome to contribute:
-
-- Documentation improvements
-- Bug reports and fixes
-- Test coverage
-- Example pipelines
-- Translations
-- Issue triage
-
-## Getting Started
-
-### Prerequisites
-
-- Rust 1.75+ (install via rustup)
-- Nix (optional, for reproducible builds)
-- CUE and Nickel (for integration tests)
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://gitlab.com/hyperpolymath/conflow.git
-cd conflow
-
-# Option 1: Use Nix (recommended)
-nix develop
-
-# Option 2: Manual setup
-cargo build
-cargo test
-```
-
-### Running Tests
-
-```bash
-# All tests
-cargo test
-
-# Specific test
-cargo test test_name
-
-# With output
-cargo test -- --nocapture
-```
-
-## Contribution Process
-
-### 1. Find or Create an Issue
-
-- Check existing issues first
-- Create a new issue for bugs or features
-- Wait for maintainer feedback on large changes
-
-### 2. Fork and Branch
-
-```bash
-git checkout -b feature/my-feature
-# or
-git checkout -b fix/issue-123
-```
-
-### 3. Make Changes
-
-- Follow the code style (run `cargo fmt`)
-- Add tests for new functionality
-- Update documentation as needed
-- Add SPDX headers to new files:
-
-```rust
-// SPDX-License-Identifier: MIT OR Apache-2.0
-// Copyright (c) 2025 conflow contributors
-```
-
-### 4. Commit
-
-Follow conventional commits:
-
-```
-feat: add new cue validation option
-fix: handle empty pipeline gracefully
-docs: update CLI usage examples
-test: add cache invalidation tests
-refactor: simplify stage execution
-```
-
-### 5. Submit Merge Request
-
-- Fill out the MR template
-- Link related issues
-- Ensure CI passes
-- Request review
-
-## Code Style
-
-### Rust Guidelines
-
-- Use `cargo fmt` for formatting
-- Use `cargo clippy` for linting
-- Prefer explicit error handling over `.unwrap()`
-- Document public APIs with doc comments
-- Keep functions focused and small
-
-### Documentation
-
-- Use clear, concise language
-- Include code examples where helpful
-- Update README for user-facing changes
-- Add inline comments for complex logic
-
-## Testing Requirements
-
-### Unit Tests
-
-- All new functions should have tests
-- Test edge cases and error conditions
-- Use descriptive test names
-
-### Integration Tests
-
-- Test CLI commands in `tests/`
-- Test with real CUE/Nickel files
-- Verify cache behavior
-
-### Test Coverage
-
-We aim for >80% coverage on core modules.
-
-## Review Process
-
-### What Reviewers Look For
-
-1. **Correctness**: Does the code work as intended?
-2. **Tests**: Are there adequate tests?
-3. **Documentation**: Is it documented?
-4. **Style**: Does it follow conventions?
-5. **Security**: Any security implications?
-
-### Review Timeline
-
-- Initial response: 2-3 business days
-- Full review: 1 week for small changes
-- Large changes may take longer
-
-## Community
-
-### Communication Channels
-
-- GitLab Issues: Bug reports and feature requests
-- Merge Requests: Code discussions
-- Email: maintainers@conflow.dev
-
-### Meetings
-
-- No regular meetings currently
-- Ad-hoc discussions as needed
-
-## Recognition
-
-Contributors are recognized in:
-
-- `MAINTAINERS.md` for significant contributions
-- Release notes for merged changes
-- `humans.txt` for all contributors
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the
-same MIT OR Apache-2.0 dual license as the project.
-
-## Questions?
-
-Don't hesitate to ask! Open an issue or reach out to maintainers.
-
----
-
-*This contributing guide follows RSR standards and TPCF principles.*
+See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full contribution guidelines.

Mustfile

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Mustfile - hyperpolymath mandatory checks
+# See: https://github.com/hyperpolymath/mustfile
+
+version: 1
+
+checks:
+  - name: security
+    run: just lint
+  - name: tests
+    run: just test
+  - name: format
+    run: just fmt