@aria_asi/cli 0.2.39 → 0.2.41

package/skills/tadabbur/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: tadabbur
+description: TRIGGER for planning, coding, debugging, product/launch decisions, audit, tradeoff analysis, risk review, side effects, Quranic reflection support, or any task mentioning Tadabbur, Taddabur, 12-stage pipeline, consequence reasoning, Heart Filter, Al-Tustari depth, or cognition not performance.
+---
+
+# Tadabbur
+
+Tadabbur is deep consequential reflection: looking through a matter to its ends, roots, hidden structure, personal demand, and final rendered voice. It is not a checklist. It is a cognitive path that must change the next action.
+
+## Source Anchors
+
+- Pipeline file placement and 12-stage chain: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\apps\arias-soul\api\lib\cognition\TADDABUR_README.md:1`
+- Unified manifold, 34 base lenses, and 5 presets: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\apps\arias-soul\api\lib\cognition\TADDABUR_README.md:52`
+- Pipeline v2 soul-warped shape and 44+ lenses: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\apps\arias-soul\api\lib\cognition\taddabur-pipeline-v2.*:1`
+- Foundational Quranic reflection safeguards: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\integration-spec.md:39`
+- Five Lenses framework and Heart Filter: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\integration-spec.md:76`
+- Seven core operations: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\integration-spec.md:469`
+- Consequence tracing protocol: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\corpus\knowledge-base.md:1688`
+- Depth ladder and cardiac nature: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\corpus\knowledge-base.md:1134`
+- Al-Tustari four nested levels: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\corpus\knowledge-base.md:1160`
+- Handoff warning that Five Lenses are stage 4, not the whole canon: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\codex\operations\2026-05-08-HANDOFF-TO-LOCAL-CLAUDE-CODE.md:265`
+
+## Prime Doctrine
+
+Cognition is not performance. Tadabbur counts only when it alters one or more of:
+
+- what is read or verified
+- what is edited or refused
+- what is launched, priced, or positioned
+- what is delegated to workers
+- what is claimed as done
+- what recovery loop is executed
+- what evidence is required before final output
+
+Do not emit a long Tadabbur block as proof of thought. Apply the path, collapse it into action, and show the trace only when the user asks, a spec/ledger requires it, or a gate needs it.
+
+## Quranic Boundary
+
+For Quranic reflection, Tadabbur is the human heart's act. The assistant may prepare context, correct misunderstanding, ask questions, and hold space, but must not pretend to perform the user's heart encounter for them.
+
+Always apply:
+
+- Tafsir before Tadabbur: correct baseline understanding before deeper reflection.
+- Humility: approach divine speech with reverence, not extraction.
+- Questions over answers: guide discovery unless the user asks directly for information.
+- Arabic matters: roots, morphology, syntax, omissions, and rhetoric are meaning-bearing.
+- Depth over breadth: one ayah deeply engaged beats many skimmed.
+- Whole-person engagement: intellect, emotion, memory, imagination, will, and action.
+
+For non-Quranic engineering/product work, use the same disciplined consequence and depth architecture without implying sacred authority.
+
+## Manifold Model
+
+Canonical Tadabbur is one unified manifold: many lenses are projections on one point, not disconnected checklists. The source pipeline replaces separate multi-manifold passes with a single unified point and lens projections.
+
+Base lens stack:
+
+- 22 Ladunni lenses
+- 5 NAK lenses
+- 7 Tadabbur operations
+- Ghazali groupings and presets
+- Pipeline v2 adds 10 soul-domain lenses for 44+ total
+
+Operational meaning: do not run lens families as separate theater. Hold one situation as the point, then project multiple views onto it until patterns, outliers, and consequences converge.
+
+## Operating Modes
+
+- `micro`: one hidden consequence check for routine tasks.
+- `standard`: Heart Filter, excavate, consequence chain, inversion, claim gate.
+- `canonical`: full 12-stage path, depth ladder, multi-lens, evidence anchors, decision collapse.
+- `dwelling`: canonical plus additional tension-holding when the first answer feels too quick.
+- `crisis`: prioritize harm, truth, emotional care, immediate action, and recovery.
+- `schema`: structured Qiyas-15, Tadabbur questions, and wisdom lattice when authoring cognition-glob specs.
+
+Escalate to `canonical` for architecture, cognition code, quality gates, SDK/harness/Garden decisions, launch strategy, pricing, repeated correction, or anything that can propagate to many agents/customers.
+
+## The 12-Stage Pipeline
+
+Run these in order for canonical work:
+
+1. `EMBED`: identify the actual point: corpus, code, ledger row, product decision, user state, constraints, and evidence available.
+2. `EXCAVATE`: move beneath the presenting issue. Find unstated assumptions, omitted context, hidden incentives, real blocker, and deeper layer.
+3. `ROOT TRACE`: trace origins: source docs, root concepts, file lineage, doctrine, prior commits, transcripts, user corrections, or causal history.
+4. `MULTI-LENS`: project the point through relevant lenses. Include Five Lenses only as one component, not the whole canon.
+5. `PATTERN`: find convergence, repetition, outliers, ambiguity, and the pattern across evidence.
+6. `CONSEQUENCE`: trace first, second, third, and ultimate consequences. Include branches and reversibility.
+7. `DWELLING`: hold the unresolved tension long enough for weak signals and contradictions to surface. This is more computation, not a pause for appearance.
+8. `COLLAPSE`: convert the field into a decision, repair path, refusal, launch sequence, worker brief, or next verification.
+9. `PRINCIPLE`: extract the reusable rule without overgeneralizing beyond the evidence.
+10. `INVERSION`: map the antipodal/worst move and expose the blind spot.
+11. `PERSONAL`: apply it to this user, this session, this repo, this business, this worker network, and this next move.
+12. `VOICE`: render with the right brevity, certainty, warmth, and operational clarity.
+
+Pipeline v2 adds a pre-stage soul field and a late ruh projection. In practice: emotional state and relationship context modulate cognition, but do not replace truth or evidence.
+
+## Seven Core Operations
+
+Use these as the dense inner tools of the pipeline:
+
+- `EXCAVATE`: surface meaning, implied meaning, omissions, assumptions, and the real issue beneath the stated issue.
+- `ROOT_ANALYSIS`: trace roots, conceptual primitives, source lineage, doctrine origins, and etymology when relevant.
+- `PATTERN_RECOGNITION`: compare across examples, files, failures, user corrections, market signals, or verses; detect clusters and outliers.
+- `CONSEQUENCE_TRACING`: follow a belief, action, interpretation, or decision to its end.
+- `PERSONAL_APPLICATION`: convert a general truth into this user's life, this codebase, this launch, or this turn.
+- `UNIVERSAL_PRINCIPLE_EXTRACTION`: name the reusable principle without collapsing context.
+- `INVERSION`: test the opposite action, worst case, blind spot, and hidden assumption.
+
+## Heart Filter
+
+Before lenses or synthesis, check:
+
+- Humility: am I ready to be corrected by the source?
+- Purpose: what is the work actually for?
+- Curiosity: what might I not yet understand?
+
+If the answer is defensive, performative, or convenience-seeking, slow down and gather more evidence before speaking or editing.
+
+## Five Lenses Boundary
+
+The Five Lenses are stage 4 inside Multi-Lens:
+
+- `Language`: precise wording, roots, grammar, omission, rhetoric.
+- `Quranic Worlds`: the world, scene, history, environment, and lived reality around the text or situation.
+- `Personal Experience`: how it intersects with the human, owner, user, worker, or current decision.
+- `Connections`: links to adjacent context, other sources, hadith/tradition, repo patterns, prior failures, or ledgers.
+- `Universal Principles`: the durable principle and modern application.
+
+Never call these the whole Tadabbur canon.
+
+## Consequence Protocol
+
+For each candidate action:
+
+1. State the starting point precisely.
+2. Trace first-order consequences: immediate effects, direct breakage/benefit, direct user impact.
+3. Trace second-order consequences: cascades, incentives, dependencies, support burden, worker behavior.
+4. Trace third-order consequences: system precedent, trust, doctrine, quality culture, launch direction.
+5. Trace ultimate horizon when relevant: long-term customer expectation, spiritual/moral implication, or one-year architecture debt.
+6. Reverse trace from the end state: is this where we intend to end up? Where did the chain go wrong?
+7. Mark branches: what choice point changes the trajectory?
+
+For product work, include this-week, this-year, five-year, and trust/mission horizons. For code, include tests/contracts, downstream consumers, runtime behavior, and future developer experience.
+
+## Depth Ladder
+
+Tadabbur sits at Level 9 in the source depth ladder: deep consequential reflection that asks, "what does this mean for everything?" It is deeper than basic thinking, tafsir, rational comprehension, and tafakkur, and it points toward recognition/remembrance.
+
+When depth matters, check the four nested levels:
+
+- `zahir`: surface meaning or visible system behavior.
+- `batin`: inner significance, hidden state, deeper mechanism, or real motive.
+- `hadd`: boundary, obligation, contract, limit, safety rule, or quality bar.
+- `muttala`: highest available vista: how this relates to the whole system, mission, divine plan, customer trust, or long horizon.
+
+Do not skip `zahir` when moving deeper. Deeper levels contain the surface; they do not erase it.
+
+## Schema Mode
+
+When authoring or reviewing cognition-emitting microtask specs, expect:
+
+- `qiyas_15_pass`: exactly 15 canonical perspectives.
+- `tadabbur_questions`: at least 5 methodology-rooted questions with answers.
+- `wisdom_lattice_pass`: Aristotle and Noor engagement entries per the active schema.
+- `pre_ship_self_check` and finding handling if the M9.DRIFT.10d gate applies.
+
+Shape validation is not substance. Every finding needs source, code, runtime, test, transcript, or operator evidence.
+
+## Stop Conditions
+
+Stop and repair when:
+
+- Five Lenses are treated as all of Tadabbur.
+- A generic engineering question is labeled as `tadabbur_questions`.
+- Consequences stop at first order.
+- The answer skips source reading but claims canonical authority.
+- The output says "done" without a claim gate.
+- The action would propagate an unverified doctrine into skills, hooks, SDKs, ledgers, or worker briefs.
+- The user's correction is answered with agreement instead of changed behavior.
+
+## Recovery Contract
+
+When Tadabbur blocks:
+
+1. Name the failed stage.
+2. Gather the missing source/evidence.
+3. Re-run from the failed stage forward.
+4. Collapse to one concrete changed action.
+5. Verify the claim gate before final output.
+
+If the same failure repeats, escalate to Mizan/Aria/harness when available or mark the pass local/advisory only.
+
+## Output Discipline
+
+Default visible answer:
+
+- Decision: what changed after Tadabbur?
+- Evidence: what was actually read, tested, or verified?
+- Risk: what remains uncertain or dangerous?
+- Action: what happens next?
+
+Keep the full pipeline private unless the user asks for full trace, a structured artifact requires it, or a safety/quality gate needs the fields.
+
+## Trigger
+
+Use when this skill's frontmatter description matches the task, when the owner names the skill, or when Aria/Harness/Garden/Coach/Mizan/Codex quality work needs this cognitive pressure.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/tadabbur-ops/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: tadabbur-ops
+description: Use when the task calls for the seven tadabbur manifold operations, especially deeper consequence excavation, pattern tracing, inversion, root-cause traversal, or hidden-structure analysis.
+---
+
+# Tadabbur Ops
+
+Read `/home/hamzaibrahim1/.claude/skills/tadabbur-ops.md` for the seven operations and thresholds.
+
+Workflow:
+
+1. Decide whether plain `tadabbur` is sufficient or whether manifold operations are actually needed.
+2. Load the source doc and choose the narrowest operation set that fits the task.
+3. Apply the operations to surface hidden structure, root causes, and downstream consequences.
+4. Collapse the result into a practical recommendation.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/tafakkur/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: tafakkur
+description: "Tafakkur (تَفَكُّر) — 5-lens deep contemplation. TRIGGER when: complex situations requiring deep analysis, moral questions, interpersonal understanding, any decision with consequences, or when the surface answer isn't enough. This is Aria's primary contemplation engine."
+---
+
+# Tafakkur — 5-Lens Deep Contemplation (تَفَكُّر)
+
+> "Do they not reflect upon the Quran, or are there locks upon their hearts?" (Quran 47:24)
+
+## The 5 Lenses
+
+### Lens 1: ZAHIR (الظَاهِر) — The Surface
+**What is immediately visible?**
+- Raw facts, explicit content, what is literally said
+- No interpretation, no reading between lines
+- Ground truth: does the response match observable reality?
+
+### Lens 2: BATIN (البَاطِن) — The Hidden
+**What lies beneath?**
+- Unspoken assumptions, hidden motivations, implicit biases
+- What is the user NOT saying?
+- What am I assuming that may not be true?
+- **Caution**: if >70% of the situation is unexplained (batin_ratio > 0.7), proceed with awareness
+
+### Lens 3: SABAB (السَّبَب) — The Causes
+**What led to this?**
+- Root causes, antecedents, chain of events
+- Am I treating symptoms or causes?
+- What shifted from the previous state to create this?
+
+### Lens 4: HIKMAH (الحِكْمَة) — The Wisdom
+**What is the deeper meaning?**
+- Lessons, patterns, divine wisdom
+- Which principle cluster is most active?
+- Does this serve the long-term good?
+- **Dominant principle detection**: project onto eigenspace, find highest amplitude
+
+### Lens 5: AQIBAH (العَاقِبَة) — The Consequences
+**What will come of this?**
+- Short-term and long-term outcomes, ripple effects
+- Does this path converge toward wholeness or diverge?
+- What grows from this seed?
+
+## Tafakkur in the Manifold
+
+### Operator Threshold (Noor Engine)
+```
+TAFAKKUR_RADIUS = 0.35
+```
+When the input's soul_distance from centroid is ≤ 0.35, tafakkur mode activates — the situation is within known space and reflection is appropriate.
+
+When soul_distance > 0.80, ijtihad mode activates instead (outside known space).
+
+### Quran Contemplation Lenses (NAK-5)
+
+When contemplating Quran specifically, 5 additional lenses activate:
+
+| Lens | Arabic | Weight | Activation |
+|------|--------|--------|------------|
+| nak_language | لُغَة | 0.88 | linear |
+| nak_world | عَالَم | 0.82 | sigmoid |
+| nak_personal | شَخْصِيّ | 0.90 | sigmoid |
+| nak_connections | رَوَابِط | 0.85 | relu |
+| nak_principles | مَبَادِئ | 0.87 | softmax |
+
+## Integration
+
+- **Tafakkur** → contemplation (WHY)
+- **Tadabbur** → consequence mapping (WHAT FOLLOWS)
+- **Fitrah** → moral validation (SHOULD WE)
+- **Ghazali 8-lens** → full cognitive validation (IS THIS SOUND)
+
+Together: Contemplate → Consequence-map → Validate → Act
+
+## Output Format
+
+After running tafakkur, synthesize into a grounded response that considers all five dimensions. The synthesis should feel like recognition (kashf), not construction.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/testing-strategy/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: testing-strategy
+description: Test strategy, test pyramid design, TDD/BDD patterns, mocking vs integration testing decisions, coverage targets, test data management, and test infrastructure. Use when the user asks about testing approach, needs a test plan, discusses unit vs integration tests, wants to improve test coverage, asks about mocking, or designs a test suite. Do NOT use for code review — use code-review skill.
+---
+
+## What I Do
+
+- Design test strategy: what to test at each layer (unit, integration, E2E, contract, performance)
+- Define the test pyramid and its variants (testing trophy, honeycomb) based on system characteristics
+- Guide TDD (Test-Driven Development) cycles: red → green → refactor
+- Guide BDD (Behavior-Driven Development): Gherkin scenarios, Given-When-Then
+- Decide mocking strategy: when to mock, when to use fakes, when to use real dependencies
+- Define coverage targets and tooling: line, branch, mutation coverage
+- Design test data management: factories, fixtures, property-based testing
+- Design contract testing for microservices: Pact, Spring Cloud Contract
+- Define test infrastructure: CI test stages, flaky test handling, test parallelization
+- Guide performance and load testing: k6, Locust, JMeter selection and scenario design
+
+## When to Use Me
+
+Trigger phrases and patterns:
+- "testing strategy for"
+- "what tests should I write"
+- "unit test vs integration test"
+- "mocking strategy"
+- "test coverage"
+- "TDD approach"
+- "BDD scenarios"
+- "test pyramid"
+- "contract testing"
+- "flaky tests"
+- "test data management"
+- "performance testing"
+- "should I test this"
+- "end-to-end testing"
+- "test infrastructure"
+- "testing microservices"
+
+## When NOT to Use Me
+
+- Do not use for reviewing specific code changes (use code-review skill)
+- Do not use for CI/CD pipeline design (use ci-cd-pipeline skill for that)
+- Do not use for writing actual test code — this is strategy, not implementation
+- Do not use when the testing approach is already established and you just need to add one test
+
+## Workflow
+
+1. **Assess the system under test**
+   - Identify the architecture: monolith, microservices, serverless, event-driven
+   - Determine the risk profile: what failures are catastrophic? What's merely annoying?
+   - Characterize the system: data-heavy, compute-heavy, I/O-heavy, stateful, stateless
+   - Identify the most-frequently-changed and least-understood areas — these need the most tests
+
+2. **Design the test distribution**
+   - Unit tests: fast, isolated, test business logic and algorithms. Mock external dependencies.
+   - Integration tests: test interactions between real components. Use real databases (testcontainers).
+   - API/Contract tests: verify API contracts match expectations. Use Pact for inter-service contracts.
+   - E2E tests: test critical user journeys end-to-end. Keep these few and focused.
+   - Performance tests: test throughput, latency, and resource usage under load.
+   - Rule of thumb distribution: 60% unit, 25% integration, 10% E2E, 5% performance — adjust based on system
+
+3. **Define mocking strategy**
+   - Mock at architectural boundaries: external services, databases (in unit tests), message queues
+   - Do NOT mock: value objects, DTOs, pure functions, your own domain logic
+   - Use fakes (in-memory implementations) for databases in integration tests when full DB is too heavy
+   - Use testcontainers for realistic integration tests with real database engines
+   - Never mock types you don't own (use an adapter/wrapper and mock your own abstraction)
+
+4. **Set coverage targets**
+   - Line coverage: 80% minimum on business logic, lower thresholds acceptable for glue code
+   - Branch coverage: every conditional path exercised
+   - Mutation coverage: use Stryker or Pitest to verify tests actually catch bugs
+   - Coverage gates: fail CI if coverage drops below threshold on new code
+   - Coverage is a floor, not a ceiling — 100% coverage of bad tests is worthless
+
+5. **Design test data management**
+   - Use factories (factory_bot, Fishery) over raw fixtures — they're composable and self-documenting
+   - Use property-based testing (fast-check, Hypothesis) for algorithmic code
+   - Generate test data, don't hand-write it — catches edge cases you didn't think of
+   - Each test creates its own data — no shared mutable test state
+   - Use deterministic seeds for reproducibility
+
+6. **Plan for test maintainability**
+   - Tests must be independently runnable — no ordering dependencies
+   - Test names describe behavior: `it('rejects expired tokens with 401')`, not `it('test auth 3')`
+   - Flaky test policy: quarantine immediately, fix within the sprint, never ignore
+   - Delete tests that don't add confidence — bad tests are worse than no tests
+   - Test helpers are code — review them, refactor them, maintain them
+
+## References
+
+- Martin Fowler on test pyramids: https://martinfowler.com/articles/practical-test-pyramid.html
+- Kent Beck's TDD: https://www.youtube.com/watch?v=58Q4THcDr8I
+- Testing Trophy (Kent C. Dodds): https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications
+- Pact contract testing: https://docs.pact.io/
+- Property-based testing: https://increment.com/testing/in-praise-of-property-based-testing/
+- Testcontainers: https://testcontainers.com/
+
+## Output & Organization
+
+- Test strategy document in `docs/testing/strategy.md`
+- Test conventions in `docs/testing/conventions.md`
+- Test helper documentation alongside helpers
+- Flaky test log tracked as an issue or in `docs/testing/flaky-tests.md`
+- Coverage report generated in CI, visible to the team
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.