-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path0-AI-MANIFEST.a2ml
More file actions
131 lines (95 loc) · 5.5 KB
/
0-AI-MANIFEST.a2ml
File metadata and controls
131 lines (95 loc) · 5.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
# ⚠️ STOP - CRITICAL READING REQUIRED
**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
## WHAT IS THIS?
This is the AI manifest for **KRL**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization
- Key root audit documents that constrain release and publication claims
## CANONICAL LOCATIONS (UNIVERSAL RULE)
### Machine-Readable Metadata: `.machine_readable/` ONLY
These 6 a2ml files MUST exist in `.machine_readable/` directory ONLY:
1. **STATE.a2ml** - Project state, progress, blockers
2. **META.a2ml** - Architecture decisions, governance
3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
4. **AGENTIC.a2ml** - AI agent interaction patterns
5. **NEUROSYM.a2ml** - Neurosymbolic integration config
6. **PLAYBOOK.a2ml** - Operational runbook
**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.
### Anchor File: `.machine_readable/anchors/ANCHOR.a2ml` ONLY
Canonical authority and semantic-boundary declaration MUST exist at:
` .machine_readable/anchors/ANCHOR.a2ml `
Do not place `ANCHOR.a2ml` at repository root.
### Maintenance Policies: `.machine_readable/policies/` ONLY
Canonical maintenance/governance files MUST exist under:
` .machine_readable/policies/ `
Minimum required files:
- `MAINTENANCE-AXES.a2ml`
- `MAINTENANCE-CHECKLIST.a2ml`
- `SOFTWARE-DEVELOPMENT-APPROACH.a2ml`
Do not place maintenance policy files in repository root.
### Bot Directives: `.machine_readable/bot_directives/` ONLY
Bot-specific instructions for your automated agents.
### Contractiles: `.machine_readable/contractiles/` ONLY
Policy enforcement contracts (k9, dust, lust, must, trust).
### AI Configuration & Guides: `.machine_readable/ai/` ONLY
- `AI.a2ml` - Language-specific or LLM-specific patterns
- `PLACEHOLDERS.md` - Bootstrap guide
### Community & Forge Metadata: `.github/` ONLY
- `CODEOWNERS` - Review assignments
- `MAINTAINERS` - Machine-readable contact list
- `SUPPORT` - Support channels
- `SECURITY.md` - Technical security policy
- `CONTRIBUTING.md` - Technical contribution manual
- `CODE_OF_CONDUCT.md` - Conduct rules
### Agent Instructions: `.machine_readable/agent_instructions/` ONLY
Methodology-aware AI agent configuration (ADR-002):
- `methodology.a2ml` - Mode, invariants, ring ceiling, priority weights
- `coverage.a2ml` - Session coverage tracking (visited, skipped, MUSTs)
- `debt.a2ml` - Meander debt carried between sessions
Entry points:
- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point, read FIRST)
## CORE INVARIANTS
1. **No state file duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc.
2. **Single source of truth** - `.machine_readable/` is authoritative
3. **No stale metadata** - If root state files exist, they are OUT OF DATE
4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell <[email protected]>"
6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`)
7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile`
8. **Container orchestration** - `selur-compose`, never `docker-compose`
## REPOSITORY STRUCTURE
This repo follows the **Dual-Track** architecture:
```
KRL/
├── 0-AI-MANIFEST.a2ml # THIS FILE (start here)
├── AUDIT.adoc # Root audit gate summary (read before making release/publication claims)
├── README.adoc # High-level pitch — excitement and awe (Rich Human)
├── EXPLAINME.adoc # Developer deep-dive — how it works (Rich Nerd)
├── ROADMAP.adoc # Future direction
├── CONTRIBUTING.adoc # Human contribution guide
├── GOVERNANCE.adoc # Decision-making model
├── Justfile # Task runner
├── Containerfile # OCI build
├── LICENSE # Primary license
├── src/ # Source code
│ └── interface/ # Verified Interface Seams
│ ├── abi/ # Idris2 ABI (The Spec)
│ ├── ffi/ # Zig FFI (The Bridge)
│ └── generated/ # C Headers (The Result)
├── container/ # Stapeln container ecosystem
├── docs/ # Technical depths
│ ├── attribution/ # Citations, owners, maintainers (adoc)
│ ├── architecture/ # Topology, diagrams
│ ├── theory/ # Domain theory
│ └── practice/ # Manuals
├── docs/legal/ # Legal exhibits and full texts
└── .machine_readable/ # ALL machine-readable metadata
```
## SESSION STARTUP CHECKLIST
✅ Read THIS file (0-AI-MANIFEST.a2ml) first
✅ Read `AUDIT.adoc` before making release, stable, or publication claims
✅ Understand canonical location: `.machine_readable/`
✅ State understanding of canonical locations
## ATTESTATION PROOF
**"I have read the AI manifest. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, community metadata is in `.github/`, and `AUDIT.adoc` constrains release and publication claims. I will not create duplicate files in the root directory or make optimistic claims that bypass the audit gate."**