docs: bespoke documentation for K9 contract toolchain

Replace template placeholders with k9iser-specific content throughout:
- README.adoc: K9 contract anatomy (must/trust/dust/intend pillars),
  safety tiers (Kennel/Yard/Hunt), use cases, architecture diagram
- ROADMAP.adoc: Phase 0-6 from scaffold through ecosystem integration
- TOPOLOGY.md: module map, data flow, FFI boundary table
- Idris2 ABI: K9Contract, Constraint, MustRule, TrustSource, DustRule,
  IntendDeclaration, ValidationResult, SafetyTier, ConfigFormat types
  with dependent-type proofs
- Zig FFI: config parsing, constraint inference, contract generation,
  validation, and attestation functions with k9iser_ prefix
- 0-AI-MANIFEST.a2ml: domain-specific invariants for K9 contracts
- All .machine_readable/6a2/ files: bespoke STATE, META, ECOSYSTEM,
  AGENTIC, NEUROSYM, PLAYBOOK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for k9iser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -22,6 +22,8 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never generate K9 contracts missing any of the four pillars (must/trust/dust/intend)
+# - Never assign a safety tier higher than needed (prefer Kennel over Yard over Hunt)
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,15 +6,19 @@
   (version "0.1.0")
   (name "k9iser")
   (type "tool")
-  (purpose "Wrap configs into self-validating K9 contracts")
+  (purpose "Analyse config files, infer constraints, generate K9 contracts, validate and attest compliance")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
+    (role "K9 contract toolchain — the canonical tool for generating and validating K9 contracts")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
+    (project "contractile"
+      (relationship "upstream-consumer")
+      (description "CLI contract system — k9iser generates contracts that contractile validators consume"))
     (project "iseriser"
       (relationship "meta-framework")
       (description "Generates new -iser project scaffolding"))
@@ -27,12 +31,12 @@
     (project "verisimiser"
       (relationship "sibling-priority-3")
       (description "VeriSimDB octad database augmentation"))
-    (project "squeakwell"
-      (relationship "sibling")
-      (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
       (description "Shared Idris2 verified library"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine"))
+    (project "boj-server"
+      (relationship "integration-target")
+      (description "MCP server — k9iser will ship as a BoJ cartridge"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,59 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
     (adr "001-iser-pattern"
       (status "accepted")
-      (context "Need to make powerful languages accessible without steep learning curves")
-      (decision "Use manifest-driven code generation: user describes WHAT, tool generates HOW")
-      (consequences "Users write zero target language code; all complexity in the -iser"))
+      (context "Need to make K9 contract generation accessible without deep knowledge of contract internals")
+      (decision "Use manifest-driven code generation: user points at configs, k9iser generates contracts")
+      (consequences "Users write zero K9 contract code by hand; all complexity in k9iser"))
 
     (adr "002-abi-ffi-standard"
       (status "accepted")
-      (context "Need verified interop between Rust CLI, target language, and user code")
-      (decision "Idris2 ABI for formal proofs, Zig FFI for C-ABI bridge")
+      (context "Need verified interop between Rust CLI, validation engine, and K9 contract model")
+      (decision "Idris2 ABI for formal proofs of constraint soundness, Zig FFI for C-ABI bridge")
       (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
 
     (adr "003-rsr-template"
       (status "accepted")
       (context "Need consistent project structure across 29+ -iser repos")
       (decision "All repos cloned from rsr-template-repo with full CI/CD and governance")
-      (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one")))
+      (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one"))
+
+    (adr "004-four-pillars"
+      (status "accepted")
+      (context "K9 contracts need a clear structure that maps to the contractile CLI validators")
+      (decision "Every K9 contract contains four pillars: must, trust, dust, intend")
+      (consequences "Generated contracts are directly consumable by contractile must/trust/dust/intend validators"))
+
+    (adr "005-safety-tiers"
+      (status "accepted")
+      (context "Different configs have different risk profiles — deployment configs vs. logging configs")
+      (decision "Three safety tiers: Kennel (read-only), Yard (write files), Hunt (mutate live)")
+      (consequences "Users can gate dangerous operations; CI/CD can enforce tier limits"))
+
+    (adr "006-multi-format"
+      (status "accepted")
+      (context "Real-world projects use a mix of TOML, YAML, JSON, and Nickel configs")
+      (decision "Support all four formats via a unified config AST")
+      (consequences "One constraint inference engine works across all formats; no format lock-in")))
 
   (development-practices
-    (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
+    (language "Rust" (purpose "CLI, orchestration, config parsing, constraint inference, codegen"))
+    (language "Idris2" (purpose "ABI formal proofs — constraint soundness, layout correctness"))
+    (language "Zig" (purpose "FFI C-ABI bridge — validation engine hot path"))
+    (language "Nickel" (purpose "K9 contract output format (.k9.ncl)"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
-    (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
+    (principle "Implicit-to-explicit"
+      (explanation "Turn implicit config assumptions into explicit, machine-checked K9 contracts"))
+    (principle "Four pillars"
+      (explanation "must/trust/dust/intend gives complete coverage of constraint, provenance, hygiene, and intent"))
     (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
-    (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+      (explanation "Idris2 dependent types prove constraint completeness and soundness at compile time"))
+    (principle "Contractile compatibility"
+      (explanation "Generated contracts are first-class inputs to the contractile CLI validator chain"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,21 +1,23 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for k9iser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
+# Custom symbolic rules for k9iser
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "four-pillars-present", pattern = "must.*trust.*dust.*intend", severity = "high" }
+# - { name = "tier-assignment", pattern = "Kennel|Yard|Hunt", severity = "medium" }
 
 [neural-config]
 # Neural pattern detection settings

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,25 +1,26 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for k9iser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "ci-triggered"
+target = "binary"  # binary CLI tool + library crate
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
 # 3. Run `just validate` to check compliance
 # 4. Run `just security` to audit for vulnerabilities
+# 5. Verify K9 contract templates in .machine_readable/contractiles/k9/ are intact
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Justfile
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
 # 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
 # 4. Tag and push

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,35 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "k9iser")
-    (description "Wrap configs into self-validating K9 contracts")
+    (description "Analyse config files, infer constraints, generate K9 contracts, validate, and attest compliance")
     (status "scaffold")
     (priority "—")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
     (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (completion-percentage 8)
+    (milestone "Architecture defined, CLI scaffolded, Idris2 ABI bespoke types written, Zig FFI bespoke stubs written, documentation complete"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "Implement multi-format config parser (TOML, YAML, JSON, Nickel) in bridges/")
+    (step 2 "Build constraint inference engine in core/ — must, trust, dust, intend")
+    (step 3 "Implement K9 contract codegen — emit .k9.ncl files from inferred constraints")
+    (step 4 "Build validation engine — check configs against K9 contracts")
+    (step 5 "Implement cryptographic attestation for validation results")
+    (step 6 "Write Idris2 ABI proofs for constraint completeness and soundness")
+    (step 7 "Build Zig FFI bridge for validation engine hot path")
+    (step 8 "Integration tests with real-world config examples"))
 
   (blockers-and-issues
     (none "Project is in scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement TOML config parser and structural analysis in bridges/")
+    (action "Define the unified config AST that all format parsers produce")
+    (action "Build first must-rule inference from observed config patterns")))