@aria_asi/cli 0.2.40 → 0.2.41

package/skills/skill-installer/scripts/install-skill-from-github.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Install a skill from a GitHub repo path into $CODEX_HOME/skills."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import zipfile
+
+from github_utils import github_request
+DEFAULT_REF = "main"
+
+
+@dataclass
+class Args:
+    url: str | None = None
+    repo: str | None = None
+    path: list[str] | None = None
+    ref: str = DEFAULT_REF
+    dest: str | None = None
+    name: str | None = None
+    method: str = "auto"
+
+
+@dataclass
+class Source:
+    owner: str
+    repo: str
+    ref: str
+    paths: list[str]
+    repo_url: str | None = None
+
+
+class InstallError(Exception):
+    pass
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _tmp_root() -> str:
+    base = os.path.join(tempfile.gettempdir(), "codex")
+    os.makedirs(base, exist_ok=True)
+    return base
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-install")
+
+
+def _parse_github_url(url: str, default_ref: str) -> tuple[str, str, str, str | None]:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.netloc != "github.com":
+        raise InstallError("Only GitHub URLs are supported for download mode.")
+    parts = [p for p in parsed.path.split("/") if p]
+    if len(parts) < 2:
+        raise InstallError("Invalid GitHub URL.")
+    owner, repo = parts[0], parts[1]
+    ref = default_ref
+    subpath = ""
+    if len(parts) > 2:
+        if parts[2] in ("tree", "blob"):
+            if len(parts) < 4:
+                raise InstallError("GitHub URL missing ref or path.")
+            ref = parts[3]
+            subpath = "/".join(parts[4:])
+        else:
+            subpath = "/".join(parts[2:])
+    return owner, repo, ref, subpath or None
+
+
+def _download_repo_zip(owner: str, repo: str, ref: str, dest_dir: str) -> str:
+    zip_url = f"https://codeload.github.com/{owner}/{repo}/zip/{ref}"
+    zip_path = os.path.join(dest_dir, "repo.zip")
+    try:
+        payload = _request(zip_url)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"Download failed: HTTP {exc.code}") from exc
+    with open(zip_path, "wb") as file_handle:
+        file_handle.write(payload)
+    with zipfile.ZipFile(zip_path, "r") as zip_file:
+        _safe_extract_zip(zip_file, dest_dir)
+        top_levels = {name.split("/")[0] for name in zip_file.namelist() if name}
+    if not top_levels:
+        raise InstallError("Downloaded archive was empty.")
+    if len(top_levels) != 1:
+        raise InstallError("Unexpected archive layout.")
+    return os.path.join(dest_dir, next(iter(top_levels)))
+
+
+def _run_git(args: list[str]) -> None:
+    result = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if result.returncode != 0:
+        raise InstallError(result.stderr.strip() or "Git command failed.")
+
+
+def _safe_extract_zip(zip_file: zipfile.ZipFile, dest_dir: str) -> None:
+    dest_root = os.path.realpath(dest_dir)
+    for info in zip_file.infolist():
+        extracted_path = os.path.realpath(os.path.join(dest_dir, info.filename))
+        if extracted_path == dest_root or extracted_path.startswith(dest_root + os.sep):
+            continue
+        raise InstallError("Archive contains files outside the destination.")
+    zip_file.extractall(dest_dir)
+
+
+def _validate_relative_path(path: str) -> None:
+    if os.path.isabs(path) or os.path.normpath(path).startswith(".."):
+        raise InstallError("Skill path must be a relative path inside the repo.")
+
+
+def _validate_skill_name(name: str) -> None:
+    altsep = os.path.altsep
+    if not name or os.path.sep in name or (altsep and altsep in name):
+        raise InstallError("Skill name must be a single path segment.")
+    if name in (".", ".."):
+        raise InstallError("Invalid skill name.")
+
+
+def _git_sparse_checkout(repo_url: str, ref: str, paths: list[str], dest_dir: str) -> str:
+    repo_dir = os.path.join(dest_dir, "repo")
+    clone_cmd = [
+        "git",
+        "clone",
+        "--filter=blob:none",
+        "--depth",
+        "1",
+        "--sparse",
+        "--single-branch",
+        "--branch",
+        ref,
+        repo_url,
+        repo_dir,
+    ]
+    try:
+        _run_git(clone_cmd)
+    except InstallError:
+        _run_git(
+            [
+                "git",
+                "clone",
+                "--filter=blob:none",
+                "--depth",
+                "1",
+                "--sparse",
+                "--single-branch",
+                repo_url,
+                repo_dir,
+            ]
+        )
+    _run_git(["git", "-C", repo_dir, "sparse-checkout", "set", *paths])
+    _run_git(["git", "-C", repo_dir, "checkout", ref])
+    return repo_dir
+
+
+def _validate_skill(path: str) -> None:
+    if not os.path.isdir(path):
+        raise InstallError(f"Skill path not found: {path}")
+    skill_md = os.path.join(path, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        raise InstallError("SKILL.md not found in selected skill directory.")
+
+
+def _copy_skill(src: str, dest_dir: str) -> None:
+    os.makedirs(os.path.dirname(dest_dir), exist_ok=True)
+    if os.path.exists(dest_dir):
+        raise InstallError(f"Destination already exists: {dest_dir}")
+    shutil.copytree(src, dest_dir)
+
+
+def _build_repo_url(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}.git"
+
+
+def _build_repo_ssh(owner: str, repo: str) -> str:
+    return f"git@github.com:{owner}/{repo}.git"
+
+
+def _prepare_repo(source: Source, method: str, tmp_dir: str) -> str:
+    if method in ("download", "auto"):
+        try:
+            return _download_repo_zip(source.owner, source.repo, source.ref, tmp_dir)
+        except InstallError as exc:
+            if method == "download":
+                raise
+            err_msg = str(exc)
+            if "HTTP 401" in err_msg or "HTTP 403" in err_msg or "HTTP 404" in err_msg:
+                pass
+            else:
+                raise
+    if method in ("git", "auto"):
+        repo_url = source.repo_url or _build_repo_url(source.owner, source.repo)
+        try:
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+        except InstallError:
+            repo_url = _build_repo_ssh(source.owner, source.repo)
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+    raise InstallError("Unsupported method.")
+
+
+def _resolve_source(args: Args) -> Source:
+    if args.url:
+        owner, repo, ref, url_path = _parse_github_url(args.url, args.ref)
+        if args.path is not None:
+            paths = list(args.path)
+        elif url_path:
+            paths = [url_path]
+        else:
+            paths = []
+        if not paths:
+            raise InstallError("Missing --path for GitHub URL.")
+        return Source(owner=owner, repo=repo, ref=ref, paths=paths)
+
+    if not args.repo:
+        raise InstallError("Provide --repo or --url.")
+    if "://" in args.repo:
+        return _resolve_source(
+            Args(url=args.repo, repo=None, path=args.path, ref=args.ref)
+        )
+
+    repo_parts = [p for p in args.repo.split("/") if p]
+    if len(repo_parts) != 2:
+        raise InstallError("--repo must be in owner/repo format.")
+    if not args.path:
+        raise InstallError("Missing --path for --repo.")
+    paths = list(args.path)
+    return Source(
+        owner=repo_parts[0],
+        repo=repo_parts[1],
+        ref=args.ref,
+        paths=paths,
+    )
+
+
+def _default_dest() -> str:
+    return os.path.join(_codex_home(), "skills")
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="Install a skill from GitHub.")
+    parser.add_argument("--repo", help="owner/repo")
+    parser.add_argument("--url", help="https://github.com/owner/repo[/tree/ref/path]")
+    parser.add_argument(
+        "--path",
+        nargs="+",
+        help="Path(s) to skill(s) inside repo",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument("--dest", help="Destination skills directory")
+    parser.add_argument(
+        "--name", help="Destination skill name (defaults to basename of path)"
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "download", "git"],
+        default="auto",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        source = _resolve_source(args)
+        source.ref = source.ref or args.ref
+        if not source.paths:
+            raise InstallError("No skill paths provided.")
+        for path in source.paths:
+            _validate_relative_path(path)
+        dest_root = args.dest or _default_dest()
+        tmp_dir = tempfile.mkdtemp(prefix="skill-install-", dir=_tmp_root())
+        try:
+            repo_root = _prepare_repo(source, args.method, tmp_dir)
+            installed = []
+            for path in source.paths:
+                skill_name = args.name if len(source.paths) == 1 else None
+                skill_name = skill_name or os.path.basename(path.rstrip("/"))
+                _validate_skill_name(skill_name)
+                if not skill_name:
+                    raise InstallError("Unable to derive skill name.")
+                dest_dir = os.path.join(dest_root, skill_name)
+                if os.path.exists(dest_dir):
+                    raise InstallError(f"Destination already exists: {dest_dir}")
+                skill_src = os.path.join(repo_root, path)
+                _validate_skill(skill_src)
+                _copy_skill(skill_src, dest_dir)
+                installed.append((skill_name, dest_dir))
+        finally:
+            if os.path.isdir(tmp_dir):
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+        for skill_name, dest_dir in installed:
+            print(f"Installed {skill_name} to {dest_dir}")
+        return 0
+    except InstallError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/skill-installer/scripts/list-skills.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""List skills from a GitHub repo path."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+
+from github_utils import github_api_contents_url, github_request
+
+DEFAULT_REPO = "openai/skills"
+DEFAULT_PATH = "skills/.curated"
+DEFAULT_REF = "main"
+
+
+class ListError(Exception):
+    pass
+
+
+class Args(argparse.Namespace):
+    repo: str
+    path: str
+    ref: str
+    format: str
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-list")
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _installed_skills() -> set[str]:
+    root = os.path.join(_codex_home(), "skills")
+    if not os.path.isdir(root):
+        return set()
+    entries = set()
+    for name in os.listdir(root):
+        path = os.path.join(root, name)
+        if os.path.isdir(path):
+            entries.add(name)
+    return entries
+
+
+def _list_skills(repo: str, path: str, ref: str) -> list[str]:
+    api_url = github_api_contents_url(repo, path, ref)
+    try:
+        payload = _request(api_url)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            raise ListError(
+                "Skills path not found: "
+                f"https://github.com/{repo}/tree/{ref}/{path}"
+            ) from exc
+        raise ListError(f"Failed to fetch skills: HTTP {exc.code}") from exc
+    data = json.loads(payload.decode("utf-8"))
+    if not isinstance(data, list):
+        raise ListError("Unexpected skills listing response.")
+    skills = [item["name"] for item in data if item.get("type") == "dir"]
+    return sorted(skills)
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="List skills.")
+    parser.add_argument("--repo", default=DEFAULT_REPO)
+    parser.add_argument(
+        "--path",
+        default=DEFAULT_PATH,
+        help="Repo path to list (default: skills/.curated)",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        skills = _list_skills(args.repo, args.path, args.ref)
+        installed = _installed_skills()
+        if args.format == "json":
+            payload = [
+                {"name": name, "installed": name in installed} for name in skills
+            ]
+            print(json.dumps(payload))
+        else:
+            for idx, name in enumerate(skills, start=1):
+                suffix = " (already installed)" if name in installed else ""
+                print(f"{idx}. {name}{suffix}")
+        return 0
+    except ListError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/skills-and-hooks-reference/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: skills-and-hooks-reference
+description: Reference for Claude Code skills, Claude Code hooks, OpenCode skills, and OpenCode hooks. Use when the user asks about SKILL.md format, hook events, settings.json hooks block, slash commands vs skills vs agents, OpenCode plugins, or how to extend either tool. Also use when comparing the two tools or deciding where to write a new skill.
+when_to_use: User mentions skills, hooks, SKILL.md, hook events, slash commands, plugins, sst/opencode, .claude/skills/, .opencode/skills/, .opencode/plugins/, settings.json hooks, or asks "where do I write/save my X" for a custom Claude/OpenCode extension.
+---
+
+# Skills & Hooks — Claude Code + OpenCode
+
+## Top finding (read first)
+**OpenCode reads `~/.claude/skills/` directly.** Write a skill once in your personal Claude skills dir and both tools pick it up. There's no first-party skill marketplace in either tool — `~/.claude/skills/` is the de-facto distribution path.
+
+**OpenCode hooks are also `await`-and-block** — switching to OpenCode does NOT solve Claude Code's blocking-hooks pain. Skills bypass this entirely (prompt-only, no hook latency).
+
+---
+
+## Claude Code — Skills
+
+**Where they live (precedence: enterprise → user → project → plugin):**
+```
+~/.claude/skills/<name>/SKILL.md           # personal, all projects
+.claude/skills/<name>/SKILL.md             # project, committed
+<plugin>/skills/<name>/SKILL.md            # plugins (namespace: plugin:name)
+```
+
+A skill is a **directory** with `SKILL.md` plus optional bundled files (`reference.md`, `scripts/*.sh`, etc).
+
+**SKILL.md frontmatter:**
+```yaml
+---
+name: my-skill                    # required, lowercase-hyphens, ≤64 chars
+description: ...                  # required — Claude uses this to auto-load
+when_to_use: "..."                # optional, appended to description
+allowed-tools: Read Bash(git *)   # only granted while skill is active
+disable-model-invocation: false   # true = manual /skill-name only
+user-invocable: true              # false = hidden from / menu
+paths: "src/**,test/**"           # glob filter for auto-load
+model: opus[1m]                   # override model
+context: fork                     # run in isolated subagent
+agent: Explore                    # subagent type when forked
+hooks: {}                         # skill-scoped hooks
+---
+```
+
+Body: markdown. `$ARGUMENTS`, `$0/$1`, `${CLAUDE_SKILL_DIR}` substitution. `` !`cmd` `` runs at load time.
+
+**Triggering:** (1) Auto via `description` match. (2) `/skill-name [args]` typed by user. (3) Programmatic via Skill tool.
+
+**Progressive disclosure:** description always in context (~tiny), body only loads on invocation, linked files load on-demand. After compaction, first 5,000 tokens of recent skills re-attach.
+
+**Description writing:** lead with use case, follow with trigger phrases ("Use when user asks for X, wants Y"). Keywords first — late keywords get truncated at the 1,536-char description+when_to_use cap.
+
+---
+
+## Claude Code — Hooks
+
+**Events:**
+
+| Event | Block? | Notes |
+|---|---|---|
+| `SessionStart` | No | matchers: startup/resume/clear/compact |
+| `SessionEnd` | No | |
+| `PreCompact` | Warn only | |
+| `UserPromptSubmit` | **Yes (exit 2)** | reject prompt before Claude reads |
+| `Stop` | **Yes (exit 2)** | reject response before send |
+| `StopFailure` | No | |
+| `PreToolUse` | **Yes** | deny/allow/ask/defer + can rewrite toolInput |
+| `PostToolUse` | No | logging, context injection |
+| `PermissionRequest` | **Yes** | auto-approve/deny |
+| `Notification`, `SubagentStop`, `SubagentToolUse` | varies | |
+
+**Config (settings.json):**
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "Bash",
+  "hooks": [ { "type": "command", "command": ".claude/hooks/gate.sh", "timeout": 2000 } ] } ] } }
+```
+Matcher: exact (`Bash`), list (`Edit|Write`), or regex (`mcp__memory__.*`).
+
+**Return contract:**
+- stdin: JSON payload
+- exit 0: parse stdout JSON
+- exit 1: log stderr, continue
+- exit 2: **block**
+
+```json
+{ "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "policy",
+    "updatedInput": { "command": "safe-version" },
+    "additionalContext": "extra context for Claude"
+} }
+```
+
+**Blocking semantics — phone pain:** all hooks block the turn until exit (or `timeout`). Non-blocking hook support is not yet GA. `disableAllHooks: true` is the kill-switch. Workaround: HTTP hook (`type: "http"`) to a backend that doesn't await.
+
+**Env vars:** `$CLAUDE_PROJECT_DIR`, `$CLAUDE_SESSION_ID`, `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`.
+
+---
+
+## OpenCode (sst/opencode) — Skills
+
+**Anthropic-compatible — first-class subsystem.** Search paths (walks upward to git root):
+```
+.opencode/skills/<name>/SKILL.md             # project, native
+~/.config/opencode/skills/<name>/SKILL.md    # global, native
+.claude/skills/<name>/SKILL.md               # Claude-compat (project)
+~/.claude/skills/<name>/SKILL.md             # Claude-compat (global)
+.agents/skills/<name>/SKILL.md               # generic
+~/.agents/skills/<name>/SKILL.md             # generic
+```
+Names must be globally unique.
+
+**SKILL.md format (smaller than Claude's):**
+```yaml
+---
+name: my-skill              # required, must match folder, [a-z0-9-]
+description: ...            # required, ≤1024 chars
+license: MIT                # optional
+compatibility: opencode     # optional
+metadata: {}                # optional string→string
+---
+```
+Unknown fields (incl. Claude's `allowed-tools`) silently ignored — tool restriction lives at the **agent** level.
+
+**Triggering — model-only:** OpenCode lists skills as catalog (name+description) at session start. Model calls built-in `skill` tool to load body. **No `/skill` slash invoke.** For user-triggered, use `.opencode/commands/`.
+
+**Skills vs agents vs commands:**
+| Concept | Folder | Invoked by |
+|---|---|---|
+| Agent | `.opencode/agents/*.md` | User Tab / `@mention` |
+| Command | `.opencode/commands/*.md` | `/<name>` in TUI |
+| Skill | `.opencode/skills/<name>/SKILL.md` | Model via skill tool |
+
+**Permissioning** (`opencode.json`):
+```json
+{ "permission": { "skill": {
+  "*": "allow", "internal-*": "deny", "experimental-*": "ask"
+} } }
+```
+
+---
+
+## OpenCode — Hooks (live in plugins)
+
+**Where:** `.opencode/plugins/*.{js,ts}` or `~/.config/opencode/plugins/*.{js,ts}` or npm packages in `opencode.json`'s `plugin` array.
+
+**Plugin shape:**
+```ts
+import type { Plugin } from "@opencode-ai/plugin"
+export const MyPlugin: Plugin = async (ctx) => ({
+  event: async ({ event }) => {
+    if (event.type === "session.idle") { /* ... */ }
+  },
+  "tool.execute.before": async (input, output) => {
+    if (input.tool === "read" && output.args.filePath.includes(".env")) {
+      throw new Error("Cannot read .env files")
+    }
+  },
+})
+```
+
+**Key events:** `tool.execute.before/after`, `session.created/idle/compacted/error/updated`, `message.*`, `file.edited`, `permission.asked/replied`, `tui.*`, `shell.env`, `lsp.*`, `experimental.session.compacting`.
+
+**Blocking — same pain:** all hooks awaited and sequential. `tool.execute.before` cancels by **throwing**. No first-class non-blocking variant. Fire-and-forget = don't `await` inside the handler (loses error reporting). No documented hook-timeout for non-tool events.
+
+---
+
+## Practical takeaways for phone use
+
+1. **Skills > hooks while non-blocking is unshipped.** Pure prompt-cost, no turn delay.
+2. **Write skills in `~/.claude/skills/` for cross-tool reuse.** OpenCode reads them too.
+3. **Auto-load pattern:** sharp `description` with trigger phrases, `disable-model-invocation: false`, no `paths:` filter unless project-specific. Claude pulls it without you typing `/`.
+4. **Re-express PreToolUse policy hooks as skills with `allowed-tools` constraints** when latency matters more than absolute enforcement.
+5. **Don't migrate to OpenCode for the hook problem.** Same await-and-block model.
+
+---
+
+Sources: docs.claude.com Claude Code (skills.md, hooks.md), opencode.ai/docs (skills, plugins, agents, commands, config), github.com/sst/opencode, deepwiki.com/sst/opencode.
+
+## Required Workflow
+
+1. Identify the target surface: Claude Code, Codex, OpenCode, hooks, skills, or plugins.
+2. Use current local docs or official docs before making compatibility claims.
+3. Distinguish prompt-skill behavior from mechanical hook enforcement.
+4. Verify local file paths or config keys before recommending edits.
+5. Report the practical next step and any compatibility risk.
+
+## First-Class Production Contract
+
+When this skill is loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, and no vague future wiring in skills/hooks guidance
+- real proof from local config, official docs, command output, or owner instruction before claiming compatibility
+- re-test or re-check the same hook/skill surface after correction
+- a redo contract whenever guidance fails validation: state what failed, what changed, how it was re-tested, and the remaining blocker
+- architect/ARIA console escalation when the same skills/hooks failure repeats twice, crosses system boundaries, or cannot be verified locally

package/skills/soul-domains/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: soul-domains
+description: Use when you need to identify which domain or domains are truly dominant in a task so the answer can be shaped by the right discipline pressures instead of generic intuition.
+---
+
+# Soul Domains
+
+Use this skill to determine which disciplines should govern the decision.
+
+## Workflow
+
+1. Identify the artifact or decision.
+2. Read [../aria-essence/references/domain-matrix.md](../aria-essence/references/domain-matrix.md).
+3. Determine:
+   - dominant domain
+   - secondary supporting domains
+   - neglected domains that could cause hidden failure
+4. Let the dominant domains change the recommendation or implementation.
+5. Summarize the result in readable language, not internal manifold jargon.
+
+## Rules
+
+- Do not pretend to have exact threshold math if the live domain service was not consulted.
+- The point is better decisions, not fancy vocabulary.
+- If only one domain truly matters, say so plainly.
+
+## 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.