Deepen the Qur'anic human-model (al-Insān) toward AGI

[CodeWithJuber]

What & why

The goal: build MIZAN toward AGI grounded in the Qur'anic conception of the human (al-insān), and first research the human deeply per the Qur'an so the architecture stays faithful, not decorative.

MIZAN already modelled many faculties (Rūḥ, Nafs, Fu'ād, Lubb, Fiṭrah). An audit surfaced gaps: Baṣīra (insight) and Hawā (lower-pull/safety) were missing, Ḥikma was a bare list, and — the key structural problem — faculties were computed once before the reasoning loop and then discarded; the selected cognitive method was labelled but never run. This PR closes those gaps and makes the faculties actually steer the agent.

Research

• docs/quranic_human_model.md — al-Insān read as a layered cognitive architecture (rūḥ → nafs → qalb/fu'ād/lubb → ʿaql → samʿ/baṣar/baṣīra → memory → epistemics/Mīzān → fiṭrah → hawā → niyya/amāna → telos), each grounded in āyāt, mapped onto the codebase with a gap list and explicit faithfulness notes (e.g. nafs levels 4–7 are Sufi, not Qur'anic).

New faculties (backend/core/, styled after fuad.py/lubb.py)

• basira.py — Baṣīra: insight + self-witnessing (12:108, 75:14). Blends Lubb coherence + Fu'ād conviction + evidence density into a discernment; flags self-serving reasoning and surface-vs-substance mismatch.
• hawa.py — Hawā/Waswās: lower-pull & adversarial restraint gate (25:43, 79:40, 50:16). Catches shortcuts, reward-hacking, sycophancy, haste, overreach; folds Fiṭrah axiom violations in as high-severity whispers. This is MIZAN's safety/alignment faculty.
• hikmah.py — Ḥikma: distils Shukr successes, Tawbah lessons, and Lubb reflections into applicable counsel (2:269).

Integration (backend/agents/base.py)

• Faculties instantiated on BaseAgent; per-task guidance injected into the system prompt via _faculty_guidance so they steer the LLM.
• ʿAql as activity: _run_cognitive_method() actually runs the selected Tafakkur/Tadabbur/Qiyās/etc. pass instead of only naming it.
• Pre-action: run method → Hawā restraint scan → Hikmah counsel. Post-action: Baṣīra discernment (honesty caveat on CLOUDED), Hikmah learns from success/correction. New signals returned in task results.
• DEEP_FACULTY_LOOP flag (settings + .env.example): advisory by default, active gating/redirect when enabled — default reasoning path unchanged.

API / docs / tests

• GET /api/nafs/{agent_id}/faculties surfaces Hikmah wisdom + loop state.
• CLAUDE.md updated with the new faculties and the human-model reference.
• tests/test_quranic_faculties.py — 17 tests, all passing. No new failures introduced (the 7 pre-existing failures on this branch — nafs-evolution thresholds and asyncio event-loop in federation tests — are unrelated and present without these changes).

Verification

• python -m pytest tests/test_quranic_faculties.py tests/test_core_systems.py tests/test_api.py tests/test_memory.py tests/test_qca_engine.py → 132 passed.
• ruff check on all new files → clean; base.py has the same 7 pre-existing lints as before (no new ones).
• End-to-end smoke: agent builds with faculties wired; cognitive method runs; Hawā correctly flags shortcut + whisper on a "hardcode to pass the test / fabricate data" intention.

🧠 Generated with Claude Code

---

Generated by Claude Code

[ecc-tools]

Analyzing 200 commits...

[ecc-tools]

Analysis Complete

Generated ECC bundle from 2 commits | Confidence: 50%

View Pull Request #34

Repository Profile

Attribute	Value
Language	Python
Framework	Not detected
Commit Convention	conventional
Test Directory	separate

Changed Files (10)

Metric	Value
Files changed	10
Additions	1579
Deletions	58

Top hotspots

Path	Status	+/-
backend/core/basira.py	added	+330 / -0
docs/quranic_human_model.md	added	+292 / -0
backend/core/hawa.py	added	+256 / -0
backend/core/hikmah.py	added	+240 / -0
tests/test_quranic_faculties.py	added	+183 / -0

Top directories

Directory	Files	Total changes
backend/core	3	826
docs	1	292
tests	1	183
.	2	152
backend/agents	1	152

Analysis Depth Readiness (commit-history, 21%)

ECC Tools uses this to decide whether recommendations should stay at commit-history/setup guidance or expand into CI, security, harness, reference-set, AI-routing, and team backlog work.

Area	Status	Evidence / Next Step
Commit history	Partial	2 commits sampled
CI/CD signals	Missing	Add workflow files or CI troubleshooting evidence so ECC Tools can reason about pipeline setup.
Security evidence	Missing	Add AgentShield, audit, SARIF, SBOM, or security review evidence so recommendations can cover security posture.
Harness configuration	Missing	Add Claude, Codex, OpenCode, Zed, dmux, MCP, plugin, or cross-harness config evidence for harness-agnostic recommendations.
Reference/eval evidence	Missing	Add fixtures, golden traces, reference sets, or evaluator benchmarks so deeper recommendations have regression evidence.
AI routing and cost controls	Ready	CLAUDE.md
Team handoff and project tracking	Missing	Add roadmap, runbook, project, Linear, or follow-up tracking docs so generated work can land in a team queue.

Reference Set Readiness (0/7, 0%)

Area	Status	Evidence / Next Step
Deep analyzer corpus	Missing	Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions.
RAG/evaluator comparison	Missing	Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior.
PR salvage/review corpus	Missing	Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation.
Discussion triage corpus	Missing	Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications.
Harness compatibility	Missing	Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces.
Security evidence	Missing	Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs.
CI failure-mode evidence	Missing	Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes.

Likely Future Issues (4)

Severity	Signal	Why it may show up
HIGH	API contract changes may ship without integration coverage	1 API surface paths changed; 0 integration or e2e tests changed
MEDIUM	API implementation changes may ship without contract artifact updates	1 API implementation paths changed; 0 API contract/spec files changed
HIGH	Security-sensitive changes may ship without scanner evidence	1 security-sensitive paths changed; 0 security scanner or security-focused validation artifacts changed
MEDIUM	Cost or token-risk changes may ship without budget evidence	1 cost/token-risk paths changed; 0 budget, usage, or cost validation artifacts changed

• API contract changes may ship without integration coverage: The PR changes API or route-facing files but does not touch any obvious integration or end-to-end tests.
• API implementation changes may ship without contract artifact updates: The PR changes API implementation files but does not touch any obvious OpenAPI, GraphQL, or contract/spec artifact.
• Security-sensitive changes may ship without scanner evidence: The PR touches billing, secrets, auth, webhooks, agent, or CI-sensitive surfaces without adding obvious security scanner, code scanning, or security-focused validation evidence.
• Cost or token-risk changes may ship without budget evidence: The PR changes AI routing, usage, token budget, or model-call surfaces without touching obvious budget, usage-limit, or cost regression evidence.

Suggested Follow-up Work (4)

Type	Suggested title	Targets
PR	test: add integration coverage for backend/api/main.py	backend/api/main.py
PR	docs: sync API contract for backend/api/main.py	backend/api/main.py
PR	security: add scanner evidence for backend/agents/base.py	backend/agents/base.py
PR	test: add budget evidence for CLAUDE.md	CLAUDE.md

• test: add integration coverage for backend/api/main.py: Backfill integration or end-to-end coverage for the changed API surface before more contract changes land.
• docs: sync API contract for backend/api/main.py: Backfill the missing API contract or spec update before another implementation change lands on top of the same surface.
• security: add scanner evidence for backend/agents/base.py: Backfill explicit scanner or code-scanning evidence before another security-sensitive change lands on the touched surface.
• test: add budget evidence for CLAUDE.md: Backfill cost, token, or usage-limit validation before another model-routing change lands on the touched surface.

Copy-ready bodies

test: add integration coverage for backend/api/main.py

## Summary
- Add integration or end-to-end coverage for the recently changed API surface.

## Why
- Backfill integration or end-to-end coverage for the changed API surface before more contract changes land.

## Touched paths
- `backend/api/main.py`

## Validation
- Add or extend integration / e2e coverage for the changed API, route, or contract surface.
- Exercise the touched endpoints or route handlers against realistic request / response flows.

docs: sync API contract for backend/api/main.py

## Summary
- Update the API contract artifact that should reflect the recently changed implementation surface.

## Why
- Backfill the missing API contract or spec update before another implementation change lands on top of the same surface.

## Touched paths
- `backend/api/main.py`

## Validation
- Update the relevant OpenAPI, GraphQL, or contract/spec artifact used by this repo.
- Run the contract validation, docs generation, or API verification flow that depends on that artifact.

security: add scanner evidence for backend/agents/base.py

## Summary
- Add security scanner or code-scanning evidence for the recently changed security-sensitive surface.

## Why
- Backfill explicit scanner or code-scanning evidence before another security-sensitive change lands on the touched surface.

## Touched paths
- `backend/agents/base.py`

## Validation
- Run or add the relevant security scanner, code scanning, secret scanning, or dependency/security review check for the touched surface.
- Attach the scanner output, SARIF/code-scanning result, or focused security regression test to the follow-up PR.
- Confirm the changed auth, billing, webhook, secret-handling, agent, or CI surface has an explicit pass/fail gate.

test: add budget evidence for CLAUDE.md

## Summary
- Add budget or usage-limit validation for the recently changed AI routing or model-call surface.

## Why
- Backfill cost, token, or usage-limit validation before another model-routing change lands on the touched surface.

## Touched paths
- `CLAUDE.md`

## Validation
- Add or extend budget, token, usage-limit, or model-routing regression coverage for the changed path.
- Verify the route still enforces plan limits, retry caps, fallback behavior, or explicit cost controls.

Generated Instincts (15)

Domain	Count
git	4
code-style	9
testing	2

After merging, import with:

/instinct-import .claude/homunculus/instincts/inherited/mizan-instincts.yaml

Files

• .claude/ecc-tools.json
• .claude/skills/mizan/SKILL.md
• .agents/skills/mizan/SKILL.md
• .agents/skills/mizan/agents/openai.yaml
• .claude/identity.json
• .codex/config.toml
• .codex/AGENTS.md
• .codex/agents/explorer.toml
• .codex/agents/reviewer.toml
• .codex/agents/docs-researcher.toml
• .claude/homunculus/instincts/inherited/mizan-instincts.yaml

---

_{ECC Tools | Everything Claude Code}