ai-capability-framework 1.0.0-rc.3 → 1.0.0

package/docs/providers.md

@@ -1,33 +1,34 @@
 # Provider Foundation
 
-AICF is a provider-agnostic AI capability framework. It turns application
-functions, data access, and workflows into typed, permissioned, versioned,
-observable, and evaluated capabilities that can be exposed to AI models and
-agent frameworks without making any provider schema the source of truth.
-
-OpenAI is one adapter, not the architecture. The canonical contract is still
-the AICF capability manifest plus runtime policy, lifecycle, and model-safe
-result envelopes.
-
-If you are new to provider adapters, read the
-[OpenAI walkthrough](openai-walkthrough.md) first. The same mental model applies
-to the other provider runtimes and framework bridges: export a routed slice,
-map provider calls back through bindings, validate with AICF, and keep commit
-host-controlled.
+AICF is a provider-agnostic AI capability framework. It turns application functions,
+data access, and workflows into typed, permissioned, versioned, observable, and
+evaluated capabilities that can be exposed to AI models and agent frameworks without
+making any provider schema the source of truth.
+
+OpenAI is one adapter, not the architecture. The canonical contract is still the AICF
+capability manifest plus runtime policy, lifecycle, and model-safe result envelopes.
+
+If you are new to provider adapters, start with the
+[provider-neutral quickstart](getting-started/provider-neutral-quickstart.md) and then
+use [Choose a Runtime](providers/choose-a-runtime.md). The same mental model applies to
+every provider runtime and framework bridge: export a routed slice, map provider calls
+back through bindings, validate with AICF, and keep commit host-controlled. The
+[OpenAI walkthrough](openai-walkthrough.md) remains a concrete example, not the default
+architecture.
 
 ## Provider Types
 
-- Direct model runtimes: OpenAI Responses, Anthropic Claude Messages, and Google
-  Gemini GenerateContent.
+- Direct model runtimes: OpenAI Responses, Anthropic Claude Messages, and Google Gemini
+  GenerateContent.
 - Framework bridges: Vercel AI SDK and LangChain/LangGraph.
 - Interoperability surfaces: MCP descriptors/server runtime and Semantic
   Kernel-compatible MCP/OpenAPI metadata.
-- Descriptor-only conformance: the provider conformance matrix verifies that a
-  routed slice maps consistently across supported targets.
+- Descriptor-only conformance: the provider conformance matrix verifies that a routed
+  slice maps consistently across supported targets.
 
