@acidicsoil/portable-capabilities 0.1.5 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.8
+
+### Patch Changes
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Provide a Node `createRequire` bridge in generated ESM CLI bundles so bundled CommonJS code can load Node built-ins without failing at startup.
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Keep CommonJS-backed runtime dependencies external to the public ESM bundle so the globally installed CLI starts correctly under Node.js.
+
+- [#32](https://github.com/AcidicSoil/portable-capabilities/pull/32) [`c4167b4`](https://github.com/AcidicSoil/portable-capabilities/commit/c4167b408e794ba68d5f153c9846c23b7b57b9ed) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Make the CLI source workspace private and keep the repository root as the single npm distribution surface.
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Publish the `portable-capabilities` executable from the public package, include the canonical assets and runtime schemas in the same tarball, and verify a global-style npm installation end to end.
+
 ## 1.0.0
 
 - Added canonical schemas, contracts, nine shared operations, six families, and 16 analytical roles.

package/README.md

@@ -10,24 +10,19 @@ Define an analytical coding-agent capability once, then generate and install the
 
 Portable Capabilities is a contract-first compiler and CLI. A canonical capability describes its activation criteria, accepted inputs, ordered procedure, output schema, evidence requirements, and allowed effects. The compiler turns that contract into runtime-native skills, commands, agents, workflows, rules, or extensions without maintaining a separate handwritten implementation for every client.
 
-## Review every runtime
+## Review runtime support
 
-Generated packages, one-line installers, and captured native outputs for all seven runtimes are available in [`review/runtime-packages`](review/runtime-packages/README.md).
-
-```bash
-bash review/runtime-packages/codex/install.sh
-```
+Historical generated-package snapshots and captured native outputs for all seven runtimes are available in [`review/runtime-packages`](review/runtime-packages/README.md). Use the typed CLI for current installation; the snapshots do not define the active command surface.
 
 ## Try it
 
-Run one complete example with no configuration:
+Inspect the current command surface:
 
 ```bash
-pnpm demo
+pnpm cli -- --help
+pnpm cli -- runtimes
 ```
 
-This builds the canonical `acceptance-criteria-synthesis` capability for Codex, installs it into a clean project, invokes it through Codex, and writes the result to `.demo/result.md`.
-
 ## What problem does it solve?
 
 Coding-agent clients discover and activate reusable behavior differently. The same capability may require a skill directory in one client, a slash command in another, a subagent definition elsewhere, and different permission metadata in each package.
@@ -72,7 +67,7 @@ Every generated package retains a `SKILL.md` behavioral core plus its required r
 
 ## Runtime packages
 
-The project generates packages for seven clients. Package generation is not the same as authoritative behavioral certification: the runtime profile and retained execution evidence determine whether a client is currently supported, unavailable, unsupported, or covered by an approved exception.
+The project generates packages for seven clients. Package generation is not the same as authoritative behavioral certification: the runtime descriptor and retained execution evidence determine whether a client is currently supported, unavailable, unsupported, or covered by an approved exception.
 
 | Runtime            | Native primitives     | Package and verification guide              |
 | ------------------ | --------------------- | ------------------------------------------- |
@@ -105,63 +100,37 @@ The package installs the executable into npm's configured global binary director
 
 While working from this repository, replace `portable-capabilities` in the examples with `pnpm cli --`.
 
-| Command     | Purpose                                                  |
-| ----------- | -------------------------------------------------------- |
-| `build`     | Compile selected capabilities for selected runtimes      |
-| `validate`  | Validate contracts, projections, resources, and packages |
-| `test`      | Run conformance checks                                   |
-| `diff`      | Detect nondeterministic generated output                 |
-| `inspect`   | Examine a resolved capability and runtime projection     |
-| `invoke`    | Execute a verified package through the CLI boundary      |
-| `install`   | Install all capabilities or an explicit subset           |
-| `status`    | Inspect installation health                              |
-| `upgrade`   | Upgrade installer-owned capability files                 |
-| `downgrade` | Restore an earlier package version                       |
-| `recover`   | Recover an interrupted installation transaction          |
-| `remove`    | Remove installer-owned files safely                      |
+| Command    | Purpose                                      |
+| ---------- | -------------------------------------------- |
+| `wizard`   | Guided capability installation               |
+| `runtimes` | List supported runtime IDs                   |
+| `setup`    | Plan or perform typed setup                  |
+| `install`  | Install one or more capabilities             |
+| `update`   | Update installer-owned capability files      |
+| `status`   | Inspect installation health                  |
+| `remove`   | Remove selected installer-owned files safely |
+| `invoke`   | Execute a verified package through the CLI   |
 
 Machine-readable commands support `--format json`.
 
-## Build, inspect, and install
+## Set up a capability
 
-Set the values for your system manifest, runtime, capability, generated bundle, and clean consumer project:
+Install one or more catalog capabilities into a clean project:
 
 ```bash
-MANIFEST=/path/to/capability-system.yaml
-RUNTIME=codex
-CAPABILITY=<capability-id>
-BUNDLE=/tmp/portable-capabilities-bundle
 CONSUMER=/tmp/portable-capabilities-consumer
-```
-
-Build and inspect one runtime projection:
-
-```bash
-pnpm cli -- build "$MANIFEST" \
-  --target "$RUNTIME" \
-  --role "$CAPABILITY" \
-  --output "$BUNDLE"
-
-pnpm cli -- inspect "$MANIFEST" \
-  --target "$RUNTIME" \
-  --role "$CAPABILITY" \
-  --format json
-```
-
-Install it into a clean consumer project and verify installer health:
-
-```bash
 mkdir -p "$CONSUMER"
-git -C "$CONSUMER" init
-
 pnpm cli -- install \
-  --source "$BUNDLE" \
-  --target "$CONSUMER" \
-  --runtime "$RUNTIME" \
-  --package-version 1.0.0 \
-  --capability "$CAPABILITY"
-
-pnpm cli -- status --target "$CONSUMER" --format json
+  --runtime codex \
+  --capability convention-mining \
+  --project "$CONSUMER" \
+  --approval-policy preapproved
+
+pnpm cli -- status \
+  --runtime codex \
+  --capability convention-mining \
+  --project "$CONSUMER" \
+  --format json
 ```
 
 Then start the selected coding-agent client from `$CONSUMER` and follow its runtime guide. Each guide documents the generated paths, native invocation syntax, user smoke test, maintainer certification procedure, and current evidence status.
@@ -170,9 +139,9 @@ Then start the selected coding-agent client from `$CONSUMER` and follow its runt
 
 Portable Capabilities keeps these claims separate:
 
-1. **Static package validation** proves file layout, schemas, resources, primitive selection, permissions, and integrity metadata.
-2. **Clean installation validation** proves the packed CLI can install, inspect, upgrade, recover, and remove generated packages in a disposable project.
-3. **Native client execution** proves the real client discovered and invoked the generated primitive.
+1. **Static package validation** proves file layout, schemas, resources, and integrity metadata.
+2. **Clean installation validation** proves the packed CLI can install, update, status-check, and remove generated capabilities in a disposable project.
+3. **Native client execution** proves the real client discovered and invoked the generated capability.
 4. **Behavioral conformance** proves the client consumed the operational instructions, produced schema-valid output, preserved evidence requirements, and respected effects.
 
 A static or simulated pass must not be reported as native behavioral support. See [Testing](docs/TESTING.md).

package/dist-release/catalog/roles/acceptance-criteria-synthesis.yaml

@@ -0,0 +1,84 @@
+schemaVersion: '1.0'
+id: acceptance-criteria-synthesis
+purpose: Derive measurable acceptance criteria from intent and evidence.
+family:
+  id: guardrails-evaluation
+  version: 1.0.0
+taxonomy:
+  id: acceptance-criteria-synthesis
+  displayName: Acceptance Criteria Synthesis
+  transformation: Derive measurable acceptance criteria from intent and evidence.
+  intendedOutput: Acceptance criteria set
+inputs:
+- name: intent-and-requirements
+  description: The intent, requirements, or obligations to be accepted.
+  required: true
+- name: implementation-evidence
+  description: Evidence about the system or artifact under evaluation.
+  required: false
+- name: quality-thresholds
+  description: Measurable thresholds and tolerances.
+  required: false
+precedence:
+- sourceClass: explicit-contract
+  rank: 0
+- sourceClass: observed-artifact
+  rank: 1
+- sourceClass: inference
+  rank: 2
+pipeline:
+- id: ingest.sources
+  version: 1.0.0
+- id: trace.build-evidence-ledger
+  version: 1.0.0
+- id: validation.contract
+  version: 1.0.0
+output:
+  schema: canonical/schemas/acceptance-criteria-synthesis.output.schema.json
+  description: Acceptance criteria set
+requiredBehavior:
+- 'activation: Use acceptance-criteria-synthesis only when the requested outcome requires this transformation: Derive
+  measurable acceptance criteria from intent and evidence.'
+- 'sufficiency: Require all role inputs marked required and enough evidence to complete these gates: Every obligation
+  maps to at least one unambiguous criterion, each criterion names evidence and pass/fail conditions, and coverage
+  gaps are explicit.'
+- 'conflict: Apply declared source precedence; when equally authoritative evidence changes the decision, preserve
+  both positions and return the affected output field as unresolved.'
+- 'ambiguity: Isolate ambiguous terms or boundaries, show which stage and output fields they affect, and request
+  clarification rather than selecting an unsupported interpretation.'
+- 'abstention: Abstain from acceptance-criteria-synthesis when required inputs are absent, the decision rule cannot
+  be applied, or evidence cannot satisfy the completion gate.'
+- 'stop: Stop before emitting Acceptance criteria set unless Every obligation maps to at least one unambiguous criterion,
+  each criterion names evidence and pass/fail conditions, and coverage gaps are explicit.'
+- 'resources: Load requirements, governing contracts, implementation evidence, and measurement standards; load examples
+  only to clarify boundary conditions.'
+- 'transformation: Execute the ordered analytical procedure: 1) decompose intent into observable obligations; 2)
+  identify success failure boundary and edge conditions; 3) write measurable criteria with evidence and threshold
+  requirements; 4) check completeness ambiguity independence and testability.'
+- 'output: Populate and validate canonical/schemas/acceptance-criteria-synthesis.output.schema.json with required
+  fields criteria, evidenceRequirements, thresholds, failureConditions, coverageMap; do not replace missing fields
+  with prose.'
+- 'traceability: Link every material output field to source identifiers and the analytical stage or decision that
+  produced it; retain counterevidence for unresolved results.'
+- 'evaluation: Pass only when the output schema validates, the ordered stages are evidenced, the role decision rule
+  was applied, and this completion gate holds: Every obligation maps to at least one unambiguous criterion, each
+  criterion names evidence and pass/fail conditions, and coverage gaps are explicit.'
+forbiddenBehavior:
+- Do not substitute generic analytical behavior for the role-specific acceptance-criteria-synthesis transformation.
+- Do not skip, reorder, or silently collapse the role's declared analytical stages.
+- Do not invent missing evidence, resolve authority conflicts by convenience, or emit a completed result after a
+  stop or abstention condition.
+- Do not copy operation-owned ingestion, ledger, or schema-validation mechanics into the role contract.
+traceability:
+  materialClaimsRequireSources: true
+  ledgerFormat: jsonl
+  artifacts: content-addressed
+evaluation:
+  criteria:
+  - The authoritative transformation and intended output for acceptance-criteria-synthesis are preserved.
+  - 'Required inputs and the decision rule are satisfied: Accept a criterion only when an independent evaluator
+    can determine pass or fail from named evidence without inferring unstated intent.'
+  - 'The ordered analytical stages are evidenced and the output completion gate passes: Every obligation maps to
+    at least one unambiguous criterion, each criterion names evidence and pass/fail conditions, and coverage gaps
+    are explicit.'
+  - Conflict, ambiguity, insufficient-evidence, abstention, and stop behavior remain explicit and testable.

