@aria_asi/cli 0.2.40 → 0.2.41

package/skills/plugin-creator/scripts/create_basic_plugin.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""Scaffold a plugin directory and optionally update marketplace.json."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+MAX_PLUGIN_NAME_LENGTH = 64
+DEFAULT_PLUGIN_PARENT = Path.cwd() / "plugins"
+DEFAULT_MARKETPLACE_PATH = Path.cwd() / ".agents" / "plugins" / "marketplace.json"
+DEFAULT_INSTALL_POLICY = "AVAILABLE"
+DEFAULT_AUTH_POLICY = "ON_INSTALL"
+DEFAULT_CATEGORY = "Productivity"
+DEFAULT_MARKETPLACE_DISPLAY_NAME = "[TODO: Marketplace Display Name]"
+VALID_INSTALL_POLICIES = {"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}
+VALID_AUTH_POLICIES = {"ON_INSTALL", "ON_USE"}
+
+
+def normalize_plugin_name(plugin_name: str) -> str:
+    """Normalize a plugin name to lowercase hyphen-case."""
+    normalized = plugin_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def validate_plugin_name(plugin_name: str) -> None:
+    if not plugin_name:
+        raise ValueError("Plugin name must include at least one letter or digit.")
+    if len(plugin_name) > MAX_PLUGIN_NAME_LENGTH:
+        raise ValueError(
+            f"Plugin name '{plugin_name}' is too long ({len(plugin_name)} characters). "
+            f"Maximum is {MAX_PLUGIN_NAME_LENGTH} characters."
+        )
+
+
+def build_plugin_json(plugin_name: str) -> dict:
+    return {
+        "name": plugin_name,
+        "version": "[TODO: 1.2.0]",
+        "description": "[TODO: Brief plugin description]",
+        "author": {
+            "name": "[TODO: Author Name]",
+            "email": "[TODO: author@example.com]",
+            "url": "[TODO: https://github.com/author]",
+        },
+        "homepage": "[TODO: https://docs.example.com/plugin]",
+        "repository": "[TODO: https://github.com/author/plugin]",
+        "license": "[TODO: MIT]",
+        "keywords": ["[TODO: keyword1]", "[TODO: keyword2]"],
+        "skills": "[TODO: ./skills/]",
+        "hooks": "[TODO: ./hooks.json]",
+        "mcpServers": "[TODO: ./.mcp.json]",
+        "apps": "[TODO: ./.app.json]",
+        "interface": {
+            "displayName": "[TODO: Plugin Display Name]",
+            "shortDescription": "[TODO: Short description for subtitle]",
+            "longDescription": "[TODO: Long description for details page]",
+            "developerName": "[TODO: OpenAI]",
+            "category": "[TODO: Productivity]",
+            "capabilities": ["[TODO: Interactive]", "[TODO: Write]"],
+            "websiteURL": "[TODO: https://openai.com/]",
+            "privacyPolicyURL": "[TODO: https://openai.com/policies/row-privacy-policy/]",
+            "termsOfServiceURL": "[TODO: https://openai.com/policies/row-terms-of-use/]",
+            "defaultPrompt": [
+                "[TODO: Summarize my inbox and draft replies for me.]",
+                "[TODO: Find open bugs and turn them into tickets.]",
+                "[TODO: Review today's meetings and flag gaps.]",
+            ],
+            "brandColor": "[TODO: #3B82F6]",
+            "composerIcon": "[TODO: ./assets/icon.png]",
+            "logo": "[TODO: ./assets/logo.png]",
+            "screenshots": [
+                "[TODO: ./assets/screenshot1.png]",
+                "[TODO: ./assets/screenshot2.png]",
+                "[TODO: ./assets/screenshot3.png]",
+            ],
+        },
+    }
+
+
+def build_marketplace_entry(
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+) -> dict[str, Any]:
+    return {
+        "name": plugin_name,
+        "source": {
+            "source": "local",
+            "path": f"./plugins/{plugin_name}",
+        },
+        "policy": {
+            "installation": install_policy,
+            "authentication": auth_policy,
+        },
+        "category": category,
+    }
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    with path.open() as handle:
+        return json.load(handle)
+
+
+def build_default_marketplace() -> dict[str, Any]:
+    return {
+        "name": "[TODO: marketplace-name]",
+        "interface": {
+            "displayName": DEFAULT_MARKETPLACE_DISPLAY_NAME,
+        },
+        "plugins": [],
+    }
+
+
+def validate_marketplace_interface(payload: dict[str, Any]) -> None:
+    interface = payload.get("interface")
+    if interface is not None and not isinstance(interface, dict):
+        raise ValueError("marketplace.json field 'interface' must be an object.")
+
+
+def update_marketplace_json(
+    marketplace_path: Path,
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+    force: bool,
+) -> None:
+    if marketplace_path.exists():
+        payload = load_json(marketplace_path)
+    else:
+        payload = build_default_marketplace()
+
+    if not isinstance(payload, dict):
+        raise ValueError(f"{marketplace_path} must contain a JSON object.")
+
+    validate_marketplace_interface(payload)
+
+    plugins = payload.setdefault("plugins", [])
+    if not isinstance(plugins, list):
+        raise ValueError(f"{marketplace_path} field 'plugins' must be an array.")
+
+    new_entry = build_marketplace_entry(plugin_name, install_policy, auth_policy, category)
+
+    for index, entry in enumerate(plugins):
+        if isinstance(entry, dict) and entry.get("name") == plugin_name:
+            if not force:
+                raise FileExistsError(
+                    f"Marketplace entry '{plugin_name}' already exists in {marketplace_path}. "
+                    "Use --force to overwrite that entry."
+                )
+            plugins[index] = new_entry
+            break
+    else:
+        plugins.append(new_entry)
+
+    write_json(marketplace_path, payload, force=True)
+
+
+def write_json(path: Path, data: dict, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists. Use --force to overwrite.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+
+def create_stub_file(path: Path, payload: dict, force: bool) -> None:
+    if path.exists() and not force:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(payload, handle, indent=2)
+        handle.write("\n")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a plugin skeleton with placeholder plugin.json."
+    )
+    parser.add_argument("plugin_name")
+    parser.add_argument(
+        "--path",
+        default=str(DEFAULT_PLUGIN_PARENT),
+        help=(
+            "Parent directory for plugin creation (defaults to <cwd>/plugins). "
+            "When using a home-rooted marketplace, use <home>/plugins."
+        ),
+    )
+    parser.add_argument("--with-skills", action="store_true", help="Create skills/ directory")
+    parser.add_argument("--with-hooks", action="store_true", help="Create hooks/ directory")
+    parser.add_argument("--with-scripts", action="store_true", help="Create scripts/ directory")
+    parser.add_argument("--with-assets", action="store_true", help="Create assets/ directory")
+    parser.add_argument("--with-mcp", action="store_true", help="Create .mcp.json placeholder")
+    parser.add_argument("--with-apps", action="store_true", help="Create .app.json placeholder")
+    parser.add_argument(
+        "--with-marketplace",
+        action="store_true",
+        help=(
+            "Create or update <cwd>/.agents/plugins/marketplace.json. "
+            "Marketplace entries always point to ./plugins/<plugin-name> relative to the "
+            "marketplace root."
+        ),
+    )
+    parser.add_argument(
+        "--marketplace-path",
+        default=str(DEFAULT_MARKETPLACE_PATH),
+        help=(
+            "Path to marketplace.json (defaults to <cwd>/.agents/plugins/marketplace.json). "
+            "For a home-rooted marketplace, use <home>/.agents/plugins/marketplace.json."
+        ),
+    )
+    parser.add_argument(
+        "--install-policy",
+        default=DEFAULT_INSTALL_POLICY,
+        choices=sorted(VALID_INSTALL_POLICIES),
+        help="Marketplace policy.installation value",
+    )
+    parser.add_argument(
+        "--auth-policy",
+        default=DEFAULT_AUTH_POLICY,
+        choices=sorted(VALID_AUTH_POLICIES),
+        help="Marketplace policy.authentication value",
+    )
+    parser.add_argument(
+        "--category",
+        default=DEFAULT_CATEGORY,
+        help="Marketplace category value",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    raw_plugin_name = args.plugin_name
+    plugin_name = normalize_plugin_name(raw_plugin_name)
+    if plugin_name != raw_plugin_name:
+        print(f"Note: Normalized plugin name from '{raw_plugin_name}' to '{plugin_name}'.")
+    validate_plugin_name(plugin_name)
+
+    plugin_root = (Path(args.path).expanduser().resolve() / plugin_name)
+    plugin_root.mkdir(parents=True, exist_ok=True)
+
+    plugin_json_path = plugin_root / ".codex-plugin" / "plugin.json"
+    write_json(plugin_json_path, build_plugin_json(plugin_name), args.force)
+
+    optional_directories = {
+        "skills": args.with_skills,
+        "hooks": args.with_hooks,
+        "scripts": args.with_scripts,
+        "assets": args.with_assets,
+    }
+    for folder, enabled in optional_directories.items():
+        if enabled:
+            (plugin_root / folder).mkdir(parents=True, exist_ok=True)
+
+    if args.with_mcp:
+        create_stub_file(
+            plugin_root / ".mcp.json",
+            {"mcpServers": {}},
+            args.force,
+        )
+
+    if args.with_apps:
+        create_stub_file(
+            plugin_root / ".app.json",
+            {
+                "apps": {},
+            },
+            args.force,
+        )
+
+    if args.with_marketplace:
+        marketplace_path = Path(args.marketplace_path).expanduser().resolve()
+        update_marketplace_json(
+            marketplace_path,
+            plugin_name,
+            args.install_policy,
+            args.auth_policy,
+            args.category,
+            args.force,
+        )
+
+    print(f"Created plugin scaffold: {plugin_root}")
+    print(f"plugin manifest: {plugin_json_path}")
+    if args.with_marketplace:
+        print(f"marketplace manifest: {marketplace_path}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/predictor/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: predictor
+description: Use when a plan, change, or output should be stress-tested against the next real operational step before release.
+---
+
+# Predictor
+
+Use this to ask whether the current approach will survive contact with the next actual step.
+
+## Trigger
+
+- before commit, push, deploy, or release
+- before accepting generated code
+- when a runtime or client integration seems “good enough”
+
+## Workflow
+
+1. Name the next real step.
+2. Predict the most likely failure mode.
+3. Tighten the artifact now instead of after it breaks.
+4. Feed the prediction into post-Mizan quality review.
+
+## Guardrail
+
+Prediction is for preventing breakage, not for inventing facts.
+
+## 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/qiyas-analogy/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: qiyas-analogy
+description: Use when structural analogy can improve architecture, implementation, debugging, product strategy, audit, or launch decisions without guessing; includes the canonical Qiyas-15 perspective pass.
+---
+
+# Qiyas Analogy
+
+Qiyas is not "this seems similar." It is disciplined transfer from a proven source case to a new case by a shared effective cause. When this skill fires, use analogy as cognition: it should change what you inspect, what you transfer, what you reject, and what you verify.
+
+## Source Anchors
+
+- Islamic corpus Qiyas method: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\islamic-corpus-complete.md:2865`
+- Four pillars and `illah` vs `hikmah`: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\islamic-corpus-complete.md:2878`
+- Qiyas types and madhhab caution: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\islamic-corpus-complete.md:2992`
+- Furuq false-analogy corrective: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\islamic-corpus-complete.md:6259`
+- Underlying reality over verbal resemblance: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\apps\arias-soul\corpus\islamic-corpus-complete.md:6361`
+- Qiyas-15 schema enum: `C:\Users\hibra\OneDrive\Documents\Claude\Projects\Ledger Aria\codex-mirror\apps\arias-soul\microtask-specs\_schema.json:163`
+- M9.DRIFT.10d handling and redo requirements: `C:\Users\hibra\OneDrive\Documents\New project\aria-critical-corpus-spark-11b3\codex\operations\SESSION_HANDOFF_2026-05-07_M9_DRIFT_10_SUBSTANCE_GATE.md:90`
+
+## Auto-Trigger
+
+Use this skill when any of these are present:
+
+- The user says Qiyas, analogy, similar pattern, precedent, exemplar, transfer, compare, or fifteen angles.
+- A design, SDK, harness, Garden, Aria, Claude Code, OpenCode, skill, hook, QA gate, launch, or pricing decision is being mapped from an existing pattern.
+- A bug appears in a new surface after being fixed elsewhere.
+- A repo pattern is tempting to copy into another module.
+- A product positioning claim depends on analogy to another market, tool, launch, or buyer behavior.
+- A plan needs the canonical `qiyas_15_pass` substance gate.
+
+## Prime Doctrine
+
+Qiyas must be applied before the conclusion. Do not write an answer and then decorate it with analogy. If the analogy changes nothing about evidence gathering, transfer scope, rejection of a tempting pattern, or verification, the skill did not fire.
+
+Analogy is subordinate to source truth, runtime truth, repo truth, user instruction, and Mizan. If direct evidence disagrees with analogy, the analogy loses.
+
+## Four-Pillar Qiyas
+
+Every serious Qiyas pass must name the four pillars:
+
+- `asl`: the original/source case whose decision, pattern, or contract is already established.
+- `far'`: the new case that needs a decision or implementation.
+- `hukm`: the ruling, decision, behavior, pattern, or constraint from the source case.
+- `'illah`: the effective cause that makes the `hukm` transferable.
+
+The key discipline: transfer the `'illah`, not merely the `hikmah`. `hikmah` is the wisdom or purpose; `'illah` is the operative cause. If the source pattern was good because it reduced hallucination through forced evidence, the transferable cause is forced evidence, not the broad vibe of "quality."
+
+## Qiyas Validity Test
+
+Before transferring a pattern, answer all seven:
+
+1. Is the `asl` actually established by evidence, or only remembered/implied?
+2. Is the `hukm` in the `asl` real, working, and desirable?
+3. Is the `'illah` explicit enough that another reader could test it?
+4. Does the same `'illah` exist in the `far'`, not just a surface similarity?
+5. Is there any stronger source that overrides the analogy?
+6. What condition in the `asl` is missing, weaker, inverted, or dangerous in the `far'`?
+7. What verification would prove the transfer worked in the new case?
+
+If any answer is missing, do not transfer yet. Gather evidence or mark the analogy as speculative.
+
+## Types Of Qiyas
+
+Classify the analogy by strength:
+
+- `qiyas_al_awla`: the effective cause is stronger in the new case than the source case. The transfer should be even more justified.
+- `qiyas_al_musawi`: the effective cause is equal in both cases. The transfer is direct if no override exists.
+- `qiyas_al_adna`: the effective cause is weaker in the new case. Use caution and stronger verification.
+- `qiyas_jali`: manifest analogy; the effective cause is obvious and low-dispute.
+- `qiyas_khafi`: hidden analogy; the effective cause requires careful reasoning and may need Istihsan, Maslahah, Mizan, or operator review.
+
+When the analogy is `adna` or `khafi`, visibly increase evidence requirements. Do not ship broad claims from weak analogy.
+
+## Furuq False-Analogy Corrective
+
+After proposing an analogy, run a furuq pass:
+
+- What does the new case look like on the surface?
+- What is actually happening underneath: incentives, state, users, data, runtime behavior, trust burden, failure mode?
+- Which verbal label is too coarse for the real situation?
+- Does the new case differ in `'illah`, maqsad, triggering condition, risk, authority, user expectation, or reversibility?
+- Would copying the source pattern over-permit, over-prohibit, over-simplify, or hide a real defect?
+
+If the furuq pass finds a material distinction, revise the transfer. False analogy is not a small defect; it can make the whole conclusion wrong.
+
+## Engineering Translation
+
+For code and systems:
+
+- `asl`: known-good module, hook, endpoint, migration, test, gate, SDK surface, or runtime contract.
+- `far'`: new file, skill, hook, feature, service, or launch flow.
+- `hukm`: implementation shape, validation rule, API contract, recovery path, or quality bar.
+- `'illah`: exact reason the source works, such as schema enforcement, persisted evidence, pre-tool blocking, runtime health check, explicit owner action, or test coverage.
+
+Transfer only the mechanism that carries the `'illah`. Do not copy names, prose, abstractions, or ceremony if they do not carry the cause.
+
+## Product Translation
+
+For business and launch:
+
+- `asl`: proven market motion, offer structure, adoption mechanic, buyer pain, distribution loop, or free-to-paid pathway.
+- `far'`: Aria/Garden/Harness/Claude Code SDK launch decision.
+- `hukm`: pricing, packaging, free tier, wedge, promise, audience, or sequencing.
+- `'illah`: why the source motion worked: urgency, viral artifact, immediate value, trust proof, switching cost, founder credibility, developer workflow pain, or outcome visibility.
+
+Do not transfer a launch tactic because the surface market is similar. Transfer only when the buyer pain, proof loop, and adoption mechanic match.
+
+## Canonical Qiyas-15 Pass
+
+For high-stakes architecture, cognition, launch, ledger, audit, harness, Garden, SDK, or product positioning work, run all fifteen perspectives. Each perspective must produce a concrete finding, a verdict of `ok` or `defect`, and a remediation when defective.
+
+Canonical order:
+
+1. `Owner-Hamza-tomorrow`: will the owner tomorrow trust the decision, reproduce the evidence, and avoid redoing the same phase?
+2. `operator-client`: does a paying operator get reliable output, clear state, and less cognitive burden?
+3. `investor`: does the choice create a credible wedge, defensibility, speed to market, and compounding proof?
+4. `LLM-consumer`: will a downstream model understand the artifact without hallucinating hidden assumptions?
+5. `human-end-user`: does the final user experience improve, or only the internal architecture story?
+6. `skeptic`: what would a smart critic call fake, overclaimed, circular, or unproven?
+7. `compliance`: are authority, privacy, security, licensing, evidence, and scope truthfully represented?
+8. `engineering-quality`: is the implementation testable, maintainable, typed, observable, and free of fake fallbacks?
+9. `cognitive-load`: does the plan reduce overload, or does it add ritual, logs, and decisions the operator must carry?
+10. `scale`: does the pattern work for one session only, or across many agents, repos, customers, failures, and handoffs?
+11. `Islamic-scholar`: is the reasoning disciplined, humble, source-aware, and not abusing sacred terminology as branding?
+12. `clinical-scholar`: if the domain touches care, coaching, distress, behavior, or human vulnerability, is harm bounded and evidence careful?
+13. `red-team-attacker`: how can the pattern be gamed, bypassed, spoofed, prompt-injected, or turned into false confidence?
+14. `1-week-future-self`: what breaks when the current context fades and only files, logs, ledgers, and habits remain?
+15. `1-year-future-self`: what doctrine, API, memory, pricing, customer expectation, or architecture debt will this create over time?
+
+Dense output shape when an artifact requires it:
+
+```yaml
+qiyas_15_pass:
+  - perspective: Owner-Hamza-tomorrow
+    finding: "Concrete finding with evidence or observable impact, not generic praise."
+    verdict: ok
+    evidence_anchor: "file:line or runtime/test/source anchor"
+```
+
+If `verdict: defect`, include `remediation`. For cognition specs governed by M9.DRIFT.10d, include `finding_handling` with one of: `fixed_in_rung`, `carried_to_followup_rung`, or `wont_fix_documented`.
+
+## Mini Qiyas For Normal Turns
+
+When the task is small, do not print the full Qiyas-15. Still think through a compressed pass:
+
+- Which source pattern is being transferred?
+- What is the actual effective cause?
+- Where does the analogy break?
+- What one verification protects against false transfer?
+- Which of the 15 perspectives would most likely object?
+
+Then let that change the answer.
+
+## Stop Conditions
+
+Stop and repair before continuing when:
+
+- The `asl` is vague or not evidenced.
+- The `'illah` is a broad virtue word instead of a testable cause.
+- The `far'` shares wording but not underlying reality.
+- The analogy is being used to justify a decision already made.
+- A perspective in Qiyas-15 finds a defect that the plan does not handle.
+- The output claims readiness while the analogy is still unverified.
+
+## Recovery Contract
+
+When this skill blocks, execute one recovery attempt:
+
+1. Gather the missing source evidence, runtime proof, repo pattern, transcript anchor, or owner instruction.
+2. Re-run the four-pillar mapping and furuq pass.
+3. If the same failure remains, escalate to Mizan/Aria/harness or mark the analogy invalid and choose a non-analogical path.
+
+Do not end with user-handoff-only behavior unless the remaining blocker is genuinely an owner decision. Report the executed recovery, evidence, remaining blocker, and next concrete action.
+
+## Output Discipline
+
+Do not leak a giant Qiyas block in normal conversation. Use the cognition to improve the work. Show the full Qiyas-15 only when the user asks for it, when writing an audit/spec/ledger artifact, or when a gate requires the structured block.
+
+## 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.