ai-capability-framework 1.0.0-rc.1 → 1.0.0-rc.5

package/CHANGELOG.md

@@ -2,17 +2,113 @@
 
 All notable public changes to AI Capability Framework are documented here.
 
+## Unreleased
+
+- Prepared the `1.0.0-rc.5` release candidate and made `@aicf/agent-skills` a
+  first-class same-version npm artifact in certification, CI, release dry-run, and
+  trusted-publishing workflows.
+- Added the final v1.0 certification gate with `check:public`, `check:certification`,
+  public certification docs, workflow hardening, and release-readiness assertions for
+  v1.0-ready release notes.
+- Added public repository release-readiness hardening with CI, docs, security, and
+  release dry-run workflows plus lint, conformance, governance-gate, package, source
+  archive, and secret-scan checks.
+- Added a first-time developer onboarding pass with a simplified README, start-here
+  guide, OpenAI walkthrough, glossary, and clearer eval/runtime navigation.
+- Added the `ai-capability-framework/runtime` subpath for deterministic runtime context,
+  redaction, capability routing, policy brokering, handler registry, no-model
+  read/prepare execution, host-controlled action lifecycle, in-memory reference stores,
+  audit events, and runtime result envelopes.
+- Added the optional `ai-capability-framework/openai` subpath for a bounded
+  non-streaming OpenAI Responses loop with caller-provided clients, routed read/prepare
+  tools, R2 executor integration, and model-safe tool envelopes.
+- Added optional observability, Langfuse, live eval, Promptfoo export, and EvalOps
+  subpaths with metadata-only tracing defaults, tracer adapters, dependency-free
+  Braintrust/OpenAI eval export helpers, and mock-driven tests.
+- Added the optional `ai-capability-framework/aws` subpath for DynamoDB runtime stores,
+  canonical audit ledger stores, controls, control-plane state, budget usage, Step
+  Functions approval handoff, EventBridge/CloudWatch publishing, KMS redaction refs, and
+  fake AWS test clients.
+- Added the optional `ai-capability-framework/mcp-server` subpath and OpenAI Agents SDK
+  bridge for executor-backed read/prepare interoperability.
+- Added a public runtime support/billing mock example plus action lifecycle, policy
+  broker, and release-hardening docs and scripts.
+- Added the `ai-capability-framework/providers` shared foundation for provider-neutral
+  tool naming, schema normalization, call parsing, safe result formatting, optional
+  dependency loading, and executor-backed read/prepare calls.
+- Added the optional `ai-capability-framework/providers/anthropic` subpath for a bounded
+  Claude Messages tool-use loop with caller-provided clients and AICF-backed
+  read/prepare execution.
+- Added the optional `ai-capability-framework/providers/gemini` subpath for a bounded
+  Gemini GenerateContent function-calling loop with caller-provided clients and
+  AICF-backed read/prepare execution.
+- Added the optional `ai-capability-framework/providers/ai-sdk` subpath for a Vercel AI
+  SDK tool bridge and host-supplied `generateText`/`streamText` wrappers with
+  AICF-backed read/prepare execution.
+- Added the optional `ai-capability-framework/providers/langchain` subpath for LangChain
+  tools and a host-supplied LangGraph `ToolNode` bridge with AICF-backed read/prepare
+  execution.
+- Added the optional `ai-capability-framework/providers/mcp` subpath for hardened MCP
+  descriptors, annotations, security summaries, and tool-call parsing from routed AICF
+  capability slices.
+- Added the optional `ai-capability-framework/providers/conformance` subpath and
+  `aicf providers` CLI group for descriptor-only cross-provider conformance checks.
+- Added the canonical `ai-capability-framework/conformance` subpath, `aicf conformance`
+  CLI group, conformance schemas, richer F7 reports, and provider target matrix output
+  while preserving provider conformance aliases.
+- Added grouped public provider examples, provider release scripts, and provider
+  package-readiness assertions for multi-vendor release review.
+- Added the optional `ai-capability-framework/providers/semantic-kernel` subpath for MCP
+  guidance plus OpenAPI/plugin metadata exports for Semantic Kernel-compatible hosts.
+- Added the `ai-capability-framework/governance` subpath and `aicf governance` CLI group
+  for lifecycle transition checks, risk compilation, compatibility diffs, and registry
+  impact analysis.
+- Added the governance gate APIs and `aicf gate` CLI command for CI-friendly validation,
+  risk, lifecycle, compatibility, impact, eval coverage, security-pack coverage,
+  configured provider conformance, and public artifact hygiene checks.
+- Added the optional `ai-capability-framework/control-plane` subpath and a
+  credential-free local reference app for reviewing capabilities, governance status,
+  eval/security/conformance coverage, redacted ledgers, approvals, controls, replay
+  metadata, and evidence exports.
+- Added the optional `ai-capability-framework/audit` subpath with schema-valid policy
+  decision, action, approval, and idempotency ledger records plus in-memory reference
+  stores and runtime ledger hooks.
+- Added the optional `ai-capability-framework/security` subpath for trust segments,
+  taint/provenance metadata, provider/trace redaction, and retention policy evaluation.
+- Added the optional `ai-capability-framework/memory` subpath for governed host-owned
+  memory and preference summaries, use-case/scope exposure checks, and conversion to
+  security/runtime context.
+- Added the optional `ai-capability-framework/evidence` subpath and
+  `aicf evidence export` CLI for public-safe JSON/Markdown evidence packs with required
+  disclaimers and explicit coverage gaps.
+- Added the optional `ai-capability-framework/provenance` subpath for public-safe
+  generated-content provenance metadata, strict schemas, adapter hooks, docs, and a
+  synthetic refs-and-hashes support fixture.
+- Added public documentation and developer-experience hardening with root
+  governance/conduct/roadmap docs, grouped docs navigation, numbered examples, TypeDoc
+  tooling, docs checks, and package-readiness assertions.
+- Added the optional `ai-capability-framework/controls` subpath for runtime kill
+  switches, circuit breaker evaluation, per-run budgets, local control CLI commands,
+  controls schemas, docs, and runtime/provider enforcement hooks.
+- Added the optional `ai-capability-framework/replay` subpath for sanitized runtime
+  replay, policy/router/tool-validation simulation, trace-to-golden eval drafting,
+  replay schemas, CLI commands, and a public-safe support replay fixture.
+- Added the optional `ai-capability-framework/security-packs` subpath with built-in
+  capability-aware security test packs, coverage reporting, public-safe generated
+  security cases, Promptfoo red-team config export, schemas, CLI commands, and docs.
+- Kept provider/model calls, production storage, and model-exposed commit out of the
+  Core/runtime boundary except for the optional OpenAI subpath.
+
 ## 1.0.0-rc.1 - 2026-06-03
 
 1.0 spec-complete release candidate.
 