package/dist-release/catalog/roles/anti-pattern-inversion.yaml

@@ -0,0 +1,83 @@
+schemaVersion: '1.0'
+id: anti-pattern-inversion
+purpose: Invert documented anti-patterns into positive construction rules.
+family:
+  id: corrective-transformation
+  version: 1.0.0
+taxonomy:
+  id: anti-pattern-inversion
+  displayName: Anti-Pattern Inversion
+  transformation: Invert documented anti-patterns into positive construction rules.
+  intendedOutput: Corrective rule set
+inputs:
+- name: anti-pattern-catalog
+  description: Documented anti-patterns and failure examples.
+  required: true
+- name: construction-context
+  description: The context in which positive rules will be applied.
+  required: true
+- name: existing-controls
+  description: Existing rules or controls that may overlap.
+  required: false
+precedence:
+- sourceClass: explicit-contract
+  rank: 0
+- sourceClass: observed-artifact
+  rank: 1
+- sourceClass: inference
+  rank: 2
+pipeline:
+- id: ingest.sources
+  version: 1.0.0
+- id: trace.build-evidence-ledger
+  version: 1.0.0
+- id: validation.contract
+  version: 1.0.0
+output:
+  schema: canonical/schemas/anti-pattern-inversion.output.schema.json
+  description: Corrective rule set
+requiredBehavior:
+- 'activation: Use anti-pattern-inversion only when the requested outcome requires this transformation: Invert documented
+  anti-patterns into positive construction rules.'
+- 'sufficiency: Require all role inputs marked required and enough evidence to complete these gates: Every rule
+  traces to a harmful mechanism, passes original failure cases, and documents legitimate exceptions and overlap
+  with existing controls.'
+- 'conflict: Apply declared source precedence; when equally authoritative evidence changes the decision, preserve
+  both positions and return the affected output field as unresolved.'
+- 'ambiguity: Isolate ambiguous terms or boundaries, show which stage and output fields they affect, and request
+  clarification rather than selecting an unsupported interpretation.'
+- 'abstention: Abstain from anti-pattern-inversion when required inputs are absent, the decision rule cannot be
+  applied, or evidence cannot satisfy the completion gate.'
+- 'stop: Stop before emitting Corrective rule set unless Every rule traces to a harmful mechanism, passes original
+  failure cases, and documents legitimate exceptions and overlap with existing controls.'
+- 'resources: Load anti-pattern evidence, construction context, existing controls, and exception examples; load
+  each failure trace to validate causal coverage.'
+- 'transformation: Execute the ordered analytical procedure: 1) identify the harmful mechanism and triggering conditions;
+  2) derive the positive invariant that prevents the mechanism; 3) translate the invariant into actionable construction
+  and review rules; 4) test rules against original failures and legitimate exceptions.'
+- 'output: Populate and validate canonical/schemas/anti-pattern-inversion.output.schema.json with required fields
+  antiPatternMap, positiveRules, exceptions, verificationChecks, coverageEvidence; do not replace missing fields
+  with prose.'
+- 'traceability: Link every material output field to source identifiers and the analytical stage or decision that
+  produced it; retain counterevidence for unresolved results.'
+- 'evaluation: Pass only when the output schema validates, the ordered stages are evidenced, the role decision rule
+  was applied, and this completion gate holds: Every rule traces to a harmful mechanism, passes original failure
+  cases, and documents legitimate exceptions and overlap with existing controls.'
+forbiddenBehavior:
+- Do not substitute generic analytical behavior for the role-specific anti-pattern-inversion transformation.
+- Do not skip, reorder, or silently collapse the role's declared analytical stages.
+- Do not invent missing evidence, resolve authority conflicts by convenience, or emit a completed result after a
+  stop or abstention condition.
+- Do not copy operation-owned ingestion, ledger, or schema-validation mechanics into the role contract.
+traceability:
+  materialClaimsRequireSources: true
+  ledgerFormat: jsonl
+  artifacts: content-addressed
+evaluation:
+  criteria:
+  - The authoritative transformation and intended output for anti-pattern-inversion are preserved.
+  - 'Required inputs and the decision rule are satisfied: Adopt a positive rule only when it blocks the harmful
+    mechanism without prohibiting documented legitimate behavior.'
+  - 'The ordered analytical stages are evidenced and the output completion gate passes: Every rule traces to a harmful
+    mechanism, passes original failure cases, and documents legitimate exceptions and overlap with existing controls.'
+  - Conflict, ambiguity, insufficient-evidence, abstention, and stop behavior remain explicit and testable.

