Skip to content

Commit e87d9f0

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Reflexion design layer + docs/metadata/licence sync (#51)
* feat(reflexion): add reflexive design layer Add a "reflexion" subsystem (design self-relation) under lib/phronesis/reflexion: claim extractor, judgement-evidence graph, invariant-path equivalence engine, append-only SHA-256 hash-chained design ledger, and a revaluation loop, behind a Phronesis.Reflexion facade. It turns toolchain artefacts into explicit claims, compares justification paths across versions, and emits design obligations that gate changes to the language -- without ever auto-mutating its semantics. - 9 Elixir modules + 7 ExUnit test files (32 tests, all green) - docs/REFLEXION.adoc design doc - just reflexion-test / reflexion-demo recipes (also repairs a // comment on Justfile line 2 that broke just parsing) Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AqMopxUsgu78rg5fhWBUkk * docs: sync stale docs/metadata to reality; normalise licence Documentation and machine-readable metadata had drifted from the codebase. Docs/metadata: - README: GitLab -> GitHub URLs, Haskell -> Elixir/Rust roadmap, fix clone block - TOPOLOGY: compiler is Rust/Cargo (not OCaml); accurate module map - LSP-IMPLEMENTATION-SUMMARY: debugger/profiler/doc-generator/package-manager are implemented (were listed "not implemented") - CONTRIBUTING.md: real repository structure (drop non-existent dirs/flake) - .machine_readable/6a2: repair malformed STATE.a2ml, fill blank ECOSYSTEM.a2ml, add META ADRs, refresh dates - .claude/CLAUDE.md + 0-AI-MANIFEST.a2ml: metadata is A2ML in .machine_readable/6a2 (not Guile .scm) - fix dangling SPEC.core.scm symlink -> SPEC.core.a2ml; drop duplicate TESTING-REPORT.scm Licence (owner-approved): MPL-2.0 for code, CC-BY-SA-4.0 for documentation. - add LICENSES/{MPL-2.0,CC-BY-SA-4.0}.txt (REUSE-style); keep top-level LICENSE - remove Palimpsest LICENSE.txt and PALIMPSEST.adoc (not a Palimpsest carve-out) - flip estate-authored .adoc documentation SPDX headers to CC-BY-SA-4.0 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AqMopxUsgu78rg5fhWBUkk --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent b0199a9 commit e87d9f0

46 files changed

Lines changed: 2275 additions & 711 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,15 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
44
-->
55
## Machine-Readable Artefacts
66

7-
The following files in `.machine_readable/` contain structured project metadata:
8-
9-
- `STATE.scm` - Current project state and progress
10-
- `META.scm` - Architecture decisions and development practices
11-
- `ECOSYSTEM.scm` - Position in the ecosystem and related projects
12-
- `AGENTIC.scm` - AI agent interaction patterns
13-
- `NEUROSYM.scm` - Neurosymbolic integration config
14-
- `PLAYBOOK.scm` - Operational runbook
7+
The 6 core A2ML metadata files live in `.machine_readable/6a2/` (the canonical
8+
RSR layout — see https://github.com/hyperpolymath/standards):
9+
10+
- `STATE.a2ml` - Current project state and progress
11+
- `META.a2ml` - Architecture decisions and development practices
12+
- `ECOSYSTEM.a2ml` - Position in the ecosystem and related projects
13+
- `AGENTIC.a2ml` - AI agent interaction patterns
14+
- `NEUROSYM.a2ml` - Neurosymbolic integration config
15+
- `PLAYBOOK.a2ml` - Operational runbook
1516

1617
---
1718

‎.machine_readable/6a2/AGENTIC.a2ml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# AGENTIC.a2ml — AI agent constraints and capabilities
55
[metadata]
66
version = "0.1.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-06-18"
88

99
[agent-permissions]
1010
can-edit-source = true
@@ -28,6 +28,12 @@ allow-silent-skip = false
2828
require-rerun-after-fix = true
2929
release-claim-requires-hard-pass = true
3030

31+
[reflexion]
32+
# The reflexion design layer is advisory: it emits design obligations that gate
33+
# changes to the language, but never auto-mutates the AST, compiler, or runtime.
34+
obligations-are-advisory = true
35+
never-auto-mutate-semantics = true
36+
3137
[automation-hooks]
3238
# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml
3339
# on-exit: Update STATE.a2ml with session outcomes

‎.machine_readable/6a2/ECOSYSTEM.a2ml‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,25 @@
44
# ECOSYSTEM.a2ml — Phronesis ecosystem position
55
[metadata]
66
version = "1.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-06-18"
88

99
[project]
1010
name = "Phronesis"
11-
purpose = ""
12-
role = ""
11+
purpose = "Neuro-symbolic policy language for provably-safe agentic ethical reasoning on the BEAM."
12+
role = "language-and-runtime"
1313

1414
[position-in-ecosystem]
15-
category = ""
15+
category = "nextgen-language"
1616

1717
[related-projects]
1818
projects = [
19-
# No related projects recorded
19+
{ name = "phronesiser", relation = "sibling", note = "The -iser that adds provably-safe ethical constraints to AI agents via Phronesis deontic logic." },
20+
{ name = "standards", relation = "depends-on", note = "Estate standards: RSR template, A2ML format family, licence policy." },
21+
{ name = "rsr-template-repo", relation = "templated-from", note = "Rhodium Standard Repository template (.machine_readable/6a2 layout, contractiles)." },
22+
{ name = "hypatia", relation = "ci", note = "Neurosymbolic CI scanning (report-format = logtalk)." },
23+
{ name = "gitbot-fleet", relation = "ci", note = "Learning / feedback submission." },
24+
{ name = "a2ml-validate-action", relation = "ci", note = "Validates the .machine_readable A2ML artefacts." },
2025
]
26+
27+
[boundaries]
28+
note = "A reflexion design-self-relation layer (claims / judgement-evidence graph / invariant-path equivalence / revaluation) was added 2026-06; it observes the toolchain and gates design changes but never auto-mutates semantics."

‎.machine_readable/6a2/META.a2ml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,18 @@
44
# META.a2ml — Phronesis meta-level information
55
[metadata]
66
version = "0.1.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-06-18"
88

99
[project-info]
1010
license = "MPL-2.0"
1111
author = "Jonathan D.A. Jewell (hyperpolymath)"
1212

1313
[architecture-decisions]
1414
decisions = [
15-
# No ADRs recorded
15+
{ id = "ADR-0001", title = "BEAM/Elixir reference runtime with a Rust to WASM production compiler", status = "accepted" },
16+
{ id = "ADR-0002", title = "Idris2 ABI + Zig FFI as the cross-language boundary standard", status = "accepted" },
17+
{ id = "ADR-0003", title = "Reflexion layer: design self-relation that gates changes, never auto-mutates semantics", status = "proposed" },
18+
{ id = "ADR-0004", title = "Dual licence: MPL-2.0 for code, CC-BY-SA-4.0 for documentation/content", status = "accepted" },
1619
]
1720

1821
[development-practices]

‎.machine_readable/6a2/NEUROSYM.a2ml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# NEUROSYM.a2ml — Neurosymbolic integration metadata
55
[metadata]
66
version = "0.1.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-06-18"
88

99
[hypatia-config]
1010
scan-enabled = true

‎.machine_readable/6a2/PLAYBOOK.a2ml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# PLAYBOOK.a2ml — Operational playbook
55
[metadata]
66
version = "0.1.0"
7-
last-updated = "2026-04-11"
7+
last-updated = "2026-06-18"
88

99
[deployment]
1010
# method = "gitops" # gitops | manual | ci-triggered

‎.machine_readable/6a2/README.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// SPDX-License-Identifier: MPL-2.0
1+
// SPDX-License-Identifier: CC-BY-SA-4.0
22
// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
33
# A2ML 6a2 Directory
44

‎.machine_readable/6a2/STATE.a2ml‎

Lines changed: 21 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -5,56 +5,45 @@
55
[metadata]
66
project = "phronesis"
77
version = "0.9.0"
8-
last-updated = "2026-03-14"
8+
last-updated = "2026-06-18"
99
status = "active"
10-
session = "converted from scheme — 2026-04-11"
10+
session = "reflexion design layer + docs/metadata/licence sync — 2026-06-18"
1111

1212
[project-context]
1313
name = "Phronesis"
14-
purpose = """Scale testing, edge case handling, production deployment"""
15-
completion-percentage = 95
14+
purpose = """Neuro-symbolic policy language for provably-safe agentic ethical reasoning on the BEAM."""
15+
completion-percentage = 80
1616

1717
[position]
18-
phase = "production-ready" # design | implementation | testing | maintenance | archived
18+
phase = "implementation" # design | implementation | testing | maintenance | archived
1919
maturity = "experimental" # experimental | alpha | beta | production | lts
2020

2121
[route-to-mvp]
2222
milestones = [
23-
# No milestones recorded
23+
{ name = "Lexer / parser / AST", completion = 100 },
24+
{ name = "Type checker + analyzer", completion = 100 },
25+
{ name = "Interpreter + tracing + decision traces", completion = 100 },
26+
{ name = "LSP / debugger / profiler / doc-generator", completion = 100 },
27+
{ name = "Consensus (Raft via :ra) runtime + TLA+ spec", completion = 80 },
28+
{ name = "Reflexion design layer (claims / JEG / invariant-path / revaluation)", completion = 70 },
29+
{ name = "Rust to WASM production compiler", completion = 20 },
30+
{ name = "Idris2 ABI + Zig FFI boundary", completion = 30 },
2431
]
2532

2633
[blockers-and-issues]
2734
issues = [
28-
# No blockers recorded
35+
{ id = "pre-existing-test-failures", note = "DebuggerTest (Trace.merge/2 undefined; State.variables), DocGeneratorTest, IncrementalLexerTest, ConformanceTest 04_boolean_logic — predate the reflexion work" },
36+
{ id = "compiler-backend", note = "Rust to WASM codegen is still AST scaffolding only" },
2937
]
3038

3139
[critical-next-actions]
3240
actions = [
33-
"Write comprehensive tests for lexer, parser, interpreter, consensus, RPKI",
34-
"8-12 hours",
35-
"Scale test and real-world BGP feed testing",
36-
"15-20 hours",
37-
"Add Idris2 ABI definitions and Zig FFI layer",
38-
"15-20 hours",
39-
")
40-
(achieved ",
41-
")
42-
(evidence
43-
(unit ",
44-
")
45-
(smoke ",
46-
")
47-
(p2p ",
48-
")
49-
(e2e ",
50-
")
51-
(aspect ",
52-
")
53-
(contract ",
54-
")
55-
(benchmarks ",
41+
"Repair pre-existing test failures (Trace.merge/2 in debugger; State.variables field)",
42+
"Wire reflexion claim ingest for the compiler, formal/proof, and benchmark sources",
43+
"Advance the Rust to WASM production compiler beyond AST scaffolding",
44+
"Add Idris2 ABI definitions and the Zig FFI layer",
5645
]
5746

5847
[maintenance-status]
59-
last-run-utc = "2026-03-14T00:00:00Z"
60-
last-result = "unknown" # unknown | pass | warn | fail
48+
last-run-utc = "2026-06-18T00:00:00Z"
49+
last-result = "warn" # unknown | pass | warn | fail (reflexion suite green; pre-existing failures remain)

‎.machine_readable/contractiles/Trustfile.a2ml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Current trust level: maximal
5454

5555
#### license-content
5656
- description: LICENSE contains expected identifier
57-
- run: grep -q 'PMPL\|MPL\|MIT\|Apache\|LGPL' LICENSE
57+
- run: grep -q 'MPL\|MIT\|Apache\|LGPL\|CC-BY-SA' LICENSE
5858
- severity: warning
5959

6060
## Template-Specific Trust

‎0-AI-MANIFEST.a2ml‎

Lines changed: 33 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@ This is the AI manifest for **phronesis**. It declares:
1111

1212
## CANONICAL LOCATIONS (UNIVERSAL RULE)
1313

14-
### Machine-Readable Metadata: `.machine_readable/` ONLY
14+
### Machine-Readable Metadata: `.machine_readable/6a2/` ONLY
1515

16-
These 6 SCM files MUST exist in `.machine_readable/` directory ONLY:
17-
1. **STATE.scm** - Project state, progress, blockers
18-
2. **META.scm** - Architecture decisions, governance
19-
3. **ECOSYSTEM.scm** - Position in ecosystem, relationships
20-
4. **AGENTIC.scm** - AI agent interaction patterns
21-
5. **NEUROSYM.scm** - Neurosymbolic integration config
22-
6. **PLAYBOOK.scm** - Operational runbook
16+
These 6 A2ML files MUST exist in the `.machine_readable/6a2/` directory ONLY:
17+
1. **STATE.a2ml** - Project state, progress, blockers
18+
2. **META.a2ml** - Architecture decisions, governance
19+
3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
20+
4. **AGENTIC.a2ml** - AI agent interaction patterns
21+
5. **NEUROSYM.a2ml** - Neurosymbolic integration config
22+
6. **PLAYBOOK.a2ml** - Operational runbook
2323

2424
**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.
2525

@@ -40,9 +40,9 @@ Bot-specific instructions for:
4040

4141
## CORE INVARIANTS
4242

43-
1. **No SCM duplication** - Root must NOT contain STATE.scm, META.scm, etc.
44-
2. **Single source of truth** - `.machine_readable/` is authoritative
45-
3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
43+
1. **No metadata duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc.
44+
2. **Single source of truth** - `.machine_readable/6a2/` is authoritative
45+
3. **No stale metadata** - If root metadata files exist, they are OUT OF DATE
4646
4. **License consistency** - All code MPL-2.0 unless platform requires MPL-2.0
4747
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
4848

@@ -55,16 +55,21 @@ This repo contains:
5555
```
5656
phronesis/
5757
├── 0-AI-MANIFEST.a2ml # THIS FILE (start here)
58-
├── README.md # Project overview
59-
├── [your source files] # Main code
60-
├── .machine_readable/ # SCM files (6 files)
61-
│ ├── STATE.scm
62-
│ ├── META.scm
63-
│ ├── ECOSYSTEM.scm
64-
│ ├── AGENTIC.scm
65-
│ ├── NEUROSYM.scm
66-
│ └── PLAYBOOK.scm
67-
└── .bot_directives/ # Bot instructions
58+
├── README.adoc # Project overview
59+
├── lib/phronesis/ # Reference implementation (Elixir/BEAM)
60+
├── compiler/ # Rust → WASM compiler
61+
├── spec/ formal/ academic/ # Grammar, semantics, proofs
62+
├── docs/ # AsciiDoc design docs (incl. REFLEXION.adoc)
63+
├── .machine_readable/
64+
│ ├── 6a2/ # The 6 core A2ML files
65+
│ │ ├── STATE.a2ml
66+
│ │ ├── META.a2ml
67+
│ │ ├── ECOSYSTEM.a2ml
68+
│ │ ├── AGENTIC.a2ml
69+
│ │ ├── NEUROSYM.a2ml
70+
│ │ └── PLAYBOOK.a2ml
71+
│ └── contractiles/ # Mustfile / Trustfile / Justfile / etc.
72+
└── .github/workflows/ # CI/CD
6873
```
6974

7075
## SESSION STARTUP CHECKLIST
@@ -73,8 +78,8 @@ phronesis/
7378
✅ Understand canonical locations (.machine_readable/, .bot_directives/)
7479
✅ Know the invariants (no SCM duplication, etc.)
7580
✅ Check for MCP enforcement (if applicable)
76-
✅ Read `.machine_readable/STATE.scm` for current status
77-
✅ Read `.machine_readable/AGENTIC.scm` for interaction patterns
81+
✅ Read `.machine_readable/6a2/STATE.a2ml` for current status
82+
✅ Read `.machine_readable/6a2/AGENTIC.a2ml` for interaction patterns
7883

7984
## LIFECYCLE HOOKS
8085

@@ -86,15 +91,15 @@ When starting a new session:
8691
2. Log session start (optional but recommended)
8792
- Format: `[YYYY-MM-DD HH:MM:SS] Session started: [agent-name]`
8893
- Location: `.machine_readable/session-log.txt`
89-
3. Read `.machine_readable/STATE.scm`
94+
3. Read `.machine_readable/6a2/STATE.a2ml`
9095
4. Check for blockers
9196
5. State understanding of canonical locations
9297

9398
### on-exit (Session End)
9499

95100
When ending a session:
96101

97-
1. Update `.machine_readable/STATE.scm` if changes made
102+
1. Update `.machine_readable/6a2/STATE.a2ml` if changes made
98103
2. Log session end (optional but recommended)
99104
- Format: `[YYYY-MM-DD HH:MM:SS] Session ended: [summary]`
100105
- Location: `.machine_readable/session-log.txt`
@@ -105,13 +110,13 @@ When ending a session:
105110

106111
After reading this file, demonstrate understanding by stating:
107112

108-
**"I have read the AI manifest. SCM files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files in the root directory."**
113+
**"I have read the AI manifest. The 6 core A2ML files are located in `.machine_readable/6a2/` ONLY, and I will not create duplicate metadata files in the root directory."**
109114

110115
## META
111116

112117
- **Format Version:** 1.0.0
113-
- **Created:** [DATE]
114-
- **Maintained By:** [YOUR-NAME/ORG]
118+
- **Created:** 2026
119+
- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath)
115120
- **License:** MPL-2.0
116121
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol
117122

0 commit comments

Comments
 (0)