-Provider modules are optional subpath imports. Root, runtime, and shared
-provider imports must work without Anthropic, Google, AI SDK, LangChain, MCP SDK,
-Semantic Kernel, OpenAI, AWS, or observability SDK packages installed.
+Provider modules are optional subpath imports. Root, runtime, and shared provider
+imports must work without Anthropic, Google, AI SDK, LangChain, MCP SDK, Semantic
+Kernel, OpenAI, AWS, or observability SDK packages installed.
 
 ```ts
 import { createProviderToolNameMap } from "ai-capability-framework/providers";
@@ -41,15 +42,14 @@ import { exportSemanticKernelOpenApiPlugin } from "ai-capability-framework/provi
 
 ## Shared Behavior
 
-The shared provider layer provides deterministic provider-safe tool names,
-collision diagnostics, reverse lookup through binding maps, schema
-normalization, canonical provider call/result summaries, optional dependency
-loading, and an execution helper that delegates read and prepare calls to
-`AicfToolExecutor`.
+The shared provider layer provides deterministic provider-safe tool names, collision
+diagnostics, reverse lookup through binding maps, schema normalization, canonical
+provider call/result summaries, optional dependency loading, and an execution helper
+that delegates read and prepare calls to `AicfToolExecutor`.
 
-Provider SDK validation does not replace AICF validation. Provider descriptors
-are generated from routed AICF capability slices, then all tool calls map back
-through bindings to the original capability ID and input schema.
+Provider SDK validation does not replace AICF validation. Provider descriptors are
+generated from routed AICF capability slices, then all tool calls map back through
+bindings to the original capability ID and input schema.
 
 ## Safety Boundary
 
@@ -58,19 +58,24 @@ AICF remains the policy and action authority:
 - commit capabilities are not exported to models by default;
 - read and prepare calls execute through AICF validation, policy, lifecycle, and
   model-safe envelopes;
-- optional AICF controls can deny provider export, apply read-only mode, and
-  enforce provider-loop budgets;
-- commit remains host-controlled through `AicfActionLifecycleManager` after a
-  stored prepared action, approval, idempotency, and audit checks;
+- optional AICF controls can deny provider export, apply read-only mode, and enforce
+  provider-loop budgets;
+- commit remains host-controlled through `AicfActionLifecycleManager` after a stored
+  prepared action, approval, idempotency, and audit checks;
 - raw prompts, raw user messages, provider request/response payloads, traces,
   credentials, and private diagnostics are not logged by default;
 - ambiguous provider/runtime behavior fails closed.
 
-Live tests are opt-in. Normal package checks use mock clients, fake SDK
-factories, descriptor exports, and synthetic fixtures.
+Live tests are opt-in. Normal package checks use mock clients, fake SDK factories,
+descriptor exports, and synthetic fixtures.
 
 ## Guides And Examples
 
+- [Choose a runtime](providers/choose-a-runtime.md)
+- [Provider-neutral quickstart](getting-started/provider-neutral-quickstart.md)
+- [OpenAI quickstart](getting-started/openai-quickstart.md)
+- [Anthropic quickstart](getting-started/anthropic-quickstart.md)
+- [Gemini quickstart](getting-started/gemini-quickstart.md)
 - [OpenAI Responses runtime](openai-runtime.md)
 - [Anthropic Claude runtime](anthropic-runtime.md)
 - [Google Gemini runtime](gemini-runtime.md)
@@ -80,9 +85,9 @@ factories, descriptor exports, and synthetic fixtures.
 - [Semantic Kernel compatibility](semantic-kernel-runtime.md)
 - [Provider conformance](providers/conformance.md)
 
-Grouped public examples live under `examples/providers/`. They are README-only
-by design: no credentials, raw provider payloads, live transcripts, or local
-runtime state are included.
+Grouped public examples live under `examples/providers/`. They are README-only by
+design: no credentials, raw provider payloads, live transcripts, or local runtime state
+are included.
 
 ## Release Checks
 

package/docs/public/license-exceptions.md

@@ -0,0 +1,187 @@
+# Dependency License Exceptions
+
+AICF uses MIT for the public framework and accepts common permissive dependency licenses
+by default. The release gate blocks unknown, copyleft, source-available, and unlicensed
+dependency metadata unless maintainers document an explicit exception here.
+
+The default allow-list is:
+
+- MIT
+- Apache-2.0
+- BSD-2-Clause
+- BSD-3-Clause
+- ISC
+- CC0-1.0
+- Unlicense
+- BlueOak-1.0.0
+
+Disallowed-by-default license families include GPL, AGPL, LGPL, SSPL, BUSL, unknown
+licenses, and `UNLICENSED`.
+
+The `npm run check:licenses` gate reads the package lockfiles and the JSON block below.
+Exceptions must be exact by package, version, license, and package scope. Stale or
+malformed exception records fail the gate.
+
+```json
+{
+  "exceptions": [
+    {
+      "package": "argparse",
+      "version": "2.0.1",
+      "license": "Python-2.0",
+      "scope": "root",
+      "reason": "Transitive build and validation dependency; license reviewed as compatible for public package use.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Do not copy package source into AICF docs or examples."
+    },
+    {
+      "package": "lightningcss",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Transitive TypeDoc build dependency; weak-copyleft terms are isolated to the dependency package.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Do not vendor or modify dependency source in this repository."
+    },
+    {
+      "package": "lightningcss-android-arm64",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-darwin-arm64",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-darwin-x64",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-freebsd-x64",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-linux-arm-gnueabihf",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-linux-arm64-gnu",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-linux-arm64-musl",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-linux-x64-gnu",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-linux-x64-musl",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-win32-arm64-msvc",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "lightningcss-win32-x64-msvc",
+      "version": "1.32.0",
+      "license": "MPL-2.0",
+      "scope": "root",
+      "reason": "Optional platform package for the reviewed lightningcss dependency.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Keep usage limited to dependency installation; do not vendor source."
+    },
+    {
+      "package": "tslib",
+      "version": "2.8.1",
+      "license": "0BSD",
+      "scope": "root",
+      "reason": "Transitive TypeScript helper dependency; 0BSD is public-domain-like and compatible with MIT distribution.",
+      "approved_by": "AICF maintainers",
+      "approved_at": "2026-06-08",
+      "review_by": "2027-06-08",
+      "constraints": "Review again if the dependency is vendored or materially modified."
+    }
+  ]
+}
+```
+
+Host applications and downstream distributors remain responsible for their own legal
+review.

package/docs/public/npm-release-preflight.md

@@ -0,0 +1,112 @@
+# npm Release Preflight
+
+Run this preflight before pushing a release tag. It checks the public npm package
+boundary and makes the release operator verify ownership and publishing setup.
+
+## Packages
+
+| Package                   | Expected scope          | Access | Release policy                                                            |
+| ------------------------- | ----------------------- | ------ | ------------------------------------------------------------------------- |
+| `ai-capability-framework` | unscoped public package | public | Published from the release tag after final certification.                 |
+| `@aicf/agent-skills`      | `@aicf` npm scope       | public | Published from the same release tag and version, before the root package. |
+
+Both packages must use the same version. Release tags must match that version exactly:
+package version `1.0.0` uses tag `v1.0.0`.
+
+## Ownership
+
+AICF maintainers own release approval. Before tagging, the release operator must verify
+npm ownership directly:
+
+```bash
+npm whoami
+npm owner ls ai-capability-framework
+npm owner ls @aicf/agent-skills
+```
+
+For the first `@aicf/agent-skills` release, the `@aicf` npm scope and package-level
+trusted publishing setup must exist before the tag is pushed.
+
+## Dist Tags
+
+- Prerelease versions with a hyphen, such as `1.0.0-rc.6`, publish with `next`.
+- Stable versions, such as `1.0.0`, publish with `latest`.
+- Do not move `latest` to a prerelease intentionally. If a prerelease lands on `latest`,
+  fix the dist tags before announcing the release.
+
+## Trusted Publishing
+
+GitHub Actions publishing must use npm Trusted Publishing with OIDC. Do not commit npm
+tokens, one-time passwords, local `.npmrc` auth lines, or long-lived release
+credentials. The publish workflow must keep `id-token: write` and publish only from `v*`
+tags that point at `origin/main`.
+
+AICF uses npm Trusted Publishing / GitHub OIDC for both public packages:
+
+- `ai-capability-framework`
+- `@aicf/agent-skills`
+
+## Preflight Commands
+
+See [Final Certification Matrix](../public-framework/final-certification-matrix.md) for
+the complete local command and workflow gate.
+
+Run the final matrix and local metadata/registry preflight:
+
+```bash
+npm run check:final-matrix
+```
+
+```bash
+npm run check:release-tag
+```
+
+```bash
+npm run release:preflight:npm
+```
+
+For final manual release review, use strict mode:
+
+```bash
+node scripts/check-npm-release-preflight.mjs --strict
+```
+
+The default command verifies package metadata, target dist tag, package availability,
+and whether the target local versions are already published. It warns when npm login or
+owner checks cannot be completed. Strict mode fails on missing npm auth, missing owner
+verification, or missing scoped package setup.
+
+Run both package publish dry-runs with the computed dist tag:
+
+```bash
+npm run release:publish:dry
+```
+
+This command does not publish. It runs root and `@aicf/agent-skills` dry-runs with
+`--access public`.
+
+## Version Availability
+
+Before tagging, verify the target versions are unpublished:
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+npm view "ai-capability-framework@${VERSION}" version
+npm view "@aicf/agent-skills@${VERSION}" version
+```
+
+If either command returns a version, bump both package versions and refresh lockfiles
+before tagging. npm versions are immutable.
+
+## Rollback And Deprecation
+
+Do not delete a published version as a normal rollback strategy. If a release is bad,
+publish a fixed version and, when appropriate, deprecate the bad version with a concise
+public-safe reason:
+
+```bash
+npm deprecate ai-capability-framework@<version> "Use <fixed-version>."
+npm deprecate @aicf/agent-skills@<version> "Use <fixed-version>."
+```
+
+For dist-tag mistakes, move the tag to the intended version with `npm dist-tag add`.