package/dist-release/catalog/roles/behavior-preserving-refactor.yaml

@@ -0,0 +1,88 @@
+schemaVersion: '1.0'
+id: behavior-preserving-refactor
+purpose: Transform structure while preserving observable behavior.
+family:
+  id: corrective-transformation
+  version: 1.0.0
+taxonomy:
+  id: behavior-preserving-refactor
+  displayName: Behavior-Preserving Refactor
+  transformation: Transform structure while preserving observable behavior.
+  intendedOutput: Refactored artifact with equivalence evidence
+inputs:
+- name: source-artifact
+  description: The artifact to restructure.
+  required: true
+- name: behavior-contract
+  description: Observable behavior that must be preserved.
+  required: true
+- name: refactor-goals
+  description: Structural goals and allowed change scope.
+  required: true
+- name: equivalence-fixtures
+  description: Tests or traces used to prove equivalence.
+  required: true
+precedence:
+- sourceClass: explicit-contract
+  rank: 0
+- sourceClass: observed-artifact
+  rank: 1
+- sourceClass: inference
+  rank: 2
+pipeline:
+- id: ingest.sources
+  version: 1.0.0
+- id: trace.build-evidence-ledger
+  version: 1.0.0
+- id: validation.contract
+  version: 1.0.0
+output:
+  schema: canonical/schemas/behavior-preserving-refactor.output.schema.json
+  description: Refactored artifact with equivalence evidence
+requiredBehavior:
+- 'activation: Use behavior-preserving-refactor only when the requested outcome requires this transformation: Transform
+  structure while preserving observable behavior.'
+- 'sufficiency: Require all role inputs marked required and enough evidence to complete these gates: All affected
+  behavior passes equivalence checks, any difference is declared out of scope or rejected, and the structural goal
+  is demonstrably achieved.'
+- 'conflict: Apply declared source precedence; when equally authoritative evidence changes the decision, preserve
+  both positions and return the affected output field as unresolved.'
+- 'ambiguity: Isolate ambiguous terms or boundaries, show which stage and output fields they affect, and request
+  clarification rather than selecting an unsupported interpretation.'
+- 'abstention: Abstain from behavior-preserving-refactor when required inputs are absent, the decision rule cannot
+  be applied, or evidence cannot satisfy the completion gate.'
+- 'stop: Stop before emitting Refactored artifact with equivalence evidence unless All affected behavior passes
+  equivalence checks, any difference is declared out of scope or rejected, and the structural goal is demonstrably
+  achieved.'
+- 'resources: Load the source artifact, behavior contract, baseline tests, execution traces, and refactor constraints;
+  run only read-safe analysis unless an explicit execution harness is provided.'
+- 'transformation: Execute the ordered analytical procedure: 1) establish a pre-change behavioral baseline; 2) identify
+  structural changes that do not alter the behavior contract; 3) apply changes in reversible increments; 4) compare
+  outputs side effects and failure behavior against the baseline.'
+- 'output: Populate and validate canonical/schemas/behavior-preserving-refactor.output.schema.json with required
+  fields refactoredArtifact, changeMap, equivalenceEvidence, behavioralDiffs, rollbackNotes; do not replace missing
+  fields with prose.'
+- 'traceability: Link every material output field to source identifiers and the analytical stage or decision that
+  produced it; retain counterevidence for unresolved results.'
+- 'evaluation: Pass only when the output schema validates, the ordered stages are evidenced, the role decision rule
+  was applied, and this completion gate holds: All affected behavior passes equivalence checks, any difference is
+  declared out of scope or rejected, and the structural goal is demonstrably achieved.'
+forbiddenBehavior:
+- Do not substitute generic analytical behavior for the role-specific behavior-preserving-refactor transformation.
+- Do not skip, reorder, or silently collapse the role's declared analytical stages.
+- Do not invent missing evidence, resolve authority conflicts by convenience, or emit a completed result after a
+  stop or abstention condition.
+- Do not copy operation-owned ingestion, ledger, or schema-validation mechanics into the role contract.
+traceability:
+  materialClaimsRequireSources: true
+  ledgerFormat: jsonl
+  artifacts: content-addressed
+evaluation:
+  criteria:
+  - The authoritative transformation and intended output for behavior-preserving-refactor are preserved.
+  - 'Required inputs and the decision rule are satisfied: Permit a structural change only when equivalence evidence
+    covers affected behavior; classify intentional behavior changes outside this role.'
+  - 'The ordered analytical stages are evidenced and the output completion gate passes: All affected behavior passes
+    equivalence checks, any difference is declared out of scope or rejected, and the structural goal is demonstrably
+    achieved.'
+  - Conflict, ambiguity, insufficient-evidence, abstention, and stop behavior remain explicit and testable.

