@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/research-arxiv/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: research-arxiv
+scope: common
+category: research
+description: "Search arXiv papers by keyword, author, category, or ID."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  nativeReplaces: [arxiv]
+  upstream: Hermes Agent skills/research/arxiv at 1a1f4a59e2
+  hermes:
+    tags: [Research, Arxiv, Papers, Academic, Science, API]
+    related_skills: [office-artifacts, evidence-citations]
+---
+
+# arXiv Research
+
+Search and retrieve academic papers from arXiv via their REST API. No API key.
+Use the shipped Python 3.9+ standard-library script relative to this installed
+skill directory, not a hardcoded Hermes repository path:
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning" --max 5 --json
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 1706.03762v1 --json
+```
+
+The script preserves versioned identifiers and full abstracts, bounds response
+size and retries transient HTTP errors, and rejects malformed feeds/options.
+`unknown` metadata is a coverage gap, not permission to invent dates. Use
+`evidence-citations` for quotations and `office-artifacts` for PDFs. Attach only
+requested file outputs through `cloud task attach`/`cloud deliver`; honor PKF
+carrier instructions for inline answers. Abstract retrieval is not full-paper reading.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Search papers | `curl "https://export.arxiv.org/api/query?search_query=all:QUERY&max_results=5"` |
+| Get specific paper | `curl "https://export.arxiv.org/api/query?id_list=2402.03300"` |
+| Read abstract (web) | `web_extract(urls=["https://arxiv.org/abs/2402.03300"])` |
+| Read full paper (PDF) | `web_extract(urls=["https://arxiv.org/pdf/2402.03300"])` |
+
+## Searching Papers
+
+The API returns Atom XML. Use an XML parser (the shipped script), not grep/sed.
+
+### Basic search
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5"
+```
+
+### Clean output
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning" --max 5 --sort date
+```
+
+## Search Query Syntax
+
+| Prefix | Searches | Example |
+|--------|----------|---------|
+| `all:` | All fields | `all:transformer+attention` |
+| `ti:` | Title | `ti:large+language+models` |
+| `au:` | Author | `au:vaswani` |
+| `abs:` | Abstract | `abs:reinforcement+learning` |
+| `cat:` | Category | `cat:cs.AI` |
+| `co:` | Comment | `co:accepted+NeurIPS` |
+
+### Boolean operators
+
+```
+# AND (default when using +)
+search_query=all:transformer+attention
+
+# OR
+search_query=all:GPT+OR+all:BERT
+
+# AND NOT
+search_query=all:language+model+ANDNOT+all:vision
+
+# Exact phrase
+search_query=ti:"chain+of+thought"
+
+# Combined
+search_query=au:hinton+AND+cat:cs.LG
+```
+
+## Sort and Pagination
+
+| Parameter | Options |
+|-----------|---------|
+| `sortBy` | `relevance`, `lastUpdatedDate`, `submittedDate` |
+| `sortOrder` | `ascending`, `descending` |
+| `start` | Result offset (0-based) |
+| `max_results` | Number of results (default 10, max 30000) |
+
+```bash
+# Latest 10 papers in cs.AI
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?search_query=cat:cs.AI&sortBy=submittedDate&sortOrder=descending&max_results=10"
+```
+
+## Fetching Specific Papers
+
+```bash
+# By arXiv ID
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?id_list=2402.03300"
+
+# Multiple papers
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?id_list=2402.03300,2401.12345,2403.00001"
+```
+
+## BibTeX Generation
+
+Retrieve structured metadata using `--json`, retaining the complete versioned ID.
+Register the inspected abstract/PDF URL and title with `evidence-citations`, then
+export its escaped `--style bibtex` entries. For article-specific author/year/
+primaryClass fields, use only returned metadata and a BibTeX serializer; leave
+missing fields absent rather than inventing a category or author. Compile the
+actual bibliography and verify rendered URLs and unresolved-citation warnings.
+
+## Reading Paper Content
+
+After finding a paper, read it:
+
+```
+# Abstract page (fast, metadata + abstract)
+web_extract(urls=["https://arxiv.org/abs/2402.03300"])
+
+# Full paper (PDF → markdown via Firecrawl)
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+```
+
+For local PDF processing, see `office-artifacts`. Use an available extraction
+tool; these examples do not imply a Firecrawl account or full-text entitlement.
+
+## Common Categories
+
+| Category | Field |
+|----------|-------|
+| `cs.AI` | Artificial Intelligence |
+| `cs.CL` | Computation and Language (NLP) |
+| `cs.CV` | Computer Vision |
+| `cs.LG` | Machine Learning |
+| `cs.CR` | Cryptography and Security |
+| `stat.ML` | Machine Learning (Statistics) |
+| `math.OC` | Optimization and Control |
+| `physics.comp-ph` | Computational Physics |
+
+Full list: https://arxiv.org/category_taxonomy
+
+## Helper Script
+
+The `scripts/search_arxiv.py` script handles XML parsing and provides clean output:
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning"
+python3 "<skill-dir>/scripts/search_arxiv.py" "transformer attention" --max 10 --sort date
+python3 "<skill-dir>/scripts/search_arxiv.py" --author "Yann LeCun" --max 5
+python3 "<skill-dir>/scripts/search_arxiv.py" --category cs.AI --sort date
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 2402.03300
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 2402.03300,2401.12345
+```
+
+No dependencies — uses only Python stdlib.
+
+---
+
+## Semantic Scholar (Citations, Related Papers, Author Profiles)
+
+arXiv doesn't provide citation data or recommendations. The optional **Semantic
+Scholar API** provides JSON. Check current endpoint access, authentication and
+rate-limit responses; do not assume a fixed public or API-key quota.
+
+### Get paper details + citations
+
+```bash
+# By arXiv ID
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python -m json.tool
+
+# By Semantic Scholar paper ID or DOI
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fields=title,citationCount"
+```
+
+### Get citations OF a paper (who cited it)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
+```
+
+### Get references FROM a paper (what it cites)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
+```
+
+### Search papers (alternative to arXiv search, returns JSON)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python -m json.tool
+```
+
+### Get paper recommendations
+
+```bash
+curl --fail --silent --show-error --max-time 30 -X POST "https://api.semanticscholar.org/recommendations/v1/papers/" \
+  -H "Content-Type: application/json" \
+  -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python -m json.tool
+```
+
+### Author profile
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python -m json.tool
+```
+
+### Useful Semantic Scholar fields
+
+`title`, `authors`, `year`, `abstract`, `citationCount`, `referenceCount`, `influentialCitationCount`, `isOpenAccess`, `openAccessPdf`, `fieldsOfStudy`, `publicationVenue`, `externalIds` (contains arXiv ID, DOI, etc.)
+
+---
+
+## Complete Research Workflow
+
+1. **Discover**: `python3 "<skill-dir>/scripts/search_arxiv.py" "your topic" --sort date --max 10`
+2. **Assess impact**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID?fields=citationCount,influentialCitationCount"`
+3. **Read abstract**: `web_extract(urls=["https://arxiv.org/abs/ID"])`
+4. **Read full paper**: `web_extract(urls=["https://arxiv.org/pdf/ID"])`
+5. **Find related work**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID/references?fields=title,citationCount&limit=20"`
+6. **Get recommendations**: POST to Semantic Scholar recommendations endpoint
+7. **Track authors**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/author/search?query=NAME"`
+
+## Rate Limits
+
+| API | Rate | Auth |
+|-----|------|------|
+| arXiv | Space requests by at least 3 seconds; honor server limits | No key for public metadata |
+| Semantic Scholar | Honor current service limits and Retry-After | Endpoint/account dependent |
+
+## Notes
+
+- arXiv returns Atom XML — use the helper script or parsing snippet for clean output
+- Semantic Scholar returns JSON — pipe through `python -m json.tool` for readability
+- arXiv IDs: old format (`hep-th/0601001`) vs new (`2402.03300`)
+- PDF: `https://arxiv.org/pdf/{id}` — Abstract: `https://arxiv.org/abs/{id}`
+- HTML (when available): `https://arxiv.org/html/{id}`
+- For local PDF processing, see `office-artifacts`.
+
+## ID Versioning
+
+- `arxiv.org/abs/1706.03762` always resolves to the **latest** version
+- `arxiv.org/abs/1706.03762v1` points to a **specific** immutable version
+- When generating citations, preserve the version suffix you actually read to prevent citation drift (a later version may substantially change content)
+- The API `<id>` field returns the versioned URL (e.g., `http://arxiv.org/abs/1706.03762v7`)
+
+## Withdrawn Papers
+
+Papers can be withdrawn after submission. When this happens:
+- The `<summary>` field contains a withdrawal notice (look for "withdrawn" or "retracted")
+- Metadata fields may be incomplete
+- Always check the summary before treating a result as a valid paper

