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

package/docs/public-framework/release-process.md

@@ -1,33 +1,63 @@
 # Release Process
 
-AICF releases are public npm and GitHub artifacts. Release candidates must pass
-the checks in [Release checklist](../release.md).
+AICF releases are public npm and GitHub artifacts. Release candidates must pass the
+checks in [Release checklist](../release.md).
+
+The public packages support Node.js `>=20`. CI must prove the core gate on Node 20.x,
+22.x, and 24.x before a release. Optional live/provider/cloud checks remain opt-in and
+may run only on the primary release Node unless a workflow explicitly matrices them.
 
 ## Semantic Versioning
 
-AICF uses semantic versioning. Breaking changes require a major version. New
-optional fields, isolated subpaths, docs, examples, and warning-only checks are
-minor changes. Bug fixes, docs corrections, and compatibility fixes that do not
-change public contracts are patch changes.
+AICF uses semantic versioning. Breaking changes require a major version. New optional
+fields, isolated subpaths, docs, examples, and warning-only checks are minor changes.
+Bug fixes, docs corrections, and compatibility fixes that do not change public contracts
+are patch changes.
 
 Core commands:
 
 ```bash
 npm run check
 npm run check:certification
+npm run check:final-matrix
+npm run check:metadata
+npm run check:licenses
+npm run check:release-tag
 npm run check:release-install
+npm run skills:ci
+npm run skills:check
+npm run skills:pack:dry
+npm run release:preflight:npm
+npm run release:publish:dry
 npm pack --dry-run --json
-npm publish --dry-run --access public --tag next
 ```
 
-Use `npm pack` for npm artifact review and `npm run archive:source` for source
-review. Do not zip the working directory manually.
+Use `npm pack` for npm artifact review and `npm run archive:source` for source review.
+Do not zip the working directory manually.
+
+Use [Final Certification Matrix](final-certification-matrix.md) to confirm the local
+command set, workflows, package contents, source archive rule, and publish dry-run
+commands are still aligned.
+
+AICF uses MIT for the v1 public release. The root package, `@aicf/agent-skills`, the
+Codex plugin manifest, skill metadata, README, and release docs must agree; see
+[License Decision](license-decision.md).
+
+Dependency licenses must pass `npm run check:licenses`. Any exception to the default
+permissive allow-list must be documented in
+[Dependency License Exceptions](../public/license-exceptions.md) before tagging.
+
+npm publishing uses trusted publishing from GitHub Actions for version tags. Release
+tags must match the package version exactly. AICF publishes `ai-capability-framework`
+and `@aicf/agent-skills` from the same tag with the same version. Prereleases publish
+with the `next` dist tag; stable releases publish with `latest`.
 
-npm publishing uses trusted publishing from GitHub Actions for version tags.
-Release tags must match the package version exactly. Prereleases publish with
-the `next` dist tag; stable releases publish with `latest`.
+Before the next release tag, run the
+[npm release preflight](../public/npm-release-preflight.md), configure npm trusted
+publishing for both packages, and verify package ownership with `npm owner ls`. The
+scoped package `@aicf/agent-skills` must be owned by AICF maintainers and mapped to
+`.github/workflows/publish.yml` just like the root package.
 
-Use [Final v1 certification](v1-certification.md) before a public stable
-release. It is the objective readiness gate for the repository, package,
-examples, docs, provider conformance, public artifact hygiene, and mock-based
-runtime surfaces.
+Use [Final v1 certification](v1-certification.md) before a public stable release. It is
+the objective readiness gate for the repository, package, examples, docs, provider
+conformance, public artifact hygiene, and mock-based runtime surfaces.

package/docs/public-framework/security-disclosure.md

@@ -2,8 +2,8 @@
 
 Use [SECURITY.md](../../SECURITY.md) for vulnerability reporting.
 
-Do not publish credentials, raw prompts, provider payloads, traces, customer
-data, tenant/account/user IDs, or exploit details in public issues.
+Do not publish credentials, raw prompts, provider payloads, traces, customer data,
+tenant/account/user IDs, or exploit details in public issues.
 
 Security reports should include:
 
@@ -13,6 +13,5 @@ Security reports should include:
 - expected impact;
 - suggested mitigation if known.
 
-AICF is a framework. Host applications remain responsible for production auth,
-tenant isolation, provider credentials, storage, approval identity, and incident
-response.
+AICF is a framework. Host applications remain responsible for production auth, tenant
+isolation, provider credentials, storage, approval identity, and incident response.

package/docs/public-framework/v1-certification.md

@@ -1,8 +1,8 @@
 # Final v1.0 Certification
 
-This checklist defines when AICF can be called v1.0 complete. It is a release
-readiness gate, not a compliance certification, audit opinion, legal opinion,
-or security guarantee.
+This checklist defines when AICF can be called v1.0 complete. It is a release readiness
+gate, not a compliance certification, audit opinion, legal opinion, or security
+guarantee.
 
 ## Automated Gate
 
