@acidicsoil/portable-capabilities 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0
+
+- Added canonical schemas, contracts, nine shared operations, six families, and 16 analytical roles.
+- Added seven runtime profiles and native adapters plus a reference adapter.
+- Added eight-layer conformance, semantic equivalence, traceability, property testing, fault injection, metamorphic tests, and regression scenarios.
+- Added the public `portable-capabilities` CLI with `build`, `validate`, `test`, `diff`, `inspect`, and `invoke`.
+- Added safe Execa runtime invocation, structured JSON results, diagnostics, JSONL traces, and content-addressed artifacts.
+- Added Changesets, GitHub Actions, Lefthook, deterministic runtime bundles, npm tarball install-and-run verification, and clean-checkout release verification.
+- Corrected release policy so generated `dist/` output is ignored and untracked; drift uses independent double generation.

package/README.md

@@ -0,0 +1,231 @@
+# Portable Capabilities
+
+[![CI](https://github.com/AcidicSoil/portable-capabilities/actions/workflows/ci.yml/badge.svg)](https://github.com/AcidicSoil/portable-capabilities/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A524.14.0-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![pnpm](https://img.shields.io/badge/pnpm-11.1.3-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Status](https://img.shields.io/badge/status-v1.0%20in%20progress-5B5BD6)](.planning/STATE.md)
+
+Define an analytical capability once, then compile it into deterministic, traceable packages for multiple coding-agent runtimes.
+
+Portable Capabilities is a contract-first TypeScript toolchain for expressing reusable analytical behavior independently of any one prompt format or agent platform. Canonical role contracts, schemas, policies, and operations are resolved into a runtime-neutral projection and rendered through adapters for:
+
+- oh-my-pi
+- OpenCode
+- Pi
+- Claude Code
+- Codex
+- Google Antigravity
+- Deep Agents Code
+
+> **Project status:** the v1.0 milestone is still in progress. Phases 1–6 are complete; Phase 6.1, runtime usability and behavioral closure, is planned and has not yet been executed. See [project state](.planning/STATE.md) and the [Phase 6.1 plan set](.planning/phases/06.1-runtime-usability-and-behavioral-closure/).
+
+## Why this exists
+
+Agent runtimes expose different package layouts, activation primitives, permission controls, and execution models. Encoding the same analytical capability separately for each runtime creates drift and makes behavioral claims difficult to verify.
+
+Portable Capabilities separates the portable contract from the runtime projection:
+
+```text
+canonical contracts
+      ↓
+validation + deterministic resolution
+      ↓
+runtime-neutral projection
+      ↓
+runtime adapters
+      ↓
+native packages + conformance evidence
+```
+
+The core invariant is simple:
+
+> One canonical capability definition must produce semantically equivalent, traceable behavior across every supported runtime.
+
+## Quick start
+
+### Prerequisites
+
+- Node.js 24.14.0 or newer
+- pnpm 11.1.3
+- Git
+
+### Run from the repository
+
+```bash
+corepack prepare pnpm@11.1.3 --activate
+git clone https://github.com/AcidicSoil/portable-capabilities.git
+cd portable-capabilities
+pnpm install --frozen-lockfile
+pnpm cli -- --help
+```
+
+Build the current tracer fixture as structured JSON:
+
+```bash
+pnpm cli -- build fixtures/tracer/system.yaml --format json
+```
+
+Write generated output to an explicit directory:
+
+```bash
+pnpm cli -- build fixtures/tracer/system.yaml --output ./generated
+```
+
+Generated artifacts are reproducible outputs, not source authority. Repository drift checks generate independently in temporary directories and compare normalized results.
+
+## Current capabilities
+
+The repository currently includes:
+
+- Sixteen canonical analytical role contracts
+- Six capability families and nine shared operations
+- Versioned schemas, policy evaluation, diagnostics, evidence classes, and provenance
+- Deterministic compiler resolution and normalized file generation
+- Seven runtime profiles and adapter packages, plus a reference adapter
+- Structured conformance results, semantic comparison, property tests, fault injection, and regression fixtures
+- A public CLI exposing `build`, `validate`, `test`, `diff`, `inspect`, and `invoke`
+- CI, package verification, runtime bundle generation, clean-checkout release checks, and generated-output drift verification
+
+Phase 6.1 is responsible for closing the remaining release-blocking gaps around operational skills, transitive package resources, truthful native projection, effect enforcement, clean-consumer runtime execution, installation lifecycle, and executable documentation.
+
+## CLI
+
+The intended public v1 distribution is `@portable-capabilities/cli`, installed with the executable:
+
+```text
+portable-capabilities
+```
+
+Current command surface:
+
+| Command    | Purpose                                                            |
+| ---------- | ------------------------------------------------------------------ |
+| `build`    | Compile canonical input into generated runtime packages            |
+| `validate` | Validate canonical documents, projections, and generated artifacts |
+| `test`     | Run conformance checks                                             |
+| `diff`     | Compare independently generated output                             |
+| `inspect`  | Examine resolved contracts, profiles, and projection data          |
+| `invoke`   | Launch a selected runtime through the CLI boundary                 |
+
+The command surface exists today, but Phase 6.1 will replace remaining tracer-oriented paths with fully installed, runtime-native workflows before the milestone is declared complete.
+
+## Architecture
+
+```text
+canonical/
+  roles · families · operations · policies · runtime profiles
+        │
+        ▼
+packages/contracts + packages/schemas
+        │
+        ▼
+packages/compiler
+  load · validate · resolve · enforce · digest · write
+        │
+        ▼
+packages/renderer-core + packages/adapters/*
+        │
+        ├── generated runtime packages
+        └── conformance evidence
+                    │
+                    ▼
+              packages/cli
+```
+
+The repository follows a strict dependency direction:
+
+1. Canonical documents define portable behavior.
+2. Contracts and schemas define the shared vocabulary.
+3. The compiler resolves deterministic system state.
+4. Renderer core and adapters select runtime-native representations.
+5. The CLI exposes user workflows.
+6. Conformance verifies structure, behavior, safety, traceability, and regression outcomes.
+
+See [Architecture](docs/ARCHITECTURE.md) for package-level detail.
+
+## Workspace
+
+| Package                                | Responsibility                                                   |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `@portable-capabilities/contracts`     | Shared readonly domain contracts                                 |
+| `@portable-capabilities/schemas`       | JSON Schema registry and validation                              |
+| `@portable-capabilities/operations`    | Shared analytical operations and families                        |
+| `@portable-capabilities/compiler`      | Loading, resolution, policy, provenance, diagnostics, and output |
+| `@portable-capabilities/renderer-core` | Projection IR and adapter contracts                              |
+| `@portable-capabilities/adapter-*`     | Runtime-specific private adapters                                |
+| `@portable-capabilities/fixtures`      | Deterministic fixtures and regression inputs                     |
+| `@portable-capabilities/conformance`   | Centralized verification implementation and tests                |
+| `@portable-capabilities/cli`           | Public command-line package                                      |
+
+Internal workspace packages remain private implementation modules. Normal CI never publishes packages automatically.
+
+## Development
+
+Common commands:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm test:run
+pnpm verify:generated-drift
+pnpm ci
+```
+
+Release-oriented checks:
+
+```bash
+pnpm release:pack:verify
+pnpm release:bundles:verify
+pnpm docs:verify
+pnpm release:verify
+```
+
+Tests are centralized under `packages/conformance/src/`. TypeScript, JavaScript, and JSON use Biome; YAML uses Prettier.
+
+## Project status and limitations
+
+The existing implementation proves the contract/compiler/adapter/CLI architecture and the Phase 6 release gates. It does **not** yet justify unconditional production-readiness claims for all seven runtimes.
+
+Known Phase 6.1 closure work includes:
+
+- Complete operational instructions for every generated skill
+- Transitive, source-independent package resource closure
+- Runtime-specific primitive selection and native permission controls
+- Separate CLI invocation confinement
+- Exact compatibility baselines and authoritative runtime harnesses
+- Four linked digest and lock layers
+- Collision-safe `install`, `status`, `upgrade`, and `remove`
+- Installed-artifact clean-consumer behavioral conformance
+- Eight explicit conformance layers and seven normative regression scenarios
+
+The complete dependency-ordered plan is in [Phase 6.1](.planning/phases/06.1-runtime-usability-and-behavioral-closure/).
+
+## Documentation
+
+- [Getting Started](docs/GETTING-STARTED.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Development](docs/DEVELOPMENT.md)
+- [Testing](docs/TESTING.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Deployment and CI](docs/DEPLOYMENT.md)
+- [Migration](docs/MIGRATION.md)
+- [Releasing](docs/RELEASING.md)
+- [Product Requirements](docs/prd/product.md)
+- [Runtime Usability Closure PRD](docs/prd/runtime-usability-closure.md)
+
+## Planning workflow
+
+GSD planning and milestone evidence live under `.planning/`:
+
+- [Project definition](.planning/PROJECT.md)
+- [Requirements](.planning/REQUIREMENTS.md)
+- [Roadmap](.planning/ROADMAP.md)
+- [Current state](.planning/STATE.md)
+- [Codebase map](.planning/codebase/)
+
+The current next step is to execute the ten gated Phase 6.1 plans only after their prerequisite and review gates remain satisfied.
+
+See [the normative runtime primitive matrix](docs/prd/runtime-primitive-matrix.md) for verified client activation selection.

package/canonical/exceptions/antigravity-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: antigravity-unsupported-primitives
+runtime: antigravity
+scope: capability:native-primitives
+rationale: antigravity does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (command, agent, extension, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/claude-code-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: claude-code-unsupported-primitives
+runtime: claude-code
+scope: capability:native-primitives
+rationale: claude-code does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (workflow, rule, extension, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/codex-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: codex-unsupported-primitives
+runtime: codex
+scope: capability:native-primitives
+rationale: codex does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (command, workflow, rule, extension, memory) are not
+  emitted as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/dcode-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: dcode-unsupported-primitives
+runtime: dcode
+scope: capability:native-primitives
+rationale: dcode does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (command, agent, workflow, rule, extension, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/oh-my-pi-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: oh-my-pi-unsupported-primitives
+runtime: oh-my-pi
+scope: capability:native-primitives
+rationale: oh-my-pi does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (command, agent, workflow, rule, extension, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/opencode-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: opencode-unsupported-primitives
+runtime: opencode
+scope: capability:native-primitives
+rationale: opencode does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (workflow, rule, extension, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/exceptions/pi-unsupported-primitives.yaml

@@ -0,0 +1,16 @@
+schemaVersion: "1.0"
+id: pi-unsupported-primitives
+runtime: pi
+scope: capability:native-primitives
+rationale: pi does not expose every portable wrapper primitive natively.
+impact:
+  Unsupported primitives (command, agent, workflow, rule, memory) are not emitted
+  as native wrappers.
+fallback:
+  Use the generated skill and external resources as the portable behavioral
+  unit.
+tests:
+  - native-matrix:all-cells
+  - runtime-profiles:unsupported-fallbacks
+provenance: docs/prd/product.md#runtime-projection-layer
+reviewDate: "2027-01-27"

package/canonical/families/comparative-traceability.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: comparative-traceability
+version: 1.0.0
+purpose: Compare and map evidence across artifacts.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.

package/canonical/families/context-template-generation.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: context-template-generation
+version: 1.0.0
+purpose: Define context boundaries and reusable templates.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.

package/canonical/families/corrective-transformation.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: corrective-transformation
+version: 1.0.0
+purpose: Correct structure while preserving intended behavior.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.

package/canonical/families/exemplar-modeling.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: exemplar-modeling
+version: 1.0.0
+purpose: Generalize and adapt exemplars.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.

package/canonical/families/guardrails-evaluation.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: guardrails-evaluation
+version: 1.0.0
+purpose: Convert failure knowledge into guardrails and tests.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.

package/canonical/families/workflow-intent-abstraction.yaml

@@ -0,0 +1,18 @@
+schemaVersion: "1.0"
+id: workflow-intent-abstraction
+version: 1.0.0
+purpose: Abstract workflows and intent.
+allowedOperations:
+  - ingest.sources
+  - normalize.artifacts
+  - segment.surfaces
+  - trace.build-evidence-ledger
+  - patterns.extract
+  - compare.artifacts
+  - inference.classify
+  - generation.render
+  - validation.contract
+requiredBehavior:
+  - Preserve traceability.
+forbiddenBehavior:
+  - Do not obscure unresolved conflicts.