-- Promoted public manifests and eval result fixtures to
-  `schema_version: "1.0"`.
+- Promoted public manifests and eval result fixtures to `schema_version: "1.0"`.
 - Made the spec normative and explicit about the no-execution boundary.
 - Added migration, host responsibility, and interoperability guidance.
 - Added a second synthetic domain and conformance fixtures for external review.
-- Added no-model-call adapters for Anthropic Claude, Google Gemini, Vercel AI
-  SDK, Model Context Protocol, LangChain/LangGraph, and Semantic Kernel.
+- Added no-model-call adapters for Anthropic Claude, Google Gemini, Vercel AI SDK, Model
+  Context Protocol, LangChain/LangGraph, and Semantic Kernel.
 - Enabled public npm release-candidate publishing while keeping the no-execution
   framework boundary.
 
@@ -24,14 +120,14 @@ Initial public v0.1 release candidate.
   manifests.
 - Added synthetic support examples for read, prepare-only write, commit, policy,
   approval, refusal, and eval boundaries.
-- Added a TypeScript core library and `aicf` CLI for loading, validating,
-  inspecting, deciding, OpenAI tool export, and deterministic eval scoring.
-- Added deterministic policy and lifecycle decision APIs without executing
-  capabilities or performing side effects.
-- Added a no-model-call OpenAI Responses adapter for exporting function tool
-  definitions and parsing tool calls.
+- Added a TypeScript core library and `aicf` CLI for loading, validating, inspecting,
+  deciding, OpenAI tool export, and deterministic eval scoring.
+- Added deterministic policy and lifecycle decision APIs without executing capabilities
+  or performing side effects.
+- Added a no-model-call OpenAI Responses adapter for exporting function tool definitions
+  and parsing tool calls.
 - Added an API-key-free eval runner for scoring candidate result fixtures.