package/dist-release/catalog/roles/canonical-exemplar-generalization.yaml

@@ -0,0 +1,84 @@
+schemaVersion: '1.0'
+id: canonical-exemplar-generalization
+purpose: Transform concrete exemplars into a reusable canonical model.
+family:
+  id: exemplar-modeling
+  version: 1.0.0
+taxonomy:
+  id: canonical-exemplar-generalization
+  displayName: Canonical Exemplar Generalization
+  transformation: Transform concrete exemplars into a reusable canonical model.
+  intendedOutput: Canonical generalized model
+inputs:
+- name: exemplars
+  description: Representative concrete exemplars to generalize.
+  required: true
+- name: variation-samples
+  description: Counterexamples or variants used to test generality.
+  required: true
+- name: scope-constraints
+  description: Explicit boundaries the generalized model must respect.
+  required: false
+precedence:
+- sourceClass: explicit-contract
+  rank: 0
+- sourceClass: observed-artifact
+  rank: 1
+- sourceClass: inference
+  rank: 2
+pipeline:
+- id: ingest.sources
+  version: 1.0.0
+- id: trace.build-evidence-ledger
+  version: 1.0.0
+- id: validation.contract
+  version: 1.0.0
+output:
+  schema: canonical/schemas/canonical-exemplar-generalization.output.schema.json
+  description: Canonical generalized model
+requiredBehavior:
+- 'activation: Use canonical-exemplar-generalization only when the requested outcome requires this transformation:
+  Transform concrete exemplars into a reusable canonical model.'
+- 'sufficiency: Require all role inputs marked required and enough evidence to complete these gates: Every invariant
+  is supported by multiple exemplars, every variation point is bounded, and held-out variants are either covered
+  or explicitly excluded.'
+- 'conflict: Apply declared source precedence; when equally authoritative evidence changes the decision, preserve
+  both positions and return the affected output field as unresolved.'
+- 'ambiguity: Isolate ambiguous terms or boundaries, show which stage and output fields they affect, and request
+  clarification rather than selecting an unsupported interpretation.'
+- 'abstention: Abstain from canonical-exemplar-generalization when required inputs are absent, the decision rule
+  cannot be applied, or evidence cannot satisfy the completion gate.'
+- 'stop: Stop before emitting Canonical generalized model unless Every invariant is supported by multiple exemplars,
+  every variation point is bounded, and held-out variants are either covered or explicitly excluded.'
+- 'resources: Load the exemplar corpus, scope constraints, and held-out variation set; load each only when it contributes
+  coverage or falsification evidence.'
+- 'transformation: Execute the ordered analytical procedure: 1) inventory invariant and variable features across
+  exemplars; 2) separate essential structure from incidental detail; 3) propose the smallest reusable model covering
+  supported variation; 4) challenge the model against held-out variants and record exclusions.'
+- 'output: Populate and validate canonical/schemas/canonical-exemplar-generalization.output.schema.json with required
+  fields model, invariants, variationPoints, excludedDetails, coverageEvidence; do not replace missing fields with
+  prose.'
+- 'traceability: Link every material output field to source identifiers and the analytical stage or decision that
+  produced it; retain counterevidence for unresolved results.'
+- 'evaluation: Pass only when the output schema validates, the ordered stages are evidenced, the role decision rule
+  was applied, and this completion gate holds: Every invariant is supported by multiple exemplars, every variation
+  point is bounded, and held-out variants are either covered or explicitly excluded.'
+forbiddenBehavior:
+- Do not substitute generic analytical behavior for the role-specific canonical-exemplar-generalization transformation.
+- Do not skip, reorder, or silently collapse the role's declared analytical stages.
+- Do not invent missing evidence, resolve authority conflicts by convenience, or emit a completed result after a
+  stop or abstention condition.
+- Do not copy operation-owned ingestion, ledger, or schema-validation mechanics into the role contract.
+traceability:
+  materialClaimsRequireSources: true
+  ledgerFormat: jsonl
+  artifacts: content-addressed
+evaluation:
+  criteria:
+  - The authoritative transformation and intended output for canonical-exemplar-generalization are preserved.
+  - 'Required inputs and the decision rule are satisfied: Retain a feature only when it is necessary across supported
+    exemplars or explicitly required by scope; otherwise classify it as optional or excluded.'
+  - 'The ordered analytical stages are evidenced and the output completion gate passes: Every invariant is supported
+    by multiple exemplars, every variation point is bounded, and held-out variants are either covered or explicitly
+    excluded.'
+  - Conflict, ambiguity, insufficient-evidence, abstention, and stop behavior remain explicit and testable.