@@ -12,10 +12,38 @@ Run the final local gate:
 npm run check:certification
 ```
 
-The gate runs generated-type freshness, build, typecheck, repository lint,
-tests, example validation, provider conformance, governance gate, docs build,
-package checks, public artifact hygiene, runtime/optional/provider mock suites,
-package dry-run, and final certification assertions.
+Run the final command/workflow/package matrix directly when reviewing release process
+changes:
+
+```bash
+npm run check:final-matrix
+```
+
+The matrix is described in [Final Certification Matrix](final-certification-matrix.md).
+
+The gate runs generated-type freshness, build, typecheck, repository lint, tests,
+example validation, provider conformance, governance gate, docs build, package checks,
+public artifact hygiene, runtime/optional/provider mock suites, agent-skills
+install/check/dry-run, root package dry-run, and final certification assertions.
+
+Run the metadata gate when reviewing package identity or license changes:
+
+```bash
+npm run check:metadata
+```
+
+The metadata gate confirms the MIT license decision, package/plugin/skill version
+agreement, public package metadata, plugin asset paths, and README identity.
+
+Run the dependency license gate when reviewing dependency or lockfile changes:
+
+```bash
+npm run check:licenses
+```
+
+The license gate checks the root and `agent-skills` lockfiles against the allowed
+license list and the public
+[Dependency License Exceptions](../public/license-exceptions.md) register.
 
 Run the public-only safety gate when reviewing artifacts:
 
@@ -26,14 +54,53 @@ npm run check:public
 `check:public` runs package public hygiene, workspace public hygiene, and
 high-confidence secret scanning.
 
+Run the npm release preflight before pushing a release tag:
+
+```bash
+npm run release:preflight:npm
+```
+
+Run the local publish dry-run wrapper before a release tag:
+
+```bash
+npm run release:publish:dry
+```
+
+Run the release tag alignment guard before tagging or reviewing publish workflows:
+
+```bash
+npm run check:release-tag
+```
+
+For final manual release review, run
+`node scripts/check-npm-release-preflight.mjs --strict` after npm ownership and trusted
+publishing are configured.
+
 ## Required Passing State
 
 AICF is not v1.0 complete until:
 
 - `npm run check:certification` passes locally.
-- CI passes on a clean checkout.
+- `npm run check:final-matrix` passes locally.
+- CI passes on a clean checkout across the supported Node compatibility matrix: Node
+  20.x, 22.x, and 24.x.
 - npm package dry-run contains only expected public files.
+- `@aicf/agent-skills` package dry-run contains only expected public skill files, docs,
+  assets, scripts, and plugin metadata.
 - clean consumer smoke test passes.
+- root package, agent-skills package, Codex plugin manifest, and real skill metadata use
+  the same version.
+- npm ownership, scoped package setup, trusted publishing, dist-tag policy, and
+  unpublished target versions are checked with
+  [npm release preflight](../public/npm-release-preflight.md).
+- root and agent-skills publish dry-runs pass through `npm run release:publish:dry`.
+- root package, agent-skills package, Codex plugin manifest, README, and release docs
+  consistently use MIT as the v1 license.
+- dependency licenses pass `npm run check:licenses`, with any exception documented in
+  [Dependency License Exceptions](../public/license-exceptions.md).
+- root API exports are intentional and documented in
+  [Public API Policy](../api/public-api-policy.md).
+- `runCli` is available from `ai-capability-framework/cli`, not from the root package.
 - docs build passes.
 - all examples validate.
 - no example requires real secrets by default.
@@ -54,8 +121,13 @@ AICF is not v1.0 complete until:
 Before a public v1.0 tag, manually inspect:
 
 - npm package contents.
+- `@aicf/agent-skills` package contents.
 - README quickstart from a fresh machine or clean container.
 - fresh-machine quickstart using the public npm package or a clean checkout.
+- 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.
 - examples with fake data.
 - generated API docs.
 - governance/lifecycle docs.
@@ -67,6 +139,17 @@ Before a public v1.0 tag, manually inspect:
 - no personal or private platform assumptions in docs.
 - no hardcoded AWS account IDs or provider keys.
 - no root import of optional dependencies.
+- no root export of CLI internals.
+- same-tag release policy for `ai-capability-framework` and `@aicf/agent-skills`.
+- npm ownership and trusted-publishing setup using `npm owner ls` and
+  `npm run release:preflight:npm`.
+- final matrix and publish dry-run review using `npm run check:final-matrix` and
+  `npm run release:publish:dry`.
+- the MIT license decision is intentional and documented in
+  [License Decision](license-decision.md).
+- dependency license exceptions, if any, are public, exact, reviewed, and still match
+  the current lockfiles.
+- npm trusted publishing is configured for both packages before pushing a release tag.
 
 ## Source Archive Review
 
@@ -77,13 +160,17 @@ npm run archive:source
 npm run check:source-archive
 ```
 
-Do not zip the working directory manually. Workspace archives can include Git
-metadata, dependencies, generated output, local logs, traces, prompts, provider
-payloads, private notes, or packed artifacts.
+Do not zip the working directory manually. Workspace archives can include Git metadata,
+dependencies, generated output, local logs, traces, prompts, provider payloads, private
+notes, or packed artifacts.
 
 ## Live Tests
 
-Live integration tests are opt-in. They require explicit environment variables
-and are not part of normal v1.0 certification. Normal certification uses mock
-clients, deterministic fixtures, descriptor exports, package dry-runs, and
-public artifact checks.
+Live integration tests are opt-in. They require explicit environment variables and are
+not part of normal v1.0 certification. Normal certification uses mock clients,
+deterministic fixtures, descriptor exports, package dry-runs, and public artifact
+checks.
+
+Optional live/provider/cloud checks may run only on the primary release Node unless a
+workflow explicitly matrices them. The compatibility promise is proven by the non-live
+public package gate on Node 20.x, 22.x, and 24.x.