0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

# ⚠️ STOP - CRITICAL READING REQUIRED

**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

## WHAT IS THIS?

This is the AI manifest for **dictask** — a speech-to-do pipeline that automates
ingestion of speech notes from a portable recorder into a structured, prioritised,
auditable task list.

## 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 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

- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## 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 MPL-2.0 unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>"
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`
9. **No Python** - Use Rust, Haskell, Julia, or Zig instead
10. **No npm/Node** - Use Deno where JS runtime needed
11. **Haskell for NLP/parsing** - megaparsec for task extraction from transcripts
12. **Idris2 for ABI** - Formal verification of task schema and confidence types
13. **SQLite canonical store** - Local-first, auditable, single source of truth for tasks

## ARCHITECTURE OVERVIEW

```
dictask/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # High-level orientation
├── TOPOLOGY.md                 # Architecture diagram + completion dashboard
├── ROADMAP.adoc                # Future direction
├── CONTRIBUTING.adoc           # Human contribution guide
├── Justfile                    # Task runner
├── Containerfile               # OCI build
├── LICENSE                     # MPL-2.0
├── src/
│   ├── ingest/                 # Rust: udev detection, file archival, cloud upload
│   ├── transcribe/             # Rust: Whisper/Vosk ASR integration
│   ├── parse/                  # Haskell: NLP task extraction (megaparsec)
│   ├── store/                  # Rust: SQLite canonical store + view generation
│   ├── review/                 # Rust: Review queue + notification
│   └── interface/              # Verified Interface Seams
│       ├── abi/                # Idris2 ABI (task schema proofs)
│       ├── ffi/                # Zig FFI (C bridge)
│       └── generated/          # C headers
├── deploy/
│   ├── ansible/                # Local machine setup playbooks
│   └── terraform/              # Cloud provisioning (bucket, IAM)
├── schemas/                    # SQLite schema, JSON schemas
├── docs/                       # Architecture, theory, practice
├── container/                  # Stapeln container ecosystem
└── .machine_readable/          # ALL machine-readable metadata
```

## PIPELINE STAGES (10-stage batch pipeline)

1. **Detect** — udev/systemd detects recorder USB insertion
2. **Ingest** — Archive raw audio, compute SHA-256 checksums
3. **Backup** — Upload encrypted copy to cloud (retry 3x / quarantine)
4. **Transcribe** — Whisper/Vosk offline ASR → transcript JSON
5. **Parse** — Haskell megaparsec extracts candidate intents with confidence scores
6. **Normalise** — Validate, resolve dates, assign priority scores
7. **Deduplicate** — Exact + semantic matching, supersedes linking
8. **Review/Apply** — High-confidence auto-apply; low-confidence → review queue
9. **Generate Views** — Markdown, JSON, CSV exports from canonical SQLite store
10. **Notify** — Dashboard alerts for review items

## SESSION STARTUP CHECKLIST

✅ Read THIS file (0-AI-MANIFEST.a2ml) first
✅ 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, and community metadata is in `.github/`. I will not create duplicate files in
the root directory."**