@calliopelabs/cli 3.5.3 → 3.6.0

package/docs/migration-playbook.md

@@ -0,0 +1,152 @@
+# Code migration playbook v1
+
+This Calliope-owned playbook pairs the `migration-v1` CLI helpers with the native
+reviewed execution and improvement contracts. It is packaged with the npm CLI.
+It supports one initial adapter: self-contained JavaScript `.mjs` to TypeScript
+`.mts` command-line programs on an exact Node 24 Linux image. Other language,
+framework and API migrations require another qualified adapter.
+
+## Establish the contract
+
+Select the source repository, full commit, literal read paths, target runtime,
+allowed worker tools and paths, total budget, deadline and concurrency. Preserve
+original tests, build configuration and lockfiles. Inventory only reads committed
+objects; an uncommitted checkout is not evidence for the pinned source.
+
+```sh
+calliope migration capabilities --json
+calliope migration schema --json
+calliope migration inventory --repository REPOSITORY --revision FULL_COMMIT --json
+calliope migration example --json
+calliope migration baseline-schema --json
+calliope migration verification-schema --json
+calliope migration assessment-schema --json
+```
+
+The example supplies source, candidate, known-regression and rulebook templates,
+plus positive, empty, negative-value and invalid-input cases. Save them only in an
+authorized disposable repository and commit them before creating pins. Resolve
+each pin to its full commit, relative path and blob ID. Replace the runtime with
+an already-present image ID and its exact Node version. No helper installs an
+image or adopts a downloaded program automatically.
+
+The chosen cases are a public-interface contract, not proof of general program
+equivalence. An independent reviewer must approve changes to cases, expectations,
+rules and compatibility obligations. Missing coverage remains a finding; it must
+not be removed to obtain a passing report.
+
+## Baseline, pilot and assessment
+
+Create a `calliope.migration.baseline-plan/v1` from the emitted schemas and example.
+It has no candidate field. Review its complete contents and exact digest before
+execution:
+
+```sh
+calliope migration review-baseline --plan baseline.json --json
+calliope migration verify-baseline --repository REPOSITORY --plan baseline.json --approve REVIEW_DIGEST --json
+calliope migration review-baseline-evidence --plan baseline.json --report baseline-report.json --json
+```
+
+A baseline must pass the original cases and detect the declared negative control
+before implementation. The built-in comparator also checks its own adversarial
+cases. Keep baseline failures, verifier failures and environment failures separate.
+Neither a failed baseline nor an ineffective negative control permits migration.
+
+After a separately reviewed pilot implementation, create and approve a full
+verification plan containing the candidate's immutable pin:
+
+```sh
+calliope migration review-verification --plan verification.json --json
+calliope migration verify --repository REPOSITORY --plan verification.json --approve REVIEW_DIGEST --json
+calliope migration review-evidence --plan verification.json --report verification-report.json --json
+```
+
+Use a `calliope.migration.assessment-request/v1` to bind the inventory, source and
+rule pins, target/runtime, declared unit dependencies, explicit exclusions,
+representative pilot plans/reports and independently evidenced measurements.
+Every selected source file must be assigned or excluded with a reason. Preserve
+package cycles and unsupported dependency declarations as findings.
+
+```sh
+calliope migration review-assessment --request assessment.json --json
+calliope migration assess --repository REPOSITORY --request assessment.json --json
+```
+
+The standalone assessment can report `investigate` or `do-not-migrate` and does
+not approve dispatch. A trusted host uses `assessMigration` with its installed
+kit/verifier hashes and independent evidence-review callback before a `go`
+recommendation is possible. Cost and time ranges are pilot extrapolations, not
+confidence intervals or new execution allowances.
+
+## Execute under the native owner
+
+Translate the reviewed work manifest into a native Calliope plan. The native
+coordinator owns review, admission, scheduling, workers, cancellations, attempts
+and the original allowance. Use dependency-first ordering and retain task/unit
+IDs with their source, rule, configuration and implementation binding digests.
+The kit does not supply a second scheduler or allow a worker to mint a root budget.
+
+The host must constrain tools and file paths and bind each worker's budget and
+absolute deadline before dispatch. Verification library callers use the existing
+`VerificationOptions` approval and command-reservation callbacks plus the
+inherited deadline; CLI users
+approve the exact verification digest for one invocation. A JSON report, model
+instruction or claimed review receipt is never authority to execute.
+
+A collected task patch may become an explicitly reviewed, unverified source
+candidate through the native source-candidate API. Creating a candidate is not
+verification, merge, publication or permission to modify the original checkout.
+Re-run the full verification contract against the candidate's exact commit.
+
+## Rule changes, invalidation and replay
+
+Record recurring failures as proposed rule changes with their failing unit,
+source/candidate/rule pins, observation/report digests, hypothesis, risk and
+rollback reference. Use the native bounded improvement review contract for the
+execution strategy. A strategy proposal or rollback does not edit the rulebook;
+source changes need their own reviewed candidate and independent approval.
+
+After an approved source, rule, configuration, case or runtime change, generate a
+new inventory and assessment. Compare the new manifest's per-unit binding
+against the recorded binding before reusing a result. Version 1 includes the full
+assessment context in each binding, so a changed context conservatively
+invalidates every unit and its dependants. Re-run the baseline and pilot/full
+verification under the new exact pins, preserving old reports for audit. Do not
+rewrite a saved report or attach it to a new digest.
+
+Use `calliope improve capabilities --json` before exposing improvement controls.
+Only advertised bounded strategy operations are available. A reviewed rule update
+or successful migration is not reinforcement learning; cross-run learned policies
+and model-weight training are not provided by this kit.
+
+## Evidence and distribution
+
+Retain the inventory, reviewed plan/request digests, rulebook, work manifest,
+baseline and candidate reports, command/cleanup receipts, source candidate,
+accounting measurements and independent review reference. An example complete
+verification and adversarial qualification can be generated by
+`scripts/qualification/migration-baseline.mjs` from the source repository; its
+arguments require an empty owned directory and an exact local image/runtime.
+The packaged [example plan](migration-example-plan.json) and
+[completed report](migration-example-report.json) are a snapshot from an actual
+disposable local run. Its source commit IDs refer to that synthetic repository;
+this example is not evidence for a user project. Review the pair without executing
+code using `migration review-evidence --plan docs/migration-example-plan.json
+--report docs/migration-example-report.json --json` (on one shell line).
+
+The qualification checks unsupported adapters, stale source and rule pins, a
+broken baseline, an ineffective negative control, a regressing candidate,
+distinct baseline/candidate approvals and actual container cleanup.
+
+Schemas and deterministic helpers ship in `dist/migration`. The example is
+available offline through `migration example --json`; a host can consume the same
+structured artifacts through `dist/migration/index.js` without Cy. Match the
+package source and exact kit/verifier hashes to the reviewed artifact. Keep
+replay evidence separate from current execution authority.
+
+Reference evaluated: Anthropic's code-migration kit at
+[`cf91c9d5068d9aaf95a36164169f08c3e636c909`](https://github.com/anthropics/code-migration-kit-with-claude-code/tree/cf91c9d5068d9aaf95a36164169f08c3e636c909),
+licensed Apache-2.0 and described by its authors as unmaintained reference code.
+No upstream script, prompt or template is copied into this implementation, and
+no upstream code is executed by this playbook. Future reuse requires a separate
+code audit, tests and retention of its required license/notices.

package/docs/migration-verification.md

@@ -0,0 +1,177 @@
+# Migration behavior verification
+
+The `javascript-to-typescript-cli/v1` adapter compares self-contained JavaScript
+`.mjs` and TypeScript `.mts` command-line programs through their public interface:
+one argument, stdout bytes, stderr bytes and exit status. It runs the original,
+a known regression and the candidate in the existing native isolated-command
+backend. No model, new scheduler or repository-wide translation is involved.
+
+```sh
+calliope migration example --json
+calliope migration verification-schema --json
+calliope migration review-verification --plan verification.json --json
+calliope migration verify --repository /path/to/repository --plan verification.json --approve REVIEW_DIGEST --json
+```
+
+`example` emits files and cases as JSON without installing, writing or executing
+them. The example sums an array of safe integers, including empty, negative and
+invalid inputs; its known-bad target adds an extra one per input. Its wrong result
+has the same byte length as the correct result. To use it, save its four
+files in a disposable repository and commit them. Create a plan from the emitted
+cases, negative control and limits, with these additional fields:
+
+- `format`: `calliope.migration.verification-plan/v1`.
+- `adapter` and `verifier`: the example's `javascript-to-typescript-cli/v1` and
+  `byte-parity-v1` identities.
+- `runtime`: an already present Linux Docker image's full `sha256:...` ID and
+  exact Node version (`v24.x.y`). The runtime probe verifies the actual version;
+  the helper never pulls an image.
+- `source`, `candidate`, `negative`, `rules`: each has `revision` (full commit ID),
+  `path` (repository-relative file) and `object` (the exact Git blob ID). Use
+  `migration inventory` to obtain those identities. Different roles may use
+  different commits in the same repository. Each file must be regular UTF-8 and
+  at most 64 KiB; source is `.mjs`, candidate/negative are `.mts`.
+
+Review the full plan before passing its returned digest to `verify`. Changing a
+case, rule pin, program pin, runtime or limit changes that digest. A mismatched
+approval does not execute code. The schema is a transport contract; native
+validation additionally checks byte bounds, related fields and Git object pins.
+
+## Evidence and outcomes
+
+### Establish a baseline before implementation
+
+An original-system baseline does not need a candidate commit. Discover
+`verify-baseline` and `review-baseline-evidence` in `migration capabilities`, then
+use the separate baseline contracts:
+
+```sh
+calliope migration baseline-schema --json
+calliope migration review-baseline --plan baseline.json --json
+calliope migration verify-baseline --repository /path/to/repository --plan baseline.json --approve REVIEW_DIGEST --json
+calliope migration review-baseline-evidence --plan baseline.json --report baseline-report.json --json
+```
+
+The plan format is `calliope.migration.baseline-plan/v1`. It has the same adapter,
+verifier, runtime, source, negative-control, rules, cases and limits as a full
+verification plan, with **no `candidate` field**. Candidate pins are refused rather
+than ignored. Review approves exactly the source, negative and rules pins and
+`cases.length + 2` commands: runtime, original cases and one known regression.
+No candidate is read, mounted or executed. The same isolated command backend,
+inherited deadline, reservation callback and cleanup checks apply.
+
+Success returns `baseline-verified` in a `calliope.migration.baseline-report/v1`.
+Read-only review returns `baseline-observations` in a distinct baseline evidence
+review. Neither is candidate verification or authorization to implement. A host
+must establish provenance and review scope independently; hashes alone do not
+authenticate the observations. Failed, cancelled, incomplete or contradictory
+baseline evidence remains nonpassing.
+
+Library hosts use `analyzeBaselinePlan`, `verifyMigrationBaseline` and
+`analyzeBaselineEvidence`, with the existing `VerificationOptions` host callbacks.
+After implementation, create a normal full verification plan with the exact
+candidate commit and obtain separate approval. Full verification still repeats
+baseline and known-regression checks before testing the candidate. Baseline
+approval digests and reports cannot be substituted for full verification.
+
+For a native isolated implementation task, the host can create that commit with
+the [generated source candidate](source-candidates.md) capability. It consumes the
+exact collected task/attempt patch, requires separate review and preserves the
+source checkout. Its `candidate` status explicitly requires independent
+verification; it cannot stand in for a passing verification report.
+
+The existing full-verification v1 formats and digests are unchanged. Baseline
+evidence also cannot satisfy assessment's passing candidate-pilot requirement.
+
+### Full verification
+
+Before reading program contents, the host approves the exact plan and read pins.
+Verification then reads immutable Git blobs, checks their identities and creates
+private temporary snapshots. Dirty and untracked checkout files are preserved.
+The selected image sees only the current role's snapshot, read-only, with no host
+credentials, network or writable host mount. Existing CPU/memory/process/output
+limits and container-cleanup receipts apply. No package installation occurs.
+
+The comparator's adversarial self-test runs first. Execution checks the runtime,
+every baseline case, then the pinned negative-control case. The negative control
+must both reproduce its declared wrong behavior and differ from the baseline.
+Only then does it execute candidate cases. Stdout/stderr hashes are computed on
+raw captured bytes before display redaction; truncated or legacy receipts without
+those hashes cannot pass. Reports omit display output, retaining hashes, byte
+counts, exit status, commands and native cleanup evidence.
+
+| Outcome | Meaning |
+| --- | --- |
+| `passed` | All declared cases passed after baseline and negative-control checks. |
+| `input-failure` | A program/rule pin or snapshot is stale, oversized or unsupported. |
+| `baseline-failure` | The original does not satisfy the proposed contract. |
+| `verifier-failure` | Comparator or known-regression validation failed. |
+| `regression` | The candidate differs on a declared case. |
+| `environment-failure` | Runtime, observation, deadline, host allowance or cleanup prevented complete evidence. |
+| `cancelled` | The caller cancelled; retained observations are not a pass. |
+
+Reports bind the plan digest, exact source/candidate/negative/rule pins, runtime,
+verifier version and observations. Their own digest covers the canonical body
+excluding `digest`. A passing report applies only to those commits and cases. It
+does not imply that a newer branch tip passed. Replan changed inputs and obtain
+independent review of changes to success criteria; this helper does not supply
+that review authority or automatically invalidate a larger workflow's units.
+
+## Host policy and limits
+
+Library hosts use `analyzeVerificationPlan` and `verifyMigration`. The mandatory
+`approve` callback receives the plan digest, canonical repository, exact read pins, image,
+command count and time limit. Intersect these with existing task grants before
+approving. `deadline` can shorten the execution allowance; `reserveCommand` can
+charge or deny each command through the host's existing ledger. These callbacks
+are trusted host code, never fields accepted from agent-authored JSON.
+
+There are 1–8 cases, at most 18 verification commands, 100–10,000ms per command and
+at most 300,000ms after approval. Read-only Git inspection shares that deadline.
+Cleanup may take the shared runner's additional bounded cleanup
+time. A missing or unconfirmed execution receipt retains the exact temporary
+workspace for inspection; the report identifies it. Confirmed cleanup allows
+removal of the disposable snapshots. Existing repository files are not deleted.
+
+The CLI's explicit approval applies to one verification invocation. It does not
+create a reusable permission grant or replenish an existing hosted allowance.
+Hosted callers must carry their parent deadline and command reservations forward.
+
+## Current support boundary
+
+This is one small language-pair adapter and verification phase of #414. It does
+not prove general program equivalence, type-check TypeScript, install dependencies,
+verify imported project modules, dispatch migration workers or approve rollout.
+Application/framework adapters, source dependency analysis, rule-update review,
+unit invalidation, headless tool discovery and Cykick/Astrolift workflow integration
+remain separate work. Keep generated, reviewed and verified states distinct.
+## Review saved observations
+
+`calliope migration review-evidence --plan plan.json --report report.json --json`
+re-evaluates a saved report without Docker, repository access, provider credentials
+or executing any program. Exit 0 means `passing-observations`; exit 1 means
+nonpassing or invalid evidence. `migration evidence-schema` returns the packaged
+JSON Schema. Hosts can import `analyzeVerificationEvidence` from `migration/index`.
+
+The review binds the exact plan digest, source/candidate/negative/rules pins,
+runtime, case order and command arguments. It checks report integrity, complete
+command coverage, distinct container identities, cleanup receipts, raw output
+fingerprints and exit status. It recomputes every comparison, including baseline
+and known-regression observations. A rewritten `passed` label or `matches` value
+cannot override contradictory observations, even after recomputing the JSON digest.
+The comparator runs its adversarial self-check before inspecting a report.
+
+A valid interrupted report remains `not-passing`, with finding codes and observation
+indexes; malformed or differently bound reports are refused. Legacy receipts that
+lack explicit cleanup or raw output evidence cannot receive passing status. Review
+accepts native confirmed absence and bounded cleanup recovery receipts. It does
+not contact the daemon to assert that a recorded container is absent now.
+
+The result contains plan/report digests, case IDs and findings, never raw program
+output, retained workspace paths or free-form report reasons. A digest proves
+consistency, not provenance: anyone able to fabricate all observations can also
+fabricate their digest. **Passing observations do not authenticate their producer,
+supply independent review, establish general behavioral equivalence, or authorize
+migration dispatch.** Assessment hosts must establish trusted evidence provenance
+and review coverage separately. Changing the source, cases, rules or target/runtime
+requires evidence for a new exact plan; old evidence is never silently rebound.

package/docs/releases/3.6.0.md

@@ -0,0 +1,43 @@
+# Calliope CLI 3.6.0
+
+This release adds reviewed host execution and a packaged code migration kit.
+It retains the provider retirement and credential-redaction fixes from 3.5.4.
+
+## Reviewed host execution
+
+Embedded hosts can bind remote children to a reviewed native run, its owner,
+workspace and original allowance. The parent ledger retains reservations across
+process restarts and refuses new work after exhaustion, cancellation or revoked
+authority. Native questions, outcomes and retained sessions preserve their account
+binding. This adds no separate scheduler or replacement root budget.
+
+`calliope --version --json` advertises headless protocol 1, delegation 1 and
+workspace binding 1. ACP remains protocol 1. Hosts must negotiate the applicable
+capability and provision the reviewed authority explicitly; an ordinary ACP
+session is not delegated execution.
+
+See [the delegation contract](../delegation-ledger.md) for credential delivery,
+private retained state, workspace binding and the runnable process qualification.
+The source qualification uses deterministic inference with real ledger and child
+processes. Deployment through Astrolift and Cykick requires separate consumer
+qualification; publishing this CLI does not establish their remote acceptance.
+
+## Code migration kit
+
+`calliope migration` packages committed-source inventory, baseline verification,
+candidate verification and reviewed assessment. The initial adapter covers
+self-contained JavaScript `.mjs` to TypeScript `.mts` command-line programs on a
+pinned Node 24 Linux image. Verification preserves exact source/rule/runtime pins,
+tests a declared negative control and retains command and cleanup evidence.
+
+The [migration playbook](../migration-playbook.md), schemas and example evidence
+ship with the npm package. Verification requires the reviewed digest and an
+already-present container image. Reports do not authorize execution, and passing
+the declared cases does not prove general program equivalence. The kit reuses
+native execution authority and bounded improvement; it does not provide
+cross-run learned policies or model-weight training.
+
+Refs: [#414](https://github.com/calliopeai/calliope-cli/issues/414),
+[#415](https://github.com/calliopeai/calliope-cli/issues/415),
+[#413](https://github.com/calliopeai/calliope-cli/issues/413),
+[#293](https://github.com/calliopeai/calliope-cli/issues/293).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calliopelabs/cli",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "The private-AI agent CLI - one terminal agent for any model backend, including the ones you run yourself",
   "keywords": [
     "ai",
@@ -34,7 +34,11 @@
   "files": [
     "dist",
     "README.md",
-    "scripts/verify-runlog.mjs"
+    "scripts/verify-runlog.mjs",
+    "docs/migration-*.md",
+    "docs/migration-example-*.json",
+    "docs/delegation-ledger.md",
+    "docs/releases/3.6.0.md"
   ],
   "scripts": {
     "build": "tsc && chmod +x dist/bin.js",
@@ -44,6 +48,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ahp-protocol": "npm run build && node --test scripts/qualification/ahp-protocol.mjs",
+    "test:reviewed-host": "npm run build && node scripts/qualification/reviewed-host.mjs",
     "test:native-policy": "npm run build && node --test scripts/qualification/native-policy.mjs",
     "bench": "node bench/run.mjs",
     "bench:cold": "npm run build && node bench/cold-start.mjs",