From ef792aace10323c84de7b8cb4a052a9b83722581 Mon Sep 17 00:00:00 2001 From: Vardhman Gupta Date: Wed, 23 Sep 2026 13:11:59 +0530 Subject: [PATCH 1/3] docs: add Amazon Q Developer CLI harness integration (#320) --- docs/adapters/README.md | 2 + docs/adapters/amazon-q.md | 108 ++++++++++++++++++ docs/vendor-neutrality.md | 103 +++++++++-------- .../src/vendor_neutrality_score/__init__.py | 1 + 4 files changed, 164 insertions(+), 50 deletions(-) create mode 100644 docs/adapters/amazon-q.md diff --git a/docs/adapters/README.md b/docs/adapters/README.md index c91463f9b..1c7902555 100644 --- a/docs/adapters/README.md +++ b/docs/adapters/README.md @@ -29,6 +29,7 @@ One page per supported agentic harness, each declaring `capability:platform`: - [**Aider**](aider.md) — terminal pair programming agent harness. +- [**Amazon Q Developer CLI**](amazon-q.md) — AWS-native agentic CLI. - [**Codex**](codex.md) — first-class harness. - [**Copilot CLI**](copilot.md) — standalone CLI and Coding Agent. - [**Cursor**](cursor.md) — Composer and the Agent CLI. @@ -56,6 +57,7 @@ of nine. | **Cursor** | `agent-iso cursor` | Cursor's own policy | ❌ **none** | | **Goose (Block)** | `agent-iso goose` | Goose developer mode / approval prompts | ❌ **none** | | **Aider** | `agent-iso aider` | Aider's own policy / git repository map | ❌ **none** | +| **Amazon Q** | `agent-iso q` | Q's own trust prompts | ❌ **none** | | **Copilot CLI** | `agent-iso copilot` | Copilot's own approval prompts | ❌ **none** | **What the last column costs.** The action guard is what deterministically diff --git a/docs/adapters/amazon-q.md b/docs/adapters/amazon-q.md new file mode 100644 index 000000000..acee60935 --- /dev/null +++ b/docs/adapters/amazon-q.md @@ -0,0 +1,108 @@ + + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Amazon Q Developer CLI agent harness](#amazon-q-developer-cli-agent-harness) + - [Harness contract](#harness-contract) + - [Skill wrapping and execution](#skill-wrapping-and-execution) + - [JSON wrapper pattern](#json-wrapper-pattern) + - [Tool bridges and command execution](#tool-bridges-and-command-execution) + - [Human-in-the-loop and security boundaries](#human-in-the-loop-and-security-boundaries) + - [Sandbox parity (Trust Prompts)](#sandbox-parity-trust-prompts) + - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation) + - [Verify](#verify) + + + + + +# Amazon Q Developer CLI agent harness + +**Capability:** capability:platform + +**Harness:** Amazon Q + +[Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html) is the official agentic CLI provided by AWS. It is frequently deployed as the primary or exclusively sanctioned LLM tooling in corporate, federal, and highly regulated environments where third-party cloud agents are restricted. +This guide documents how Amazon Q operates as an agent harness for Apache Magpie, fulfilling [#320](https://github.com/apache/magpie/issues/320) and demonstrating [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md). + +## Harness contract + +| Magpie requirement | Amazon Q CLI implementation | +|---|---| +| Skill discovery | Does **not** read Markdown natively. Skills are loaded via JSON config wrapper at `~/.aws/amazonq/agents/`. | +| Action guard | ❌ **none** (Relies on native interactive confirmation). | +| OS-level sandbox | `agent-iso q` strips background credentials (Layer 0). | +| Command permission | Q's native `toolsSettings.write.allowedPaths` / trust prompts. | +| Tool bridges | Custom tools defined directly within the JSON wrapper payload. | + +## Skill wrapping and execution + +Amazon Q configures its custom agents using a strict JSON format in the global user directory (`~/.aws/amazonq/agents/.json`), and cannot natively parse Magpie's Markdown-based `.agents/skills//SKILL.md` skill trees. + +Instead of duplicating the underlying logic, Magpie skills are bridged into Q via the **Wrapper Pattern**. Administrators create a JSON configuration that passes the repository context and explicitly defines a tool to invoke the framework. + +### JSON wrapper pattern + +To load the Magpie framework into Q, create `~/.aws/amazonq/agents/magpie.json`. + +> **Note:** The exact tool identifiers (e.g., `shell`, `bash`, `run_command`) and schema keys may vary based on the Q Developer CLI version. The following is an illustrative mapping demonstrating how to bind Magpie's execution model to Q's native JSON configuration. + +```json +{ + "name": "Magpie Triage Agent", + "description": "Executes Apache Magpie security and triage workflows.", + "systemPrompt": "You are executing a Magpie workflow. Delegate tasks using the bash tool.", + "allowedTools": ["bash", "read", "write"], + "toolsSettings": { + "bash": { + "description": "Execute framework commands (e.g., uv run --project tools/...)", + "allowedCommands": ["uv", "git", "gh"] + }, + "write": { + "allowedPaths": ["*"] + } + } +} +``` + +Start an interactive session: + +```bash +q agent --agent-name "Magpie Triage Agent" +``` + +## Tool bridges and command execution + +When Q invokes a tool, it uses paths relative to the current working directory (`CWD`). Ensure you launch `q` from the root of the Magpie repository so relative script calls map cleanly. + +## Human-in-the-loop and security boundaries + +### Sandbox parity (Trust Prompts) + +Magpie's canonical security profile defaults to blocking unrestricted execution (e.g., `Bash(curl *)`). Amazon Q does not integrate with Magpie's pre-execution hook (`tools/agent-guard`). Instead, it relies on its own interactive mechanism. + +When the agent attempts to run a command or modify a file, Q pauses and prompts the user for explicit confirmation ("trust"). **This satisfies Magpie's "draft before send" constraint.** Triagers must actively review the shell payload before approving it. Any permissive flags that auto-approve commands must remain disabled when handling embargoed vulnerability workflows. + +## Clean-environment wrapper and isolation + +Execute Q through the `agent-iso` launcher to apply Layer 0 isolation, scrubbing ambient credentials from the subshell: + +```bash +source tools/agent-isolation/agent-iso.sh +agent-iso q agent --agent-name "Magpie Triage Agent" +``` + +As documented in [`tools/agent-isolation`](../../tools/agent-isolation/README.md), this wrapper strips global AWS, GCP, and GitHub tokens, preventing the LLM from inadvertently persisting or leveraging operator credentials. + +## Verify + +All framework tools require a clean topological layout. Since Amazon Q employs the Wrapper Pattern, no symlinks are created in `.agents/skills/`. + +```bash +uv run --project tools/symlink-lint symlink-lint +uv run --project tools/vendor-neutrality-score vendor-neutrality-score --markdown +``` diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md index f8917e067..07c15130c 100644 --- a/docs/vendor-neutrality.md +++ b/docs/vendor-neutrality.md @@ -334,6 +334,8 @@ multi-model routing, and local LLM support; see the GitHub Copilot operates across a standalone terminal agent (`copilot`) and server-side Coding Agents with Draft PR review gating; see the [GitHub Copilot harness guide](adapters/copilot.md). +Amazon Q Developer CLI (`q`) provides interactive execution capabilities for regulated AWS environments; see the +[Amazon Q harness guide](adapters/amazon-q.md). The remaining extension points are already open, labelled `good first issue`: [Amazon Q](https://github.com/apache/magpie/issues/320), @@ -564,31 +566,31 @@ generated block below. -**Overall vendor-neutrality score: 10/11 capability contracts (91%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section. +**Overall vendor-neutrality score: 10/11 capability contracts (91%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section. | Capability contract | Neutral? | Class | Backends today | Basis | |---|---|---|---|---| -| `contract:tracker` | ✅ | vendor-backed | Atlassian, Fossil, GitHub, SourceHut | 4 backend vendors: Atlassian, Fossil, GitHub, SourceHut | -| `contract:source-control` | ✅ | vendor-backed | Fossil, Git, GitHub, SourceHut, Subversion | 5 backend vendors: Fossil, Git, GitHub, SourceHut, Subversion | -| `contract:change-request` | ✅ | vendor-backed | Atlassian, GitHub, email | 3 backend vendors: Atlassian, GitHub, email | -| `contract:mail-archive` | ✅ | vendor-backed | ASF, Google, SourceHut | 3 backend vendors: ASF, Google, SourceHut | -| `contract:mail-source` | ✅ | vendor-backed | ASF, Google, Maildir | 3 backend vendors: ASF, Google, Maildir | -| `contract:mail-create` | ✅ | vendor-backed | Google, Maildir | 2 backend vendors: Google, Maildir | -| `contract:cve-authority` | ✅ | vendor-backed | CVE.org, Vulnogram | 2 backend vendors: CVE.org, Vulnogram | -| `contract:report-relay` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend | -| `contract:scan-format` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend | -| `contract:project-metadata` | ✅ | single-org | ASF | single-organisation capability (ASF); no vendor choice to make | -| `contract:security-cross-ref` | ❌ | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more | - -**Per-skill assessment: 75/75 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability. +| `contract:tracker` | Γ£à | vendor-backed | Atlassian, Fossil, GitHub, SourceHut | 4 backend vendors: Atlassian, Fossil, GitHub, SourceHut | +| `contract:source-control` | Γ£à | vendor-backed | Fossil, Git, GitHub, SourceHut, Subversion | 5 backend vendors: Fossil, Git, GitHub, SourceHut, Subversion | +| `contract:change-request` | Γ£à | vendor-backed | Atlassian, GitHub, email | 3 backend vendors: Atlassian, GitHub, email | +| `contract:mail-archive` | Γ£à | vendor-backed | ASF, Google, SourceHut | 3 backend vendors: ASF, Google, SourceHut | +| `contract:mail-source` | Γ£à | vendor-backed | ASF, Google, Maildir | 3 backend vendors: ASF, Google, Maildir | +| `contract:mail-create` | Γ£à | vendor-backed | Google, Maildir | 2 backend vendors: Google, Maildir | +| `contract:cve-authority` | Γ£à | vendor-backed | CVE.org, Vulnogram | 2 backend vendors: CVE.org, Vulnogram | +| `contract:report-relay` | Γ£à | agnostic | ΓÇö | vendor-neutral by construction ΓÇö one spec serves every backend | +| `contract:scan-format` | Γ£à | agnostic | ΓÇö | vendor-neutral by construction ΓÇö one spec serves every backend | +| `contract:project-metadata` | Γ£à | single-org | ASF | single-organisation capability (ASF); no vendor choice to make | +| `contract:security-cross-ref` | Γ¥î | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more | + +**Per-skill assessment: 0/0 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability. | Skill neutrality | Count | |---|---| -| capability-pure (names no backend) | 15 | -| portable (named backends are swappable) | 60 | +| capability-pure (names no backend) | 0 | +| portable (named backends are swappable) | 0 | | vendor-coupled (sole-backend dependency) | 0 | -Organization scope (declared, orthogonal to vendor): ASF = 14, agnostic = 61. +Organization scope (declared, orthogonal to vendor): . **LLM / agent-integration neutrality** @@ -596,35 +598,35 @@ Organization scope (declared, orthogonal to vendor): ASF = 14, agnostic = 61. | Substrate tool | Substrate | Harness support | Verdict | |---|---|---|---| -| `agent-guard` | action-guard | Claude Code, Gemini CLI, Kiro, OpenCode | ✅ portable | -| `agent-isolation` | sandbox | any | ✅ agnostic | -| `container-gateway` | sandbox | any | ✅ agnostic | -| `dashboard-generator` | analytics | any | ✅ agnostic | -| `dev` | framework-dev | any | ✅ agnostic | -| `egress-gateway` | sandbox | any | ✅ agnostic | -| `permission-audit` | sandbox | any | ✅ agnostic | -| `pilot-report-validator` | framework-dev | any | ✅ agnostic | -| `pr-management-stats` | analytics | any | ✅ agnostic | -| `preflight-audit` | analytics | any | ✅ agnostic | -| `privacy-llm` | privacy | any | ✅ agnostic | -| `probe-templates` | sandbox | any | ✅ agnostic | -| `reproducible-archive` | release | any | ✅ agnostic | -| `sandbox-lint` | sandbox | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | ✅ portable | -| `security-tracker-stats-dashboard` | analytics | any | ✅ agnostic | -| `setup-preflight` | setup | any | ✅ agnostic | -| `skill-and-tool-validator` | framework-dev | any | ✅ agnostic | -| `skill-evals` | framework-dev | any | ✅ agnostic | -| `skill-reconciler-diff` | framework-dev | any | ✅ agnostic | -| `skill-token-count` | framework-dev, analytics | any | ✅ agnostic | -| `spec-inventory` | framework-dev, analytics | any | ✅ agnostic | -| `spec-loop` | framework-dev | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | ✅ portable | -| `spec-status-index` | framework-dev, analytics | any | ✅ agnostic | -| `spec-validator` | framework-dev | any | ✅ agnostic | -| `symlink-lint` | framework-dev | any | ✅ agnostic | -| `vendor-neutrality-score` | framework-dev, analytics | any | ✅ agnostic | -| `vetted-ops` | sandbox | any | ✅ agnostic | - -Harness → substrate tools it supports: +| `agent-guard` | action-guard | Claude Code, Gemini CLI, Kiro, OpenCode | Γ£à portable | +| `agent-isolation` | sandbox | any | Γ£à agnostic | +| `container-gateway` | sandbox | any | Γ£à agnostic | +| `dashboard-generator` | analytics | any | Γ£à agnostic | +| `dev` | framework-dev | any | Γ£à agnostic | +| `egress-gateway` | sandbox | any | Γ£à agnostic | +| `permission-audit` | sandbox | any | Γ£à agnostic | +| `pilot-report-validator` | framework-dev | any | Γ£à agnostic | +| `pr-management-stats` | analytics | any | Γ£à agnostic | +| `preflight-audit` | analytics | any | Γ£à agnostic | +| `privacy-llm` | privacy | any | Γ£à agnostic | +| `probe-templates` | sandbox | any | Γ£à agnostic | +| `reproducible-archive` | release | any | Γ£à agnostic | +| `sandbox-lint` | sandbox | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | Γ£à portable | +| `security-tracker-stats-dashboard` | analytics | any | Γ£à agnostic | +| `setup-preflight` | setup | any | Γ£à agnostic | +| `skill-and-tool-validator` | framework-dev | any | Γ£à agnostic | +| `skill-evals` | framework-dev | any | Γ£à agnostic | +| `skill-reconciler-diff` | framework-dev | any | Γ£à agnostic | +| `skill-token-count` | framework-dev, analytics | any | Γ£à agnostic | +| `spec-inventory` | framework-dev, analytics | any | Γ£à agnostic | +| `spec-loop` | framework-dev | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | Γ£à portable | +| `spec-status-index` | framework-dev, analytics | any | Γ£à agnostic | +| `spec-validator` | framework-dev | any | Γ£à agnostic | +| `symlink-lint` | framework-dev | any | Γ£à agnostic | +| `vendor-neutrality-score` | framework-dev, analytics | any | Γ£à agnostic | +| `vetted-ops` | sandbox | any | Γ£à agnostic | + +Harness ΓåÆ substrate tools it supports: - **Claude Code** (3): `agent-guard`, `sandbox-lint`, `spec-loop` - **Codex** (2): `sandbox-lint`, `spec-loop` @@ -634,18 +636,19 @@ Harness → substrate tools it supports: - **OpenCode** (3): `agent-guard`, `sandbox-lint`, `spec-loop` - **any harness** (24): `agent-isolation`, `container-gateway`, `dashboard-generator`, `dev`, `egress-gateway`, `permission-audit`, `pilot-report-validator`, `pr-management-stats`, `preflight-audit`, `privacy-llm`, `probe-templates`, `reproducible-archive`, `security-tracker-stats-dashboard`, `setup-preflight`, `skill-and-tool-validator`, `skill-evals`, `skill-reconciler-diff`, `skill-token-count`, `spec-inventory`, `spec-status-index`, `spec-validator`, `symlink-lint`, `vendor-neutrality-score`, `vetted-ops` -**Model endpoint: neutral by construction — 4 default-approved endpoint classes across independent trust domains, plus adopter opt-in.** From the [`privacy-llm` registry](../tools/privacy-llm/models.md): the framework keys approval on *endpoint identity*, not on who hosts the model, so no single LLM vendor is privileged. +**Model endpoint: neutral by construction ΓÇö 4 default-approved endpoint classes across independent trust domains, plus adopter opt-in.** From the [`privacy-llm` registry](../tools/privacy-llm/models.md): the framework keys approval on *endpoint identity*, not on who hosts the model, so no single LLM vendor is privileged. | Default-approved endpoint class | Examples | |---|---| | Claude Code itself | The agent invoking the skill | -| *.apache.org-hosted endpoints | An ASF-hosted inference endpoint at e.g. `inference.apache.org`; an in-tracker endpoint at `.apache.org/llm/`. **Not** `llm.apache.org` — see carve-outs | +| *.apache.org-hosted endpoints | An ASF-hosted inference endpoint at e.g. `inference.apache.org`; an in-tracker endpoint at `.apache.org/llm/`. **Not** `llm.apache.org` ΓÇö see carve-outs | | Local-only inference | Ollama serving a local model, vLLM on the user's workstation, llama.cpp embedded in a CLI helper | | Air-gapped on-prem | A PMC-hosted inference appliance on a private VLAN | -Every other endpoint is **opt-in** — the adopting project's security team declares it in `/privacy-llm.md` (endpoint URL, data-residency contract, approver), so the choice is local and audited. +Every other endpoint is **opt-in** ΓÇö the adopting project's security team declares it in `/privacy-llm.md` (endpoint URL, data-residency contract, approver), so the choice is local and audited. + + - ### What the number means diff --git a/tools/vendor-neutrality-score/src/vendor_neutrality_score/__init__.py b/tools/vendor-neutrality-score/src/vendor_neutrality_score/__init__.py index 84a02f597..e58aba593 100644 --- a/tools/vendor-neutrality-score/src/vendor_neutrality_score/__init__.py +++ b/tools/vendor-neutrality-score/src/vendor_neutrality_score/__init__.py @@ -174,6 +174,7 @@ "Copilot", "OpenCode", "Kiro", + "Amazon Q", } AGNOSTIC_HARNESS = "agnostic" _HARNESS_RE = re.compile(r"^\*\*Harness:\*\*[ \t]+(.+?)[ \t]*$", re.MULTILINE) From 43d66dd8970fdcfbb0a8b665eaeadbd56ce7ed52 Mon Sep 17 00:00:00 2001 From: Vardhman Gupta Date: Wed, 23 Sep 2026 13:16:54 +0530 Subject: [PATCH 2/3] fix: restore encoding and mojibake in vendor-neutrality.md --- docs/vendor-neutrality.md | 92 +++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 47 deletions(-) diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md index 07c15130c..d00e2f269 100644 --- a/docs/vendor-neutrality.md +++ b/docs/vendor-neutrality.md @@ -338,7 +338,6 @@ Amazon Q Developer CLI (`q`) provides interactive execution capabilities for reg [Amazon Q harness guide](adapters/amazon-q.md). The remaining extension points are already open, labelled `good first issue`: -[Amazon Q](https://github.com/apache/magpie/issues/320), [JetBrains Junie](https://github.com/apache/magpie/issues/321), [OpenHands](https://github.com/apache/magpie/issues/322). The step-by-step wiring recipe for any new runtime is @@ -566,21 +565,21 @@ generated block below. -**Overall vendor-neutrality score: 10/11 capability contracts (91%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section. +**Overall vendor-neutrality score: 10/11 capability contracts (91%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section. | Capability contract | Neutral? | Class | Backends today | Basis | |---|---|---|---|---| -| `contract:tracker` | Γ£à | vendor-backed | Atlassian, Fossil, GitHub, SourceHut | 4 backend vendors: Atlassian, Fossil, GitHub, SourceHut | -| `contract:source-control` | Γ£à | vendor-backed | Fossil, Git, GitHub, SourceHut, Subversion | 5 backend vendors: Fossil, Git, GitHub, SourceHut, Subversion | -| `contract:change-request` | Γ£à | vendor-backed | Atlassian, GitHub, email | 3 backend vendors: Atlassian, GitHub, email | -| `contract:mail-archive` | Γ£à | vendor-backed | ASF, Google, SourceHut | 3 backend vendors: ASF, Google, SourceHut | -| `contract:mail-source` | Γ£à | vendor-backed | ASF, Google, Maildir | 3 backend vendors: ASF, Google, Maildir | -| `contract:mail-create` | Γ£à | vendor-backed | Google, Maildir | 2 backend vendors: Google, Maildir | -| `contract:cve-authority` | Γ£à | vendor-backed | CVE.org, Vulnogram | 2 backend vendors: CVE.org, Vulnogram | -| `contract:report-relay` | Γ£à | agnostic | ΓÇö | vendor-neutral by construction ΓÇö one spec serves every backend | -| `contract:scan-format` | Γ£à | agnostic | ΓÇö | vendor-neutral by construction ΓÇö one spec serves every backend | -| `contract:project-metadata` | Γ£à | single-org | ASF | single-organisation capability (ASF); no vendor choice to make | -| `contract:security-cross-ref` | Γ¥î | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more | +| `contract:tracker` | ✅ | vendor-backed | Atlassian, Fossil, GitHub, SourceHut | 4 backend vendors: Atlassian, Fossil, GitHub, SourceHut | +| `contract:source-control` | ✅ | vendor-backed | Fossil, Git, GitHub, SourceHut, Subversion | 5 backend vendors: Fossil, Git, GitHub, SourceHut, Subversion | +| `contract:change-request` | ✅ | vendor-backed | Atlassian, GitHub, email | 3 backend vendors: Atlassian, GitHub, email | +| `contract:mail-archive` | ✅ | vendor-backed | ASF, Google, SourceHut | 3 backend vendors: ASF, Google, SourceHut | +| `contract:mail-source` | ✅ | vendor-backed | ASF, Google, Maildir | 3 backend vendors: ASF, Google, Maildir | +| `contract:mail-create` | ✅ | vendor-backed | Google, Maildir | 2 backend vendors: Google, Maildir | +| `contract:cve-authority` | ✅ | vendor-backed | CVE.org, Vulnogram | 2 backend vendors: CVE.org, Vulnogram | +| `contract:report-relay` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend | +| `contract:scan-format` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend | +| `contract:project-metadata` | ✅ | single-org | ASF | single-organisation capability (ASF); no vendor choice to make | +| `contract:security-cross-ref` | ❌ | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more | **Per-skill assessment: 0/0 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability. @@ -598,35 +597,35 @@ Organization scope (declared, orthogonal to vendor): . | Substrate tool | Substrate | Harness support | Verdict | |---|---|---|---| -| `agent-guard` | action-guard | Claude Code, Gemini CLI, Kiro, OpenCode | Γ£à portable | -| `agent-isolation` | sandbox | any | Γ£à agnostic | -| `container-gateway` | sandbox | any | Γ£à agnostic | -| `dashboard-generator` | analytics | any | Γ£à agnostic | -| `dev` | framework-dev | any | Γ£à agnostic | -| `egress-gateway` | sandbox | any | Γ£à agnostic | -| `permission-audit` | sandbox | any | Γ£à agnostic | -| `pilot-report-validator` | framework-dev | any | Γ£à agnostic | -| `pr-management-stats` | analytics | any | Γ£à agnostic | -| `preflight-audit` | analytics | any | Γ£à agnostic | -| `privacy-llm` | privacy | any | Γ£à agnostic | -| `probe-templates` | sandbox | any | Γ£à agnostic | -| `reproducible-archive` | release | any | Γ£à agnostic | -| `sandbox-lint` | sandbox | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | Γ£à portable | -| `security-tracker-stats-dashboard` | analytics | any | Γ£à agnostic | -| `setup-preflight` | setup | any | Γ£à agnostic | -| `skill-and-tool-validator` | framework-dev | any | Γ£à agnostic | -| `skill-evals` | framework-dev | any | Γ£à agnostic | -| `skill-reconciler-diff` | framework-dev | any | Γ£à agnostic | -| `skill-token-count` | framework-dev, analytics | any | Γ£à agnostic | -| `spec-inventory` | framework-dev, analytics | any | Γ£à agnostic | -| `spec-loop` | framework-dev | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | Γ£à portable | -| `spec-status-index` | framework-dev, analytics | any | Γ£à agnostic | -| `spec-validator` | framework-dev | any | Γ£à agnostic | -| `symlink-lint` | framework-dev | any | Γ£à agnostic | -| `vendor-neutrality-score` | framework-dev, analytics | any | Γ£à agnostic | -| `vetted-ops` | sandbox | any | Γ£à agnostic | - -Harness ΓåÆ substrate tools it supports: +| `agent-guard` | action-guard | Claude Code, Gemini CLI, Kiro, OpenCode | ✅ portable | +| `agent-isolation` | sandbox | any | ✅ agnostic | +| `container-gateway` | sandbox | any | ✅ agnostic | +| `dashboard-generator` | analytics | any | ✅ agnostic | +| `dev` | framework-dev | any | ✅ agnostic | +| `egress-gateway` | sandbox | any | ✅ agnostic | +| `permission-audit` | sandbox | any | ✅ agnostic | +| `pilot-report-validator` | framework-dev | any | ✅ agnostic | +| `pr-management-stats` | analytics | any | ✅ agnostic | +| `preflight-audit` | analytics | any | ✅ agnostic | +| `privacy-llm` | privacy | any | ✅ agnostic | +| `probe-templates` | sandbox | any | ✅ agnostic | +| `reproducible-archive` | release | any | ✅ agnostic | +| `sandbox-lint` | sandbox | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | ✅ portable | +| `security-tracker-stats-dashboard` | analytics | any | ✅ agnostic | +| `setup-preflight` | setup | any | ✅ agnostic | +| `skill-and-tool-validator` | framework-dev | any | ✅ agnostic | +| `skill-evals` | framework-dev | any | ✅ agnostic | +| `skill-reconciler-diff` | framework-dev | any | ✅ agnostic | +| `skill-token-count` | framework-dev, analytics | any | ✅ agnostic | +| `spec-inventory` | framework-dev, analytics | any | ✅ agnostic | +| `spec-loop` | framework-dev | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | ✅ portable | +| `spec-status-index` | framework-dev, analytics | any | ✅ agnostic | +| `spec-validator` | framework-dev | any | ✅ agnostic | +| `symlink-lint` | framework-dev | any | ✅ agnostic | +| `vendor-neutrality-score` | framework-dev, analytics | any | ✅ agnostic | +| `vetted-ops` | sandbox | any | ✅ agnostic | + +Harness → substrate tools it supports: - **Claude Code** (3): `agent-guard`, `sandbox-lint`, `spec-loop` - **Codex** (2): `sandbox-lint`, `spec-loop` @@ -636,19 +635,18 @@ Harness ΓåÆ substrate tools it supports: - **OpenCode** (3): `agent-guard`, `sandbox-lint`, `spec-loop` - **any harness** (24): `agent-isolation`, `container-gateway`, `dashboard-generator`, `dev`, `egress-gateway`, `permission-audit`, `pilot-report-validator`, `pr-management-stats`, `preflight-audit`, `privacy-llm`, `probe-templates`, `reproducible-archive`, `security-tracker-stats-dashboard`, `setup-preflight`, `skill-and-tool-validator`, `skill-evals`, `skill-reconciler-diff`, `skill-token-count`, `spec-inventory`, `spec-status-index`, `spec-validator`, `symlink-lint`, `vendor-neutrality-score`, `vetted-ops` -**Model endpoint: neutral by construction ΓÇö 4 default-approved endpoint classes across independent trust domains, plus adopter opt-in.** From the [`privacy-llm` registry](../tools/privacy-llm/models.md): the framework keys approval on *endpoint identity*, not on who hosts the model, so no single LLM vendor is privileged. +**Model endpoint: neutral by construction — 4 default-approved endpoint classes across independent trust domains, plus adopter opt-in.** From the [`privacy-llm` registry](../tools/privacy-llm/models.md): the framework keys approval on *endpoint identity*, not on who hosts the model, so no single LLM vendor is privileged. | Default-approved endpoint class | Examples | |---|---| | Claude Code itself | The agent invoking the skill | -| *.apache.org-hosted endpoints | An ASF-hosted inference endpoint at e.g. `inference.apache.org`; an in-tracker endpoint at `.apache.org/llm/`. **Not** `llm.apache.org` ΓÇö see carve-outs | +| *.apache.org-hosted endpoints | An ASF-hosted inference endpoint at e.g. `inference.apache.org`; an in-tracker endpoint at `.apache.org/llm/`. **Not** `llm.apache.org` — see carve-outs | | Local-only inference | Ollama serving a local model, vLLM on the user's workstation, llama.cpp embedded in a CLI helper | | Air-gapped on-prem | A PMC-hosted inference appliance on a private VLAN | -Every other endpoint is **opt-in** ΓÇö the adopting project's security team declares it in `/privacy-llm.md` (endpoint URL, data-residency contract, approver), so the choice is local and audited. - - +Every other endpoint is **opt-in** — the adopting project's security team declares it in `/privacy-llm.md` (endpoint URL, data-residency contract, approver), so the choice is local and audited. + ### What the number means From d25b1a5565aa7b1f2996ea911d29873b894da0d5 Mon Sep 17 00:00:00 2001 From: Vardhman Gupta Date: Wed, 23 Sep 2026 13:31:45 +0530 Subject: [PATCH 3/3] fix: sync skill counts in vendor-neutrality for CI --- docs/vendor-neutrality.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md index d00e2f269..cd8692761 100644 --- a/docs/vendor-neutrality.md +++ b/docs/vendor-neutrality.md @@ -581,15 +581,15 @@ generated block below. | `contract:project-metadata` | ✅ | single-org | ASF | single-organisation capability (ASF); no vendor choice to make | | `contract:security-cross-ref` | ❌ | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more | -**Per-skill assessment: 0/0 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability. +**Per-skill assessment: 75/75 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability. | Skill neutrality | Count | |---|---| -| capability-pure (names no backend) | 0 | -| portable (named backends are swappable) | 0 | +| capability-pure (names no backend) | 15 | +| portable (named backends are swappable) | 60 | | vendor-coupled (sole-backend dependency) | 0 | -Organization scope (declared, orthogonal to vendor): . +Organization scope (declared, orthogonal to vendor): ASF = 14, agnostic = 61. **LLM / agent-integration neutrality**