package/built-in-skills/research-arxiv/scripts/search_arxiv.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Bounded, version-preserving arXiv Atom search (stdlib only)."""
+import argparse
+import json
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+
+NS = {"a": "http://www.w3.org/2005/Atom"}
+ID = re.compile(r"(?:\d{4}\.\d{4,5}|[a-z-]+(?:\.[A-Z]{2})?/\d{7})(?:v[1-9]\d*)?\Z")
+SORTS = {"relevance": "relevance", "date": "submittedDate", "updated": "lastUpdatedDate"}
+
+
+def parse_feed(data):
+    root = ET.fromstring(data)
+    if root.tag != "{" + NS["a"] + "}feed":
+        raise ValueError("response is not an Atom feed")
+    papers = []
+    for entry in root.findall("a:entry", NS):
+        def field(name, default="unknown"):
+            return " ".join((entry.findtext("a:" + name, default, NS) or default).split())
+        raw_id = field("id", "")
+        if "/api/errors" in raw_id:
+            raise ValueError("arXiv API error: " + field("summary"))
+        parsed = urllib.parse.urlsplit(raw_id)
+        if parsed.hostname not in {"arxiv.org", "www.arxiv.org", "export.arxiv.org"} or not parsed.path.startswith("/abs/"):
+            raise ValueError("entry has an invalid arXiv identifier")
+        paper_id = parsed.path.removeprefix("/abs/")
+        if not ID.fullmatch(paper_id):
+            raise ValueError("entry has an invalid arXiv identifier")
+        papers.append({
+            "id": paper_id, "title": field("title"),
+            "published": field("published"), "updated": field("updated"),
+            "authors": [a.findtext("a:name", "unknown", NS) for a in entry.findall("a:author", NS)],
+            "categories": [c.get("term", "") for c in entry.findall("a:category", NS)],
+            "abstract": field("summary", ""),
+            "abs_url": "https://arxiv.org/abs/" + paper_id,
+            "pdf_url": "https://arxiv.org/pdf/" + paper_id,
+        })
+    return papers
+
+
+def search(query=None, author=None, category=None, ids=None, max_results=5, sort="relevance", start=0, as_json=False):
+    if not isinstance(max_results, int) or not 1 <= max_results <= 100:
+        raise ValueError("max_results must be between 1 and 100")
+    if not isinstance(start, int) or start < 0 or sort not in SORTS:
+        raise ValueError("invalid start or sort")
+    params = {"max_results": max_results, "start": start, "sortBy": SORTS[sort], "sortOrder": "descending"}
+    if ids:
+        values = [value.strip() for value in ids.split(",")]
+        if len(values) > 100 or not all(ID.fullmatch(value) for value in values):
+            raise ValueError("invalid arXiv id list")
+        params["id_list"] = ",".join(values)
+    else:
+        parts = [prefix + ":" + value for prefix, value in [("all", query), ("au", author), ("cat", category)] if value]
+        if not parts:
+            raise ValueError("provide a query, --author, --category, or --id")
+        params["search_query"] = " AND ".join(parts)
+    url = "https://export.arxiv.org/api/query?" + urllib.parse.urlencode(params)
+    request = urllib.request.Request(url, headers={"User-Agent": "PrismerResearch/1.0"})
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(request, timeout=20) as response:
+                data = response.read(8 * 1024 * 1024 + 1)
+            if len(data) > 8 * 1024 * 1024:
+                raise ValueError("arXiv response exceeds 8 MiB")
+            break
+        except urllib.error.HTTPError as exc:
+            if attempt == 2 or exc.code not in {429, 500, 502, 503, 504}:
+                raise
+            time.sleep(3 * (attempt + 1))
+    papers = parse_feed(data)
+    if as_json:
+        print(json.dumps({"papers": papers, "start": start, "count": len(papers)}, ensure_ascii=False))
+    elif not papers:
+        print("No results found.")
+    else:
+        for index, paper in enumerate(papers, start=1):
+            print(f"{index}. {paper['title']}\n   ID: {paper['id']} | Published: {paper['published']} | Updated: {paper['updated']}")
+            print("   Authors: " + ", ".join(paper["authors"]))
+            print("   Categories: " + ", ".join(paper["categories"]))
+            print("   Abstract: " + paper["abstract"])
+            print(f"   Links: {paper['abs_url']} | {paper['pdf_url']}\n")
+    return papers
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("query", nargs="?")
+    parser.add_argument("--author")
+    parser.add_argument("--category")
+    parser.add_argument("--id", dest="ids")
+    parser.add_argument("--max", type=int, default=5, dest="max_results")
+    parser.add_argument("--start", type=int, default=0)
+    parser.add_argument("--sort", choices=SORTS, default="relevance")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args()
+    try:
+        search(**vars(args))
+    except (ValueError, ET.ParseError, OSError) as exc:
+        print(f"arxiv search failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/role-builder/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: role-builder
+scope: common
+category: authoring
+description: Create or update a Prismer SS-02 role template from a persona, SOP, job description, or operating brief; instantiate an existing role as a new working agent and run its first task through the bundled one-command harness. Use for "create a role template", "make this role into an agent", "create an agent from this role", or "let this role handle a task". Route standardized instantiate-and-run requests to the script instead of discovering and composing low-level CLI commands.
+license: MIT
+compatibility:
+  - prismer-sdk
+  - hermes
+  - claude-code
+  - codex
+  - openclaw
+metadata:
+  category: authoring
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - WebFetch
+---
+
+# Role Builder
+
+Choose exactly one path from the requested outcome. Do not inspect `cloud
+--help`, create probe assets, or compose low-level commands first.
+
+## A. Existing role → new working agent → first task
+
+Run the bundled harness directly:
+
+```bash
+node scripts/instantiate-and-run.mjs --json
+```
+
+Required environment:
+
+- `PRISMER_API_KEY`
+- `PRISMER_CLOUD_BASE`
+- `PRISMER_ROLE_SLUG`
+- `PRISMER_WORKSPACE_ID`
+- `PRISMER_TASK`
+
+Optional environment:
+
+- `PRISMER_AGENT_HANDLE`, `PRISMER_AGENT_DISPLAY_NAME`,
+  `PRISMER_AGENT_ADAPTER`, `PRISMER_TARGET_DAEMON_ID`
+- `PRISMER_REQUEST_ID`, `PRISMER_OPERATION_LEDGER`
+- `PRISMER_WORKFLOW_TIMEOUT_MS`, `PRISMER_WORKFLOW_POLL_MS`
+- `PRISMER_ALLOW_REMOTE_WRITE=1` for an explicitly confirmed non-local target
+
+The runtime must inject these variables before the turn. Never ask the user to
+paste a credential into chat and never pass one as a command-line flag.
+
+The harness validates locally, performs server preflight, creates/resumes the
+role-backed agent, waits for its exact daemon binding, creates one idempotent
+task, and waits for the canonical result. `--no-wait` skips only the final task
+result wait. `--preflight-only` performs no mutation.
+
+If it returns `ROLE_CONFIG_REQUIRED`, report the missing level, target, and key
+names exactly. Do not guess values:
+
+- `level=skill` or `level=role`, user-owned key: the owner supplies it through
+  Studio or `POST /api/im/user-skill-config`; values are sealed and never enter
+  the model prompt.
+- role default: edit the role's `parameters[]` declaration/default.
+- global-only Skill key: inject it into the daemon/deployment environment.
+- workspace/runtime issue: repair the named workspace or daemon; do not create
+  a different workspace as a workaround.
+
+## B. Material → role template
+
+Create a directory with exactly the role definition and persona:
+
+```text
+<role-slug>/
+├── role.json
+└── SOUL.md
+```
+
+`role.json` is the SS-02 governance manifest. `SOUL.md` is persona only; do
+not put credentials, per-run instructions, or an `AGENTS.md` in the role bundle.
+
+Minimum useful `role.json`:
+
+```json
+{
+  "slug": "legal-expert",
+  "version": "1.0.0",
+  "name": { "en": "Legal Expert", "zh": "法学专家" },
+  "description": { "en": "Analyzes legal matters.", "zh": "分析法律事项。" },
+  "agentType": "specialist",
+  "requiredSkills": [{ "skillSlug": "legal-article-retrieval", "required": true }],
+  "taskAuthority": "executor",
+  "approvalPolicy": "auto-low-risk",
+  "parameters": [],
+  "adapters": { "hermes": {} },
+  "source": "community",
+  "curatedQuality": "review"
+}
+```
+
+Use catalog slugs returned by the Skill create/import result. Never derive a
+slug from a directory name, case-normalize it after creation, or invent one.
+Build missing skills with `skill-creator` first.
+
+Declare only role-specific business skills in `requiredSkills`. The active
+Admin Built-in Skill baseline is injected automatically at template creation
+and re-resolved when an Agent is instantiated. Do not copy system skills into
+the role manifest and do not attempt to remove an injected skill. Readback
+separates `requiredSkills`, `injectedSkills`, and `effectiveSkills`, plus the
+`baselinePolicyVersion` used for the snapshot.
+
+Put the bundle path in `PRISMER_ROLE_BUNDLE`, then run the fixed authoring
+closure as one command:
+
+```bash
+node scripts/author-role.mjs --json
+```
+
+Optional environment: `PRISMER_ROLE_PUBLISH=1` for an explicitly requested
+Marketplace publish, `PRISMER_ROLE_AUTHORING_LEDGER`, `PRISMER_CLOUD_BIN`,
+`PRISMER_CLOUD_BASE`, and `PRISMER_ALLOW_REMOTE_WRITE=1` for a confirmed
+non-local target. The harness performs local validation, read-only required
+Skill preflight, private create/owner-update, and owner readback. It resumes a
+completed same-revision ledger without pushing another role version. Report the
+returned slug/version; do not use `role apply` as a test.
+
+The clean lower-level primitives remain available for diagnosis:
+
+```bash
+cloud role validate ./<role-slug> --json
+cloud role test ./<role-slug> --json
+cloud role create ./<role-slug> --mine --json
+cloud role show <returned-slug-or-id> --json
+```
+
+For the retained legacy entrypoint (requires the current Cloud CLI; no raw HTTP fallback):
+
+```bash
+node scripts/ingest-role.mjs ./<role-slug> --mine
+```
+
+It reads `PRISMER_API_KEY` and `PRISMER_CLOUD_BASE` from the already-injected
+environment. Do not write literal secrets in the command, bundle, or ledger.
+The adapter delegates validation and Skill preflight to Cloud before creation.
+Ledger-based workflows require an injected API key even if Cloud has saved
+credentials: the target origin and that executing key's hash bind every receipt.
+Changing either requires a separate ledger. Completed receipts are read back,
+not blindly trusted. A lock is never stolen on timeout; after a crash, verify
+the old process has stopped and reconcile remote writes before explicit recovery.
+
+## C. Change an existing agent's role
+
+Only when the user explicitly identifies an existing target:
+
+```bash
+cloud role apply <role-slug> --agent <imUserId> --workspace-id <workspaceId>
+```
+
+Never apply a role to the currently executing agent as a probe. Template
+creation is complete after validation, dependency test, ingest, and readback;
+it does not require mutating a live agent.
+
+## Configuration ownership
+
+Declare each value once at the level that owns it:
+
+| Need                              | Owner/declaration                                 | Delivery                         |
+| --------------------------------- | ------------------------------------------------- | -------------------------------- |
+| reusable Skill config             | Skill frontmatter `config:`                       | Skill subprocess env             |
+| role behavior/default             | role `parameters[]`, `kind:"default"`             | structured `roleParams`          |
+| per-account role secret           | role `parameters[]`, `kind:"user", type:"secret"` | environment-only `roleParamsEnv` |
+| role default for a required Skill | role `skillConfig[skillSlug]`                     | resolved Skill env               |
+| workspace identity/policy         | workspace fields and policy APIs                  | server/runtime bootstrap         |
+| workspace runtime secret          | daemon/deployment env                             | child process env only           |
+| invocation target/recovery        | `PRISMER_WORKSPACE_ID`, daemon/request/ledger env | harness request only             |
+
+Do not duplicate values across Skill prose, role persona, workspace metadata,
+and workflow flags. Workspace metadata is not a secret store.
+
+## Harness negative-control contract
+
+The bundled mutation harness must keep these guarantees:
+
+1. Secret-bearing flags, missing/invalid local input, and unconfirmed remote
+   writes fail locally before any fetch.
+2. Server preflight rejects inaccessible/non-deployable roles, missing config,
+   handle collisions, and absent runtime before creating an operation or agent.
+3. Instance and task writes carry durable idempotency keys. Instance retries
+   return the same operation and reject changed instance input with 409; task
+   retries return the first committed task and reject changed task input with 409. Derived task keys are fixed-length hashes, so a 191-character instance
+   request ID cannot overflow the task contract. A new invocation gets a fresh
+   request ID; set `PRISMER_REQUEST_ID` only to resume that same invocation.
+4. A secret-free ledger is written atomically before mutation. Output contains
+   stage, code, retryability, and recovery path—never credentials. Reusing the
+   ledger path with a different invocation hash is rejected before fetch.
+5. Provisioning failure compensates the newly created agent. Incomplete cleanup
+   remains `cleanupStatus=pending` with the Agent pointer retained and retryable;
+   it must never be reported as cleaned. Task failure keeps a valid agent for
+   diagnosis/retry.
+6. `ready` means the Agent is bound to the exact requested daemon. A
+   `wrong_daemon` binding fails explicitly and cannot advance to task creation.
+
+## Sources of truth
+
+- Role standard: `public/docs/Standardization/02-role-template-standard.md`
+- Harness standard: `public/docs/Standardization/16-automation-harness-standard.md`
+- Complete catalog example: `sdk/cloud/catalog/roles/team-manager.json`
+- Skill authoring/import: `sdk/cloud/catalog/skills/skill-creator/SKILL.md`