package/docs/public-framework/compatibility-policy.md

@@ -1,20 +1,19 @@
 # Compatibility Policy
 
-AICF treats exported TypeScript APIs, schemas, CLI commands, public examples,
-and documented subpath imports as public compatibility surfaces.
+AICF treats exported TypeScript APIs, schemas, CLI commands, public examples, and
+documented subpath imports as public compatibility surfaces.
 
-Breaking changes include manifest schema breaking changes, required input
-changes, removed exports, public error-code removals or meaning changes,
-lifecycle/risk semantic changes, weakened runtime safety behavior, provider
-descriptor changes that alter generated tools, eval-result schema changes,
-control-plane API changes, model-exposed commit paths, or package boundary
-changes that require optional SDKs from root imports.
+Breaking changes include manifest schema breaking changes, required input changes,
+removed exports, public error-code removals or meaning changes, lifecycle/risk semantic
+changes, weakened runtime safety behavior, provider descriptor changes that alter
+generated tools, eval-result schema changes, control-plane API changes, model-exposed
+commit paths, or package boundary changes that require optional SDKs from root imports.
 
-Minor changes include new optional manifest fields, new isolated subpaths, new
-provider adapters, new eval scorers, new warnings that do not fail by default,
-new docs, and new examples.
+Minor changes include new optional manifest fields, new isolated subpaths, new provider
+adapters, new eval scorers, new warnings that do not fail by default, new docs, and new
+examples.
 