package/dist-release/catalog/roles/constrained-exemplar-adaptation.yaml

@@ -0,0 +1,85 @@
+schemaVersion: '1.0'
+id: constrained-exemplar-adaptation
+purpose: Adapt an exemplar under explicit constraints.
+family:
+  id: exemplar-modeling
+  version: 1.0.0
+taxonomy:
+  id: constrained-exemplar-adaptation
+  displayName: Constrained Exemplar Adaptation
+  transformation: Adapt an exemplar under explicit constraints.
+  intendedOutput: Constraint-compliant adaptation
+inputs:
+- name: source-exemplar
+  description: The exemplar whose structure or behavior is being adapted.
+  required: true
+- name: target-constraints
+  description: Mandatory target-environment constraints.
+  required: true
+- name: preservation-requirements
+  description: Properties that must remain unchanged.
+  required: true
+- name: target-context
+  description: Optional target conventions and integration context.
+  required: false
+precedence:
+- sourceClass: explicit-contract
+  rank: 0
+- sourceClass: observed-artifact
+  rank: 1
+- sourceClass: inference
+  rank: 2
+pipeline:
+- id: ingest.sources
+  version: 1.0.0
+- id: trace.build-evidence-ledger
+  version: 1.0.0
+- id: validation.contract
+  version: 1.0.0
+output:
+  schema: canonical/schemas/constrained-exemplar-adaptation.output.schema.json
+  description: Constraint-compliant adaptation
+requiredBehavior:
+- 'activation: Use constrained-exemplar-adaptation only when the requested outcome requires this transformation:
+  Adapt an exemplar under explicit constraints.'
+- 'sufficiency: Require all role inputs marked required and enough evidence to complete these gates: All mandatory
+  constraints pass, preserved properties remain equivalent, and every deviation has an evidence-backed rationale.'
+- 'conflict: Apply declared source precedence; when equally authoritative evidence changes the decision, preserve
+  both positions and return the affected output field as unresolved.'
+- 'ambiguity: Isolate ambiguous terms or boundaries, show which stage and output fields they affect, and request
+  clarification rather than selecting an unsupported interpretation.'
+- 'abstention: Abstain from constrained-exemplar-adaptation when required inputs are absent, the decision rule cannot
+  be applied, or evidence cannot satisfy the completion gate.'
+- 'stop: Stop before emitting Constraint-compliant adaptation unless All mandatory constraints pass, preserved properties
+  remain equivalent, and every deviation has an evidence-backed rationale.'
+- 'resources: Load the source exemplar, target constraint set, preservation checks, and target conventions only
+  when a mapped element depends on them.'
+- 'transformation: Execute the ordered analytical procedure: 1) extract the exemplar properties relevant to the
+  target; 2) classify target constraints as mandatory, negotiable, or conflicting; 3) map exemplar elements to target-compatible
+  replacements; 4) validate preserved properties and document every intentional deviation.'
+- 'output: Populate and validate canonical/schemas/constrained-exemplar-adaptation.output.schema.json with required
+  fields adaptedArtifact, constraintMapping, preservedProperties, deviations, validationResults; do not replace
+  missing fields with prose.'
+- 'traceability: Link every material output field to source identifiers and the analytical stage or decision that
+  produced it; retain counterevidence for unresolved results.'
+- 'evaluation: Pass only when the output schema validates, the ordered stages are evidenced, the role decision rule
+  was applied, and this completion gate holds: All mandatory constraints pass, preserved properties remain equivalent,
+  and every deviation has an evidence-backed rationale.'
+forbiddenBehavior:
+- Do not substitute generic analytical behavior for the role-specific constrained-exemplar-adaptation transformation.
+- Do not skip, reorder, or silently collapse the role's declared analytical stages.
+- Do not invent missing evidence, resolve authority conflicts by convenience, or emit a completed result after a
+  stop or abstention condition.
+- Do not copy operation-owned ingestion, ledger, or schema-validation mechanics into the role contract.
+traceability:
+  materialClaimsRequireSources: true
+  ledgerFormat: jsonl
+  artifacts: content-addressed
+evaluation:
+  criteria:
+  - The authoritative transformation and intended output for constrained-exemplar-adaptation are preserved.
+  - 'Required inputs and the decision rule are satisfied: Prefer the least-divergent adaptation that satisfies all
+    mandatory constraints; abstain when two mandatory constraints cannot be jointly satisfied.'
+  - 'The ordered analytical stages are evidenced and the output completion gate passes: All mandatory constraints
+    pass, preserved properties remain equivalent, and every deviation has an evidence-backed rationale.'
+  - Conflict, ambiguity, insufficient-evidence, abstention, and stop behavior remain explicit and testable.