docs: replace template placeholders with bespoke phronesiser content

Replace all generic -iser template content with phronesiser-specific
deontic logic types, ethical constraint engine implementation, and
domain documentation. Idris2 ABI now defines DeonticModality,
EthicalConstraint, ValueAlignment, HarmPrevention, and AuditDecision
with formal proofs. Zig FFI implements constraint evaluation engine
with add/remove/evaluate/audit-trail operations. README, ROADMAP,
TOPOLOGY, and all 6a2 machine-readable files updated to reflect
the ethical constraint domain.

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 phronesiser
 # 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,9 @@ 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 introduce obligation/prohibition contradictions in constraint sets
+# - Never allow AuditDecision to be silently dropped (every action must be audited)
+# - Never weaken existing harm prevention boundaries without explicit justification
 
 [maintenance-integrity]
 fail-closed = true
@@ -30,6 +33,13 @@ allow-silent-skip = false
 require-rerun-after-fix = true
 release-claim-requires-hard-pass = true
 
+[domain-specific-rules]
+# Phronesiser-specific invariants:
+# - DeonticModality must remain a closed enum (Obligation | Permission | Prohibition)
+# - AuditDecision must remain a trichotomy (Permitted | Denied | Escalated)
+# - HarmSeverity ordering must be monotonic (Negligible < Minor < Moderate < Severe < Critical)
+# - Constraint evaluation must be deterministic (same inputs = same AuditDecision)
+
 [automation-hooks]
 # on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml
 # on-exit: Update STATE.a2ml with session outcomes

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,13 +6,14 @@
   (version "0.1.0")
   (name "phronesiser")
   (type "tool")