-Patch changes include bug fixes, docs corrections, internal refactors, and
-provider compatibility fixes that do not alter public contracts.
+Patch changes include bug fixes, docs corrections, internal refactors, and provider
+compatibility fixes that do not alter public contracts.
 
 When in doubt, add compatibility tests and document migration guidance.

package/docs/public-framework/deprecation-policy.md

@@ -1,12 +1,12 @@
 # Deprecation Policy
 
-Deprecated capabilities, APIs, docs, or commands should remain available long
-enough for public users to migrate.
+Deprecated capabilities, APIs, docs, or commands should remain available long enough for
+public users to migrate.
 
-Deprecated public APIs and manifest fields should warn or remain documented for
-at least one minor release before removal unless a security issue requires
-immediate denial. Deprecated manifest fields must remain loadable until the next
-major version when practical.
+Deprecated public APIs and manifest fields should warn or remain documented for at least
+one minor release before removal unless a security issue requires immediate denial.
+Deprecated manifest fields must remain loadable until the next major version when
+practical.
 
 Deprecation guidance should include:
 
@@ -16,5 +16,5 @@ Deprecation guidance should include:
 - migration notes;
 - tests that preserve compatibility until removal.
 
-Safety fixes may deny unsafe behavior immediately, but should still provide
-actionable diagnostics.
+Safety fixes may deny unsafe behavior immediately, but should still provide actionable
+diagnostics.

package/docs/public-framework/final-certification-matrix.md

