llm-orchestrator 1.0.0

package/registries/task-mappings.json

@@ -0,0 +1,259 @@
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "version": 2,
+  "obligation_levels": {
+    "mandatory": "Skipping it makes the work invalid, not merely worse. It is a gate. If it cannot run, stop and say so; do not proceed and mention it afterwards.",
+    "optional": "Use when the stated trigger holds. Judgment call, but the trigger is not.",
+    "available": "Exists, costs nothing to ignore, reach for it when it fits."
+  },
+  "task_type_vocabulary_note": "protocol.md, registries/routing-matrix.json and bin/route.mjs speak the UPPER_SNAKE task type; this registry and lib/capability-resolver.mjs speak the lowercase id. task_types is the single map between them, and it also names the workflow file for each type. Never add a task type in one place only.",
+  "task_types": [
+    { "type": "INCIDENT", "id": "incident", "workflow": "workflows/incident.md" },
+    { "type": "FEATURE", "id": "feature", "workflow": "workflows/feature.md" },
+    { "type": "BUG_FIX", "id": "bug", "workflow": "workflows/bug-fix.md" },
+    { "type": "REFACTOR", "id": "refactor", "workflow": "workflows/refactor.md" },
+    { "type": "INVESTIGATION", "id": "investigation", "workflow": "workflows/investigation.md" },
+    { "type": "DEPLOY", "id": "deployment", "workflow": "workflows/deploy.md" },
+    { "type": "CONFIG", "id": "config", "workflow": "workflows/config.md" },
+    { "type": "REVIEW", "id": "review", "workflow": "workflows/review.md" },
+    { "type": "RESEARCH", "id": "research", "workflow": "workflows/research.md" }
+  ],
+  "mappings": [
+    {
+      "id": "research-documentation",
+      "when": { "any_task_types": ["research", "documentation"], "any_task_signals": ["current-facts", "external-facts", "source-claims"] },
+      "requirements": [
+        { "id": "research.retrieve", "level": "required", "scope": "task", "reason": "Current or external factual claims need source retrieval.", "acceptance": ["source-provenance"], "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] },
+        { "id": "research.provenance", "level": "required", "scope": "task", "reason": "Factual claims need attributed provenance.", "acceptance": ["source-provenance"], "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] },
+        { "id": "research.validation", "level": "optional", "scope": "task", "reason": "An additional source-quality pass improves external factual claims.", "acceptance": ["source-validation"], "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "research.retrieve", "trigger": "Any current or external factual claim.", "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] }
+        ],
+        "optional": [
+          { "capability": "research.validation", "trigger": "External/recent source-quality needs a second pass.", "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] }
+        ],
+        "available": [
+          { "capability": "research.provenance", "trigger": "Any factual write-up benefits from attributed sources.", "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] }
+        ]
+      }
+    },
+    {
+      "id": "feature",
+      "when": { "any_task_types": ["feature"] },
+      "requirements": [
+        { "id": "workflow.design", "level": "required", "scope": "phase", "reason": "Behavior changes need an explicit design before implementation.", "applies_when": { "any_phases": ["planning"] }, "acceptance": ["approved-design"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+        { "id": "workflow.plan", "level": "required", "scope": "phase", "reason": "Multi-step feature work needs a plan.", "applies_when": { "any_phases": ["planning"] }, "acceptance": ["implementation-plan"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+        { "id": "workflow.tdd", "level": "required", "scope": "phase", "reason": "Executable changes need behavior tests.", "applies_when": { "any_phases": ["implementation"] }, "acceptance": ["behavioral-test"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+        { "id": "verification.checks", "level": "required", "scope": "phase", "reason": "Acceptance checks must be run before completion.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["verification-output"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["project-test-runner"] },
+        { "id": "test.behavioral", "level": "required", "scope": "task", "reason": "Executable feature behavior needs a test or equivalent check.", "applies_when": { "any_phases": ["implementation", "verification"] }, "acceptance": ["behavioral-test"], "preferred_implementations": ["project-test-runner"], "allowed_alternatives": [] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "workflow.brainstorm", "trigger": "Before entering plan mode.", "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+          { "capability": "workflow.tdd", "trigger": "The failing test is written before implementation.", "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] }
+        ],
+        "optional": [
+          { "capability": "docs.current", "trigger": "Any library/SDK API surface, even a familiar one.", "preferred_implementations": ["context7"], "allowed_alternatives": ["native-web"] },
+          { "capability": "ui.design_system", "trigger": "Any new UI.", "preferred_implementations": ["design-system", "ui-styling"], "allowed_alternatives": [] },
+          { "capability": "billing.provider_evidence", "trigger": "A money path is touched.", "preferred_implementations": ["stripe-best-practices"], "allowed_alternatives": [] },
+          { "capability": "code.semantic_edit", "trigger": "A large cross-file edit is planned.", "preferred_implementations": ["serena"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "workflow.plan", "trigger": "Architecture-shaped feature planning.", "preferred_implementations": ["feature-dev-code-architect"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "bug-incident",
+      "when": { "any_task_types": ["bug", "incident"] },
+      "requirements": [
+        { "id": "workflow.debug", "level": "required", "scope": "phase", "reason": "Bug fixes require evidence and a tested hypothesis.", "applies_when": { "any_phases": ["investigation", "implementation"] }, "acceptance": ["reproduction-evidence", "hypothesis-evidence"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+        { "id": "test.behavioral", "level": "required", "scope": "task", "reason": "A bug fix needs a regression check.", "applies_when": { "any_phases": ["implementation", "verification"] }, "acceptance": ["regression-check"], "preferred_implementations": ["project-test-runner"], "allowed_alternatives": [] },
+        { "id": "review.independent", "level": "optional", "scope": "role", "reason": "Ambiguous or high-risk diagnosis benefits from an adversarial challenge.", "applies_when": { "any_phases": ["review"] }, "acceptance": ["independent-review"], "preferred_implementations": ["independent-reviewer"], "allowed_alternatives": [] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "workflow.systematic_debugging", "trigger": "Reproduce before fixing (BUG_FIX).", "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] },
+          { "capability": "incident.telemetry_first", "trigger": "INCIDENT: before any hypothesis.", "preferred_implementations": ["production-telemetry-collector"], "allowed_alternatives": [] },
+          { "capability": "incident.protocol_order", "trigger": "INCIDENT: start -> evidence -> fix -> verify -> close, in order.", "preferred_implementations": ["incident-orchestration"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "code.locate", "trigger": "Symptom crosses layers.", "preferred_implementations": ["route-data-flow-tracer"], "allowed_alternatives": [] },
+          { "capability": "concurrency.review", "trigger": "An interleaving is suspected.", "preferred_implementations": ["db-concurrency-specialist"], "allowed_alternatives": [] },
+          { "capability": "browser.inspect", "trigger": "The symptom is UI-visible.", "preferred_implementations": ["playwright"], "allowed_alternatives": ["native-browser"] },
+          { "capability": "memory.recall", "trigger": "The symptom rhymes with a prior incident.", "preferred_implementations": ["mempalace"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "code.locate", "trigger": "Locate-only, before deciding a fix approach.", "preferred_implementations": ["caveman-cavecrew-investigator"], "allowed_alternatives": [] },
+          { "capability": "review.adversarial", "trigger": "A second opinion on the hypothesis is cheap and available.", "preferred_implementations": ["adversarial-skeptic"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "refactor",
+      "when": { "any_task_types": ["refactor"] },
+      "requirements": [
+        { "id": "refactor.preservation", "level": "required", "scope": "task", "reason": "A refactor must preserve observable behavior.", "acceptance": ["preservation-check"], "preferred_implementations": ["project-test-runner"], "allowed_alternatives": [] },
+        { "id": "workflow.review", "level": "required", "scope": "phase", "reason": "Ownership and scope need review.", "acceptance": ["scoped-review"], "preferred_implementations": ["superpowers-workflows"], "allowed_alternatives": ["native-workflow-selection"] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "refactor.coverage_first", "trigger": "Coverage must exist before the first edit.", "preferred_implementations": ["project-test-runner"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "code.semantic_edit", "trigger": "Symbol-level moves across many files.", "preferred_implementations": ["serena"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "code.locate", "trigger": "Bounded (<=2 files) mechanical edits.", "preferred_implementations": ["caveman-cavecrew-builder"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "investigation",
+      "when": { "any_task_types": ["investigation"] },
+      "requirements": [
+        { "id": "review.independent", "level": "required", "scope": "role", "reason": "A synthesis never ships from a single source.", "applies_when": { "any_phases": ["review", "synthesis"] }, "acceptance": ["independent-review"], "preferred_implementations": ["independent-reviewer"], "allowed_alternatives": [] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "review.adversarial", "trigger": "On the synthesis — never ship a single-source conclusion.", "preferred_implementations": ["adversarial-skeptic"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "code.semantic_edit", "trigger": "Symbol-aware exploration of a large codebase.", "preferred_implementations": ["serena"], "allowed_alternatives": [] },
+          { "capability": "research.retrieve", "trigger": "An external/recent search is relevant.", "preferred_implementations": ["exa-search"], "allowed_alternatives": ["native-web"] },
+          { "capability": "memory.recall", "trigger": "Before fanning out — the answer may already be filed.", "preferred_implementations": ["mempalace"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "code.locate", "trigger": "Broad read-only location work.", "preferred_implementations": ["caveman-cavecrew-investigator"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "code-library-api-docs",
+      "when": { "any_task_signals": ["version-sensitive", "uncertain-library", "uncertain-platform"] },
+      "requirements": [
+        { "id": "docs.current", "level": "required", "scope": "task", "reason": "Version-sensitive or uncertain API work needs current documentation.", "acceptance": ["versioned-source"], "preferred_implementations": ["context7"], "allowed_alternatives": ["native-web"] }
+      ]
+    },
+    {
+      "id": "web-ui",
+      "when": { "any_task_signals": ["web-ui", "visual-bug", "rendered-behavior"] },
+      "requirements": [
+        { "id": "browser.inspect", "level": "required", "scope": "phase", "reason": "Rendered web acceptance needs browser inspection.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["rendered-ui-acceptance"], "preferred_implementations": ["playwright"], "allowed_alternatives": ["native-browser"] },
+        { "id": "browser.interact", "level": "required", "scope": "phase", "reason": "Rendered web acceptance needs route interaction.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["rendered-ui-acceptance"], "preferred_implementations": ["playwright"], "allowed_alternatives": ["native-browser"] },
+        { "id": "browser.capture", "level": "optional", "scope": "phase", "reason": "A captured viewport makes rendered behavior reviewable.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["rendered-ui-acceptance"], "preferred_implementations": ["playwright"], "allowed_alternatives": ["native-browser"] }
+      ]
+    },
+    {
+      "id": "mobile-native",
+      "when": { "any_task_signals": ["ios", "android", "native-bridge", "mobile-native"] },
+      "requirements": [
+        { "id": "mobile.platform_evidence", "level": "required", "scope": "phase", "reason": "Native acceptance needs platform-specific build or device evidence.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["native-platform-evidence"], "preferred_implementations": ["ios-debugger-agent", "android-performance"], "allowed_alternatives": ["mobile-platform-cli"] }
+      ]
+    },
+    {
+      "id": "billing",
+      "when": { "any_project_domains": ["billing", "stripe", "apple-iap", "google-iap"], "any_task_signals": ["stripe", "apple-iap", "google-iap", "refund", "entitlement", "price", "promotion"] },
+      "requirements": [
+        { "id": "review.independent", "level": "required", "scope": "role", "reason": "Billing, entitlement, and refund work needs independent critical review.", "applies_when": { "any_phases": ["review"] }, "acceptance": ["independent-review"], "preferred_implementations": ["independent-reviewer"], "allowed_alternatives": [] },
+        { "id": "billing.provider_evidence", "level": "required", "scope": "task", "reason": "A provider-state or live-lifecycle claim needs authorized provider evidence.", "applies_when": { "any_task_signals": ["provider-state", "live-lifecycle-claim"], "any_phases": ["investigation", "verification"] }, "acceptance": ["provider-state-evidence"], "preferred_implementations": ["billing-provider-api"], "allowed_alternatives": [] }
+      ]
+    },
+    {
+      "id": "push-firebase",
+      "when": { "any_project_domains": ["push", "firebase"], "any_task_signals": ["push", "firebase", "provider-delivery"] },
+      "requirements": [
+        { "id": "push.provider_evidence", "level": "required", "scope": "task", "reason": "Provider delivery or state diagnosis needs authorized provider evidence.", "applies_when": { "any_task_signals": ["provider-state", "provider-delivery"], "any_phases": ["investigation", "verification"] }, "acceptance": ["provider-state-evidence"], "preferred_implementations": ["push-provider-api"], "allowed_alternatives": [] }
+      ]
+    },
+    {
+      "id": "database-migration",
+      "when": { "any_project_domains": ["database"], "any_task_signals": ["database", "migration", "schema", "concurrency"] },
+      "requirements": [
+        { "id": "database.schema_provenance", "level": "required", "scope": "project", "reason": "Database work needs schema provenance.", "applies_when": { "any_phases": ["planning", "investigation", "implementation"] }, "acceptance": ["schema-provenance"], "preferred_implementations": ["db-client"], "allowed_alternatives": [] },
+        { "id": "database.migration_checks", "level": "required", "scope": "task", "reason": "Migration work needs relevant checks.", "applies_when": { "any_task_signals": ["migration", "schema"], "any_phases": ["implementation", "verification"] }, "acceptance": ["migration-check"], "preferred_implementations": ["project-test-runner"], "allowed_alternatives": ["db-client"] },
+        { "id": "concurrency.review", "level": "required", "scope": "role", "reason": "Concurrency or transactional work needs a relevant review.", "applies_when": { "any_task_signals": ["concurrency"], "any_phases": ["review"] }, "acceptance": ["concurrency-review"], "preferred_implementations": ["db-concurrency-specialist"], "allowed_alternatives": [] }
+      ]
+    },
+    {
+      "id": "forge-remote",
+      "when": { "any_task_signals": ["forge-remote", "github-remote", "pull-request"] },
+      "requirements": [
+        { "id": "forge.remote", "level": "required", "scope": "task", "reason": "A requested forge remote operation needs an authorized forge capability.", "acceptance": ["forge-operation-evidence"], "preferred_implementations": ["gh"], "allowed_alternatives": [] }
+      ]
+    },
+    {
+      "id": "review",
+      "when": { "any_task_types": ["review"] },
+      "requirements": [
+        { "id": "review.independent", "level": "required", "scope": "role", "reason": "Review needs an independent relevant checker.", "acceptance": ["independent-review"], "preferred_implementations": ["independent-reviewer"], "allowed_alternatives": [] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "review.independent", "trigger": "Every review. An independent-reviewer seat if a risk floor applies — cut the implementer, never the reviewer.", "preferred_implementations": ["independent-reviewer"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "review.adversarial", "trigger": "Money, auth, or frozen-build-shaped diffs.", "preferred_implementations": ["adversarial-skeptic"], "allowed_alternatives": [] },
+          { "capability": "traceability.cypilot", "trigger": "The change is PR-shaped.", "preferred_implementations": ["cypilot-pr-review"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "review.independent", "trigger": "A quick second-pass reviewer is available.", "preferred_implementations": ["caveman-cavecrew-reviewer"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "harness-config-skill",
+      "when": { "any_task_types": ["harness", "config", "skill"] },
+      "requirements": [
+        { "id": "harness.docs", "level": "required", "scope": "task", "reason": "Harness or skill work needs relevant versioned documentation.", "acceptance": ["versioned-source"], "preferred_implementations": ["harness-docs"], "allowed_alternatives": ["native-web"] },
+        { "id": "schema.validation", "level": "required", "scope": "task", "reason": "Versioned harness contracts need schema validation.", "acceptance": ["schema-validation"], "preferred_implementations": ["schema-validator"], "allowed_alternatives": ["harness-docs"] }
+      ]
+    },
+    {
+      "id": "config",
+      "when": { "any_task_types": ["config"] },
+      "requirements": [],
+      "obligations": {
+        "mandatory": [
+          { "capability": "config.migration_author", "trigger": "Any schema change — never hand-write a migration.", "preferred_implementations": ["db-migration-author"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "review.independent", "trigger": "A Stripe/Apple/Google webhook is touched.", "preferred_implementations": ["provider-webhook-specialist"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "docs.current", "trigger": "Provider API/config docs are useful context.", "preferred_implementations": ["context7"], "allowed_alternatives": ["native-web"] }
+        ]
+      }
+    },
+    {
+      "id": "deployment",
+      "when": { "any_task_types": ["deployment"] },
+      "requirements": [
+        { "id": "deployment.authorized_target", "level": "required", "scope": "task", "reason": "Deployment requires an authorized target.", "applies_when": { "any_phases": ["precheck"] }, "acceptance": ["authorized-target-evidence"], "preferred_implementations": ["deployment-tool"], "allowed_alternatives": [] },
+        { "id": "deployment.precheck", "level": "required", "scope": "phase", "reason": "Deployment needs prechecks.", "applies_when": { "any_phases": ["precheck"] }, "acceptance": ["deployment-precheck"], "preferred_implementations": ["deployment-tool"], "allowed_alternatives": [] },
+        { "id": "deployment.smoke", "level": "required", "scope": "phase", "reason": "Deployment needs smoke evidence.", "applies_when": { "any_phases": ["verification"] }, "acceptance": ["deployment-smoke"], "preferred_implementations": ["deployment-tool"], "allowed_alternatives": [] },
+        { "id": "deployment.rollback", "level": "required", "scope": "phase", "reason": "Deployment needs rollback evidence.", "applies_when": { "any_phases": ["planning"] }, "acceptance": ["rollback-procedure"], "preferred_implementations": ["deployment-tool"], "allowed_alternatives": [] }
+      ],
+      "obligations": {
+        "mandatory": [
+          { "capability": "deployment.smoke", "trigger": "Every deployment needs post-deploy smoke evidence.", "preferred_implementations": ["deployment-tool"], "allowed_alternatives": [] }
+        ],
+        "optional": [
+          { "capability": "mobile.platform_evidence", "trigger": "A native build is part of the release.", "preferred_implementations": ["xcodebuildmcp", "android-performance"], "allowed_alternatives": [] }
+        ],
+        "available": [
+          { "capability": "deployment.authorized_target", "trigger": "Edge/worker deploy tooling is available.", "preferred_implementations": ["cloudflare-builds"], "allowed_alternatives": [] }
+        ]
+      }
+    },
+    {
+      "id": "parallel-work",
+      "when": { "any_task_signals": ["parallel-work", "delegation"] },
+      "requirements": [
+        { "id": "delegation.bounded", "level": "required", "scope": "task", "reason": "Parallel work needs bounded ownership and verification.", "acceptance": ["delegation-contract"], "preferred_implementations": ["delegation-runtime"], "allowed_alternatives": [] }
+      ]
+    }
+  ]
+}

package/schemas/agent-roles.schema.json

@@ -0,0 +1 @@
+{"_attribution":"llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving","$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://portable-orchestrator.dev/schemas/agent-roles.schema.json","title":"Agent role roster and permission profiles","type":"object","required":["version","permission_profiles","roles"],"properties":{"version":{"type":"integer","minimum":1},"permission_profiles":{"type":"object","additionalProperties":{"type":"object","required":["description","required_access","rules"],"properties":{"description":{"type":"string"},"required_access":{"type":"array","items":{"type":"string"}},"rules":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"roles":{"type":"array","items":{"type":"object","required":["id","description","capabilities","skills","mcps","best_for","permission_profile","default_tier"],"properties":{"id":{"type":"string","minLength":1},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"mcps":{"type":"array","items":{"type":"string"}},"best_for":{"type":"string"},"permission_profile":{"type":"string"},"default_tier":{"type":"string","pattern":"^[WSXF] T[0-5](-T[0-5])?$","description":"Tier and thinking level pair resolved by registries/routing-matrix.json."},"review_floor":{"type":"string","pattern":"^[WSXF] T[0-5](-T[0-5])?$","description":"Minimum review pair for this role domain, where policies/routing.md states one."}},"additionalProperties":false}}}}

package/schemas/capability-contract.schema.json

@@ -0,0 +1,209 @@
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-orchestrator.dev/schemas/capability-contract.schema.json",
+  "title": "Portable capability and dispatch contract",
+  "type": "object",
+  "required": ["mandatory", "required", "optional", "bindings", "recommendations", "degraded", "gaps", "warnings", "unverified_acceptance", "prohibited_operations"],
+  "properties": {
+    "mandatory": { "type": "array", "items": { "$ref": "#/$defs/requirement" } },
+    "required": { "type": "array", "items": { "$ref": "#/$defs/requirement" } },
+    "optional": { "type": "array", "items": { "$ref": "#/$defs/requirement" } },
+    "bindings": { "type": "object", "additionalProperties": { "$ref": "#/$defs/binding" } },
+    "recommendations": { "type": "array", "items": { "$ref": "#/$defs/recommendation" } },
+    "degraded": { "type": "boolean" },
+    "gaps": { "type": "array", "items": { "type": "object", "required": ["capability", "reason"], "properties": { "capability": { "type": "string" }, "reason": { "type": "string" }, "recommendation": { "type": "string" }, "status": { "enum": ["blocked_pending_user", "degraded"] } } } },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "unverified_acceptance": { "type": "array", "items": { "type": "string" } },
+    "prohibited_operations": { "type": "array", "items": { "$ref": "#/$defs/prohibitedOperation" } }
+  },
+  "$defs": {
+    "task": {
+      "title": "Task input",
+      "description": "Portable task classification. type is a stable task category; signals are evidence-backed labels such as web-ui, migration, android, provider-state, or deployment. requires_shell marks a phase that will run shell commands. nontrivial marks work requiring structured decision checkpoints. acceptance names observable acceptance conditions.",
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "signals": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "requires_shell": { "type": "boolean" },
+        "nontrivial": { "type": "boolean" },
+        "acceptance": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      },
+      "additionalProperties": true
+    },
+    "projectProfile": {
+      "type": "object",
+      "required": ["facts", "languages", "frameworks", "domains", "commands"],
+      "properties": {
+        "facts": { "type": "array", "items": { "type": "object", "required": ["kind", "value", "evidence", "confidence"], "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } }, "confidence": { "enum": ["low", "medium", "high"] } }, "additionalProperties": false } },
+        "languages": { "type": "array", "items": { "type": "string" } },
+        "frameworks": { "type": "array", "items": { "type": "string" } },
+        "domains": { "type": "array", "items": { "type": "string" } },
+        "commands": { "type": "array", "items": { "type": "object", "required": ["command", "cwd", "package_manager", "evidence", "confidence"], "properties": { "command": { "type": "string" }, "cwd": { "type": "string" }, "package_manager": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } }, "confidence": { "enum": ["low", "medium", "high"] } }, "additionalProperties": false } },
+        "bindings": { "type": "object", "additionalProperties": { "type": "string" } },
+        "required_capabilities": { "description": "Explicit project invariants and risk floors. A value is a capability id or a project requirement object; this field is deliberate project policy, never inferred from incidental keywords.", "type": "array", "items": { "oneOf": [{ "type": "string" }, { "$ref": "#/$defs/projectRequiredCapability" }] } }
+      },
+      "additionalProperties": true
+    },
+    "toolEntry": {
+      "type": "object",
+      "required": ["id", "kind", "capabilities", "scope", "source", "status", "permission", "evidence", "limitations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["skill", "workflow", "mcp", "native_tool", "cli", "agent_role"] },
+        "capabilities": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "scope": { "enum": ["core", "project", "user", "harness", "task", "phase", "role"] },
+        "source": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["installed", "loaded", "callable", "denied", "unknown"] },
+        "permission": { "enum": ["read_only", "read_write", "denied", "unknown"] },
+        "evidence": { "type": "array", "items": { "type": "string" } },
+        "limitations": { "type": "array", "items": { "type": "string" } },
+        "operation_denied": { "type": "boolean" },
+        "denied_capabilities": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "requirement": {
+      "type": "object",
+      "required": ["id", "level", "scope", "reason", "acceptance", "status"],
+      "properties": {
+        "id": { "type": "string" },
+        "level": { "enum": ["mandatory", "required", "optional"] },
+        "scope": { "enum": ["core", "project", "task", "phase", "role"] },
+        "reason": { "type": "string" },
+        "applies_when": { "type": "object" },
+        "acceptance": { "type": "array", "items": { "type": "string" } },
+        "preferred_implementations": { "type": "array", "items": { "type": "string" } },
+        "allowed_alternatives": { "type": "array", "items": { "type": "string" } },
+        "binding": { "type": ["string", "null"] },
+        "evidence": { "type": "array", "items": { "type": "string" } },
+        "status": { "enum": ["satisfied", "missing", "denied", "not_applicable", "blocked_pending_user", "degraded"] },
+        "provenance": { "type": "array", "items": { "type": "string" } },
+        "gap_declared_first": { "type": "boolean" },
+        "degraded_mode_after_refusal": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "projectRequiredCapability": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "scope": { "enum": ["core", "project", "task", "phase", "role"] },
+        "reason": { "type": "string" },
+        "applies_when": { "type": "object" },
+        "acceptance": { "type": "array", "items": { "type": "string" } },
+        "preferred_implementations": { "type": "array", "items": { "type": "string" } },
+        "allowed_alternatives": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "binding": {
+      "type": "object",
+      "required": ["capability", "implementation", "kind", "source", "permission", "evidence"],
+      "properties": {
+        "capability": { "type": "string" },
+        "implementation": { "type": "string" },
+        "kind": { "enum": ["skill", "workflow", "mcp", "native_tool", "cli", "agent_role", "manual"] },
+        "source": { "type": "string" },
+        "permission": { "enum": ["read_only", "read_write", "denied", "unknown"] },
+        "evidence": { "type": "array", "items": { "type": "string" } },
+        "limitations": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "recommendation": {
+      "type": "object",
+      "required": ["capability", "implementation", "kind", "level", "reason", "phase", "blocks"],
+      "properties": {
+        "capability": { "type": "string" },
+        "implementation": { "type": "string" },
+        "kind": { "enum": ["skill", "workflow", "mcp", "native_tool", "cli", "agent_role"] },
+        "level": { "enum": ["required", "optional"] },
+        "reason": { "type": "string" },
+        "phase": { "type": "string" },
+        "alternatives": { "type": "array", "items": { "type": "string" } },
+        "evidence_impact": { "type": "array", "items": { "type": "string" } },
+        "blocks": { "type": "boolean" },
+        "display_name": { "type": "string" },
+        "recommendation_kind": { "enum": ["product", "capability_gap"] },
+        "installable": { "type": "boolean" },
+        "source_url": { "type": "string", "format": "uri" }
+      },
+      "additionalProperties": true
+    },
+    "dispatchContract": {
+      "title": "Child dispatch contract",
+      "description": "A child-specific projection of a CapabilityPlan. The child receives only shard-relevant facts, bindings, permissions, fallbacks, and acceptance conditions.",
+      "type": "object",
+      "required": ["shard", "routing", "required_capabilities", "optional_capabilities", "bindings", "project_evidence", "inventory_revision", "required_mcps", "required_skills", "required_workflows", "required_cli_tools", "available_tools", "permission_profile", "rtk_preflight", "fallback_plan"],
+      "properties": {
+        "shard": { "type": "object", "required": ["id", "ownership", "acceptance"], "properties": { "id": { "type": "string" }, "ownership": { "type": "array", "items": { "type": "string" } }, "acceptance": { "type": "array", "items": { "type": "string" } }, "parent_agent_id": { "type": "string" }, "child_agent_id": { "type": "string" } } },
+        "routing": { "oneOf": [{ "$ref": "#/$defs/shardRouting" }, { "type": "null" }] },
+        "required_capabilities": { "type": "array", "items": { "$ref": "#/$defs/requirement" } },
+        "optional_capabilities": { "type": "array", "items": { "$ref": "#/$defs/requirement" } },
+        "bindings": { "type": "object", "additionalProperties": { "$ref": "#/$defs/binding" } },
+        "project_evidence": { "type": "array", "items": { "type": "object" } },
+        "inventory_ref": { "type": "string" },
+        "inventory_revision": { "type": ["number", "string"] },
+        "required_mcps": { "type": "array", "items": { "type": "string" } },
+        "required_skills": { "type": "array", "items": { "type": "string" } },
+        "required_workflows": { "type": "array", "items": { "type": "string" } },
+        "required_cli_tools": { "type": "array", "items": { "type": "string" } },
+        "available_tools": { "type": "array", "items": { "type": "object" } },
+        "permission_profile": { "type": "object", "additionalProperties": { "enum": ["read_only", "read_write", "denied", "unknown"] } },
+        "rtk_preflight": { "type": "object", "required": ["required"], "properties": { "required": { "type": "boolean" }, "implementation": { "type": "string" }, "command": { "type": "string" }, "non_mutating": { "type": "boolean" } } },
+        "fallback_plan": { "type": "array", "items": { "type": "object", "required": ["capability", "implementation", "reason"], "properties": { "capability": { "type": "string" }, "implementation": { "type": "string" }, "reason": { "type": "string" } } } },
+        "not_applicable": { "type": "array", "items": { "type": "object" } },
+        "prohibited_operations": { "type": "array", "items": { "$ref": "#/$defs/prohibitedOperation" } }
+      }
+    },
+    "shardRouting": {
+      "title": "PlanShard routing block",
+      "description": "Per-shard cost-aware model selection, resolved at dispatch time against the live inventory. These thirteen field names are canonical: the same names appear in policies/dispatch.md (PlanShard schema), policies/routing.md (Dispatch metadata), protocol.md (flow construction) and lib/dispatch-contract.mjs (SHARD_ROUTING_FIELDS). model_effective is null only when the shard is blocked — the tier floor is never lowered to fit an inventory.",
+      "type": "object",
+      "required": ["pair", "tier", "thinking_level", "model_requested", "effort_requested", "model_effective", "effort_effective", "review_floor", "independent_review", "selection_reason", "inventory_revision", "price_source", "est_usd_per_task"],
+      "properties": {
+        "pair": { "type": "string" },
+        "tier": { "enum": ["W", "S", "X", "F"] },
+        "thinking_level": { "enum": ["T0", "T1", "T2", "T3", "T4", "T5"] },
+        "model_requested": { "type": ["string", "null"] },
+        "effort_requested": { "type": ["string", "null"] },
+        "model_effective": { "type": ["string", "null"] },
+        "effort_effective": { "type": ["string", "null"] },
+        "review_floor": { "type": ["string", "null"] },
+        "independent_review": { "type": "boolean" },
+        "selection_reason": { "type": "string" },
+        "inventory_revision": { "type": ["number", "string", "null"] },
+        "price_source": { "type": "string" },
+        "est_usd_per_task": { "type": ["number", "null"] },
+        "blocked": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "dispatchEvidenceReport": {
+      "title": "Child dispatch evidence report",
+      "description": "Actual phase observations. Loaded workflows and skills, tool calls, substitutions, and concrete acceptance evidence are separate facts.",
+      "type": "object",
+      "properties": {
+        "loaded_skills": { "type": "array", "items": { "type": "string" } },
+        "loaded_workflows": { "type": "array", "items": { "type": "string" } },
+        "used_capabilities": { "type": "array", "items": { "type": "string" } },
+        "used_mcps": { "description": "Every required MCP the child called, or its explicit unavailable/error result. Silent omission is a gate failure (protocol.md, policies/dispatch.md).", "type": "array", "items": { "oneOf": [{ "type": "string" }, { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" }, "result": { "type": "string" }, "error": { "type": "string" } } }] } },
+        "question_for_user": { "description": "A child never asks the user directly; it returns the question here and the orchestrator batches it into one native question (policies/questions.md).", "type": "array", "items": { "type": "object", "required": ["title", "question", "options"], "properties": { "title": { "type": "string" }, "question": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "required": ["label", "cost"], "properties": { "label": { "type": "string" }, "cost": { "type": "string" }, "recommended": { "type": "boolean" } } } }, "blocks": { "type": "string" } } } },
+        "tool_calls": { "type": "array", "items": { "type": "object", "required": ["tool", "capability"], "properties": { "tool": { "type": "string" }, "capability": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } } } } },
+        "agent_role_invocations": { "type": "array", "items": { "type": "object", "required": ["id", "capability", "agent_id"], "properties": { "id": { "type": "string" }, "capability": { "type": "string" }, "agent_id": { "type": "string" }, "artifact": { "type": "string" }, "path": { "type": "string" } } } },
+        "substitutions": { "type": "array", "items": { "type": "object", "required": ["capability", "implementation"], "properties": { "capability": { "type": "string" }, "implementation": { "type": "string" }, "reason": { "type": "string" } } } },
+        "skipped_optional_capabilities": { "type": "array", "items": { "type": "string" } },
+        "effective_permissions": { "type": "object", "additionalProperties": { "enum": ["read_only", "read_write", "denied", "unknown"] } },
+        "acceptance_evidence": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "command": { "type": "string" }, "exit_code": { "type": "integer" }, "artifact": { "type": "string" }, "path": { "type": "string" }, "screenshot": { "type": "string" }, "capture": { "type": "string" }, "source": { "type": "string" }, "summary": { "type": "string" }, "reviewer": { "type": "string" }, "route": { "type": "string" }, "viewport": { "type": "string" } } } }
+      }
+    },
+    "prohibitedOperation": {
+      "type": "object",
+      "required": ["capability", "tool", "reason"],
+      "properties": { "capability": { "type": "string" }, "tool": { "type": "string" }, "reason": { "type": "string" } }
+    }
+  }
+}

package/schemas/installation-manifest.schema.json

@@ -0,0 +1,57 @@
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-orchestrator.dev/schemas/installation-manifest.schema.json",
+  "title": "Portable Orchestrator installation manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "project_id", "harnesses", "skill_resolution", "files", "spans"],
+  "properties": {
+    "_attribution": {"type": "string"},
+    "version": {"const": 1},
+    "project_id": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "harnesses": {"type": "array", "uniqueItems": true, "items": {"enum": ["codex", "claude", "opencode", "kilo"]}},
+    "skill_resolution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skills_root_source", "native_discovery"],
+      "properties": {
+        "skills_root_source": {"enum": ["operator_provided", "default"]},
+        "native_discovery": {"const": "unverified"}
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["scope", "path", "hash", "kind"],
+        "properties": {
+          "scope": {"enum": ["project", "skills"]},
+          "path": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"},
+          "hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "kind": {"enum": ["runtime", "bridge", "native-command"]}
+        }
+      }
+    },
+    "spans": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["scope", "path", "span", "hash", "begin", "end", "before", "after", "created_file"],
+        "properties": {
+          "scope": {"const": "project"},
+          "path": {"type": "string", "minLength": 1},
+          "span": {"type": "string", "minLength": 1},
+          "hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "begin": {"type": "string", "minLength": 1},
+          "end": {"type": "string", "minLength": 1},
+          "before": {"type": "string"},
+          "after": {"type": "string"},
+          "created_file": {"type": "boolean"}
+        }
+      }
+    }
+  }
+}