-- Added release-readiness package checks, public API docs, CI validation, and
-  public repository boundary guidance.
+- Added release-readiness package checks, public API docs, CI validation, and public
+  repository boundary guidance.
 
 This release was GitHub-release-ready only and was not published to npm.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+AI Capability Framework is a public project for building safer AI-accessible application
+capabilities. Participation should stay practical, respectful, and focused on improving
+the framework.
+
+## Expected Behavior
+
+- Be direct and constructive.
+- Assume contributors are trying to improve the public project.
+- Keep discussions focused on code, docs, examples, tests, and framework safety.
+- Use synthetic examples and public-safe language.
+- Respect maintainers when they protect the public repository boundary.
+
+## Unacceptable Behavior
+
+- Publishing credentials, private data, raw prompts, provider payloads, traces, customer
+  records, or internal account details.
+- Harassment, personal attacks, threats, or discriminatory language.
+- Repeatedly pushing changes that bypass safety, validation, or release checks.
+- Sharing private drafts or unreleased planning material in public files.
+
+## Reporting
+
+Report security issues through [SECURITY.md](SECURITY.md). For conduct issues, open a
+GitHub issue only if it can be discussed publicly without exposing private information.
+Otherwise contact the maintainers through the repository owner profile.
+
+Maintainers may remove public content, close issues, or block participation to protect
+contributors and the public repository boundary.

package/CONTRIBUTING.md

@@ -1,18 +1,17 @@
 # Contributing
 
-Thanks for improving AI Capability Framework. This repository is public, so
-every tracked change must be safe to publish.
+Thanks for improving AI Capability Framework. This repository is public, so every
+tracked change must be safe to publish.
 
 ## Public-Safe Contributions
 
-- Use synthetic examples with fake IDs, fake tenants, fake users, and
-  `example.com` addresses.
-- Do not commit credentials, account IDs, customer records, raw prompts, raw
-  traces, provider payloads, private source documents, generated exports, or
-  local experiments.
+- Use synthetic examples with fake IDs, fake tenants, fake users, and `example.com`
+  addresses.
+- Do not commit credentials, account IDs, customer records, raw prompts, raw traces,
+  provider payloads, private source documents, generated exports, or local experiments.
 - Keep private notes and drafts in `_private/` or another ignored path.
-- Never copy from `_private/` into tracked files verbatim. Distill public
-  guidance in new wording.
+- Never copy from `_private/` into tracked files verbatim. Distill public guidance in
+  new wording.
 
 ## Development Workflow
 
@@ -28,14 +27,48 @@ Common commands:
 npm run generate:types
 npm run check:generated
 npm run build