-  (purpose "Add provably safe ethical constraints to AI agents")
+  (purpose "Add provably safe ethical constraints to AI agents via Phronesis deontic logic")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
-    (top-3 ("typedqliser" "chapeliser" "verisimiser")))
+    (domain "AI safety and ethics — deontic constraint enforcement")
+    (unique-value "Only -iser that provides formal ethical guarantees via deontic logic proofs"))
 
   (related-projects
     (project "iseriser"
@@ -27,12 +28,21 @@
     (project "verisimiser"
       (relationship "sibling-priority-3")
       (description "VeriSimDB octad database augmentation"))
-    (project "squeakwell"
-      (relationship "sibling")
-      (description "Database recovery via constraint propagation"))
+    (project "phronesis"
+      (relationship "upstream-language")
+      (description "Nextgen language for ethical reasoning on the BEAM VM — phronesiser makes it accessible"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — may share deontic logic proof modules"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine"))
+    (project "boj-server"
+      (relationship "integration-target")
+      (description "MCP server — phronesiser cartridge for constraint management"))
+    (project "verisimdb"
+      (relationship "integration-target")
+      (description "Backing store for audit trail persistence"))
+    (project "panll"
+      (relationship "integration-target")
+      (description "Panel framework — constraint visualisation and editing panels"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,60 @@
 
 (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 Phronesis ethical reasoning accessible without learning deontic logic")
+      (decision "Use manifest-driven code generation: user describes ethical constraints in TOML, phronesiser generates formally verified guardrails")
+      (consequences "Users write zero Phronesis code; all deontic logic complexity hidden in the -iser"))
 
     (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")
-      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
+      (context "Need verified interop between Rust CLI, Phronesis constraint engine, and user agents")
+      (decision "Idris2 ABI for formal proofs of constraint soundness, Zig FFI for C-ABI constraint evaluation bridge")
+      (consequences "Compile-time guarantees that obligation/prohibition sets are non-contradictory; zero runtime overhead"))
 
-    (adr "003-rsr-template"
+    (adr "003-deontic-logic-model"
+      (status "accepted")
+      (context "Need formal model for ethical constraints that is both rigorous and practical")
+      (decision "Use standard deontic logic: Obligation (must), Permission (may), Prohibition (must-not)")
+      (consequences "Well-studied formal system; decidable evaluation; clear audit trail semantics"))
+
+    (adr "004-audit-decision-trichotomy"
+      (status "accepted")
+      (context "Every agent action must produce exactly one auditable decision")
+      (decision "Three-outcome model: Permitted (proof of safety), Denied (proof of violation), Escalated (ambiguity)")
+      (consequences "No silent failures; human oversight for genuinely ambiguous cases; complete audit trail"))
+
+    (adr "005-harm-prevention-taxonomy"
+      (status "accepted")
+      (context "Need structured harm classification for constraint severity")
+      (decision "Six harm domains (physical, psychological, financial, privacy, reputational, environmental) x five severity levels (negligible through critical)")
+      (consequences "Granular enforcement; severity-proportional responses; domains extensible"))
+
+    (adr "006-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")))
 
   (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 and manifest parsing"))
+    (language "Idris2" (purpose "ABI formal proofs — deontic soundness, constraint non-contradiction"))
+    (language "Zig" (purpose "FFI C-ABI bridge — constraint evaluation engine"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
+    (principle "Deontic soundness"
+      (explanation "Obligation and prohibition must never apply to the same scope — proven at compile time via Idris2"))
+    (principle "Audit completeness"
+      (explanation "Every evaluated action produces exactly one AuditDecision — no silent failures"))
+    (principle "Severity-proportional enforcement"
+      (explanation "Harm severity determines response: negligible=log, minor=warn, moderate=require-permission, severe=block, critical=immediate-deny"))
     (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
+      (explanation "User intent captured in TOML; all constraint generation is deterministic and reproducible"))
     (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 interface correctness at compile time"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,27 @@
 # 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 phronesiser
 # 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
+scan-depth = "deep"  # deep because ethical constraints demand thorough analysis
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
+# Phronesiser-specific symbolic rules:
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "deontic-soundness", pattern = "Obligation.*Prohibition.*same-scope", severity = "critical" }
+# - { name = "audit-completeness", pattern = "evaluate.*without.*AuditDecision", severity = "critical" }
+# - { name = "harm-severity-ordering", pattern = "Negligible.*>.*Critical", severity = "error" }
 
 [neural-config]
-# Neural pattern detection settings
-# confidence-threshold = 0.85
+# Neural pattern detection settings for ethical constraint analysis
+# confidence-threshold = 0.95  (higher than default — ethics demands certainty)
 # model = "hypatia-v2"
+# domain = "deontic-logic"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,30 +1,33 @@
 # 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 phronesiser
 # 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 = "library"  # phronesiser is a Rust CLI + Zig shared library
 
 [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. If constraint evaluation bugs: check Zig FFI tests first (src/interface/ffi/test/)
+# 6. If ABI mismatch: verify Idris2 types match Zig struct layouts
 
 [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
-# 5. Restore local permissions if needed: `just perms-restore`
-# 6. Run `just container-push` if applicable
+# 3. Verify constraint evaluation correctness: `cd src/interface/ffi && zig build test`
+# 4. Optional local permission hardening: `just perms-snapshot && just perms-lock`
+# 5. Tag and push
+# 6. Restore local permissions if needed: `just perms-restore`
+# 7. Run `just container-push` if applicable
 
 [maintenance-operations]
 # Baseline audit:
@@ -33,3 +36,7 @@ last-updated = "{{CURRENT_DATE}}"
 #   just maint-hard-pass
 # Permission audit:
 #   just perms-audit
+# Constraint engine test:
+#   cd src/interface/ffi && zig build test
+# Rust CLI test:
+#   cargo test

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,34 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "phronesiser")
-    (description "Add provably safe ethical constraints to AI agents")
-    (status "scaffold")
+    (description "Provably safe ethical constraints for AI agents via Phronesis deontic logic")
+    (status "scaffold-documented")
     (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"))
+    (phase "scaffold-documented")
+    (completion-percentage 15)
+    (milestone "Architecture defined, CLI scaffolded, RSR template complete, ABI/FFI types bespoke, 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 Phronesis constraint compilation from TOML to deontic propositions")
+    (step 2 "Complete Idris2 ABI proofs: DeonticModality soundness, NoContradiction, AuditDecision completeness")
+    (step 3 "Complete Zig FFI constraint evaluation engine (beyond stub)")
+    (step 4 "End-to-end example: AI agent with obligation/prohibition guardrails")
+    (step 5 "Constraint conflict detection (obligation vs prohibition on same scope)")
+    (step 6 "Audit trail generation with structured JSON output")
+    (step 7 "Integration tests with real-world constraint sets"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in scaffold-documented 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-to-deontic-proposition constraint compiler in codegen/mod.rs")
+    (action "Define phronesiser.toml schema for obligations, permissions, prohibitions, harm boundaries")
+    (action "Write first end-to-end example: content moderation constraint set")))