@@ -0,0 +1,104 @@
+# Final Certification Matrix
+
+The final certification matrix is the local release-review gate for AICF v1 readiness.
+It is not a legal certification, audit opinion, security guarantee, or npm publish
+action. It checks that the public repository, root package, `@aicf/agent-skills`,
+workflows, docs, package contents, and release dry-run commands line up.
+
+Run the matrix directly with:
+
+```bash
+npm run check:final-matrix
+```
+
+It is also part of:
+
+```bash
+npm run check:certification
+```
+
+## Required Local Commands
+
+Before a release tag, these non-live commands must pass from the repository root:
+
+```bash
+npm ci
+npm run format:check
+npm run build
+npm run typecheck
+npm test
+npm run validate
+npm run conformance
+npm run check:package
+npm run check:package-public
+npm run check:workspace-public
+npm run check:release-install
+npm run check:metadata
+npm run check:licenses
+npm run check:final-matrix
+npm run check:release-tag
+npm run skills:check
+npm run check:certification
+```
+
+Agent skills must also pass their package-local checks:
+
+```bash
+npm --prefix agent-skills ci
+npm --prefix agent-skills run validate
+npm --prefix agent-skills run test
+npm --prefix agent-skills run pack:dry
+npm --prefix agent-skills run check
+```
+
+## Required Workflows
+
+The matrix asserts these workflows exist and contain the expected gates:
+
+- CI with Node 20.x, 22.x, and 24.x.
+- Validate.
+- Security with audit, license, secret, package public, and workspace public checks.
+- Docs.
+- Release Dry Run.
+- Publish.
+- Agent skills checks through CI and final certification.
+
+## Package Artifact Rules
+
+Root and agent-skills package dry-runs must not include `.git/`, `node_modules/`,
+`_private/`, `.aicf/`, raw prompts, raw traces, raw provider payloads, logs, local
+backups, generated docs, source archives, package archives, coverage output, or
+unreviewed scratch files.
+
+Create source review archives with the release script:
+
+```bash
+npm run archive:source
+npm run check:source-archive
+```
+
+Do not zip the working directory manually.
+
+## Publish Dry-Run Review
+
+The publish dry-run command computes the npm dist tag from the package version and runs
+both package dry-runs with public access:
+
+```bash
+npm run release:publish:dry
+```
+
+Prereleases such as `1.0.0-rc.6` use `next`. Stable releases use `latest`. This command
+does not publish.
+
+## Manual Acceptance
+
+Before stable v1, maintainers should also review README positioning, MIT license
+consistency, provider-neutral onboarding, at least one non-OpenAI quickstart, agent
+skills install docs, npm ownership, trusted publishing, source archive contents, opt-in
+live test boundaries, and root import optional-dependency isolation.
+
+- GitHub repository About/description says AICF is a provider-agnostic governed AI
+  capability framework.
+- GitHub topics include at least: ai, agents, tool-calling, evals, governance,
+  model-context-protocol, langchain, gemini, anthropic, openai, typescript.

package/docs/public-framework/license-decision.md

@@ -0,0 +1,20 @@
+# License Decision
+
+AICF uses the MIT license for the v1 public release.
+
+This is an intentional project decision. The root framework package,
+`@aicf/agent-skills`, the Codex plugin metadata, tracked skill frontmatter, README text,
+package metadata, and release checks must all agree on MIT unless maintainers make an
+explicit future license change.
+
+MIT keeps the framework easy to adopt, fork, inspect, and embed in application stacks.
+AICF still expects host applications to own their own legal review, security review,
+compliance obligations, provider terms, and production risk decisions.
+
+The release certification gate includes `npm run check:metadata` to confirm the license
+and public identity are consistent before a v1 tag is published.
+
+Dependency licenses are checked separately with `npm run check:licenses`. That gate uses
+the root and `agent-skills` lockfiles, allows common permissive licenses by default, and
+requires explicit public review records for any exception in
+[Dependency License Exceptions](../public/license-exceptions.md).