+npm run docs:build
 npm test
 npm run validate
 npm run check:package
 npm run check
 ```
 
-Run `npm run generate:types` whenever schemas change. Generated public manifest
-types under `src/generated/` must stay current.
+Run `npm run generate:types` whenever schemas change. Generated public manifest types
+under `src/generated/` must stay current.
+
+Use `npm run lint` for repository readiness checks, `npm run conformance` for
+descriptor/mock provider conformance, and `npm run gate:examples` for the deterministic
+governance gate over public examples.
+
+## Optional Live Integration Tests
+
+Normal tests use mocks, descriptor exports, and synthetic fixtures. Live tests are
+opt-in only and require explicit environment variables such as `RUN_REAL_OPENAI=1`,
+`RUN_LIVE_ANTHROPIC=1`, `RUN_LIVE_GEMINI=1`, or `RUN_AWS_INTEGRATION=1`. Do not add
+credentials, account IDs, tenant IDs, raw provider payloads, or transcripts to tracked
+files.
+
+## Documentation Contributions
+
+- Use public-safe fake data and `example.com` only.
+- Include commands and expected output excerpts for walkthroughs.
+- State when examples make no live provider calls by default.
+- Keep generated TypeDoc output in ignored `generated-docs/`; do not commit it.
+- Run `npm run docs:build` after changing docs, examples, or public navigation.
+
+For artifacts:
+
+```bash
+npm pack
+npm run archive:source
+npm run check:source-archive
+```
+
+Use `npm pack` for npm package review and `npm run archive:source` for public source
+review. Do not zip the working directory manually; raw workspace ZIPs can include
+`.git/`, dependencies, generated output, private notes, logs, traces, raw prompts,
+provider payloads, or Office/PDF exports.
 
 ## Pull Requests
 
@@ -43,14 +76,39 @@ Before opening a pull request:
 
 - Run `npm run check`.
 - Confirm examples are public-safe and synthetic.
-- Confirm `_private/`, traces, prompts, provider payloads, generated local docs,
-  packed tarballs, and local-only files are not tracked.
-- Use `git status --short --ignored` to confirm private material remains
-  ignored.
+- Confirm `_private/`, traces, prompts, provider payloads, generated local docs, packed
+  tarballs, and local-only files are not tracked.
+- Use `git status --short --ignored` to confirm private material remains ignored.
 - Use `git ls-files` to inspect the tracked public surface.
 
+## Changelog And Release Notes
+
+Public behavior, docs, examples, CLI commands, package scripts, schemas, and exported
+APIs should update `CHANGELOG.md`. Keep release notes concise and public-safe. Use
+`docs/release.md` for the release checklist and
+`docs/public-framework/release-process.md` for the public release process.
+
+## Provider Adapters
+
+Provider adapters must stay behind optional subpaths unless maintainers approve a
+boundary change. Do not add provider SDKs to root imports. Descriptor exports and
+runtime loops must preserve AICF validation, policy, lifecycle, model-safe envelopes, no
+raw provider payload retention, and no model-exposed commit tools.
+
+## Security Packs
+
+Security-pack changes must use synthetic public-safe text, update generated or assigned
+coverage where relevant, and avoid claims of certification, legal advice, security
+guarantees, or compliance attestation.
+
+## Manifest Fields
+
+Add manifest fields only when they are optional or have a migration plan. Schema changes
+require generated types, validation updates, examples, docs, and tests. Required-field
+additions, removed meanings, and weakened safety semantics are breaking changes.
+
 ## Scope
 
-AICF 1.0 is a no-execution framework. Contributions should not add model calls,
-handler registries, action stores, approval runtimes, or side effects unless a
-future roadmap explicitly changes that boundary.
+AICF is not an agent framework. It is a governed capability layer for AI-accessible
+application functionality. Models propose; applications validate, authorize, execute,
+and audit. Contributions should reinforce that boundary.

package/GOVERNANCE.md

@@ -0,0 +1,59 @@
+# Project Governance
+
+AI Capability Framework is maintained as a public framework. The maintainers prioritize
+safety boundaries, public documentation quality, and deterministic tests over feature
+breadth.
+
+## Maintainer Roles
+
+- Release maintainers own npm/GitHub release readiness, tags, changelog checks, package
+  contents, and trusted publishing.
+- Security maintainers review vulnerability reports, unsafe public artifacts,
+  security-pack changes, provider boundary changes, and release mitigations.
+- Technical maintainers review API, schema, runtime, provider, governance, and example
+  changes for compatibility and test coverage.
+
+One person may hold multiple roles. Role assignment is by maintainer consensus.
+
+## Maintainer Responsibilities
+
+- Keep the public package free of private drafts, credentials, raw traces, raw prompts,
+  provider payloads, and local artifacts.
+- Preserve the framework boundary: AICF is not an agent framework. It is a governed
+  capability layer for AI-accessible application functionality.
+- Review changes for public API compatibility, package hygiene, and no-model-exposed
+  commit behavior.
+- Require tests and docs for public API, schema, CLI, provider, runtime, governance, or
+  example changes.
+
+## Decision Process
+
+Public changes should be small enough to review, include tests where behavior changes,
+and update docs when they affect user understanding. New integrations must stay isolated
+behind optional subpaths unless maintainers explicitly change the architecture.
+
+Models propose; applications validate, authorize, execute, and audit. Proposed changes
+should reinforce that boundary.
+
+Security-sensitive changes require explicit maintainer review before release. Examples
+include model-exposed tools, action lifecycle behavior, approval or idempotency
+semantics, provider payload handling, MCP server behavior, policy adapters, controls,
+audit/evidence records, and public artifact rules.
+
+## Release Approval
+
+Release candidates are gated by the repository checks in
+[docs/release.md](docs/release.md), package dry-run inspection, and public artifact
+hygiene checks. npm publishing uses trusted publishing from GitHub Actions for tagged
+releases only.
+
+Release approval requires a clean public worktree, passing CI, passing package and
+source artifact checks, reviewed changelog/release notes, and a version tag that matches
+`package.json`.
+
+## Deprecation Process
+
+Deprecated APIs, schemas, commands, docs, examples, or compatibility aliases should
+include a replacement path, migration note, and expected removal window when known.
+Deprecated behavior remains loadable for at least one minor release unless a security
+fix requires immediate denial.