feat(contracts): define non-authorizing install plans

[davida-ps]

User description

Purpose

Define the reviewable plan that a future clawsec-core-<harness> must produce before any skill installation is authorized or executed.

This is a contract-only PR. It does not add or change an installable skill.

Stack

• Base: davida-ps/result-envelope-contract-v1 / feat(contracts): add result envelope v1 #321
• One commit ahead of base: fdbadef
• Depends transitively on the lifecycle SemVer and component-metadata contract drafts.
• No merge is requested while the contract language, SemVer lifecycle, and new skill architecture are still under review.

Concrete behavior

• Adds clawsec.install-plan/v1 for core.plan-release.
• A ready plan contains every proposed action, exact target, before/after state, expected effect, rollback source/order, artifact identity, staged-input identity, target-instance identity, and future core.install-release context.
• ready means complete enough to review. It does not grant operator authorization and it does not claim execution.
• A blocked plan contains at least one blocker and contains no actions, effects, rollback order, apply context, or confirmation challenge.
• Fresh installation only: managed entries require absent prestate. Update, remove, migration, receipt, apply, and interrupted-operation recovery are separate future contracts.
• All filesystem actions are POSIX, portable, scope-relative, and anchored to one explicit scope_root.
• Every installed directory and file is represented by an exact install-tree entry. Empty/intermediate directories are explicit. File digests, lengths, modes, action targets, reported effects, and rollback records must agree.
• Declared transformations reference an earlier exact managed source file and one release-manifest entry digest. This contract validates the binding shape but deliberately leaves manifest membership, signatures, catalog authorization, advisory verification, and provenance unverified.
• Plans are bounded to 1 MiB, 64 actions/outputs, 256 MiB planned output, and 256 MiB total rollback capture work. Repeated equal preimage digests still count once per transformed target.
• Caller-owned plan and referenced metadata bytes are copied through bounded fixed-length views. Oversized, shadowed-length, hostile-resolver, and concurrent-mutation cases fail closed or remain internally coherent.

Harness adapters

• OpenClaw: may produce a ready exact-tree plan for one declared skill root and explicit reload behavior.
• NanoClaw v2: binds one selected checkout, checkout/ancestor/dependency-lock identity, additive skill placement, declared host transformations, immutable coding-harness identity, complete postimage/host/skill validation, and container/agent-runner validation when those areas are touched.
• Hermes: native installation remains prototype_pending; v1 can only produce a blocked unsupported_native_operation plan.
• PicoClaw: native installation remains prototype_pending; v1 can only produce a blocked unsupported_native_operation plan.

The NanoClaw fixture is pinned to the audited v2.1.17 contract surface. It is a contract fixture, not a blanket current-version support claim. No retired branch-merge, /workspace/ipc, or container-owned trust model is introduced.

Deliberate non-goals

• No installer or apply executor.
• No operator-confirmation implementation.
• No install, bootstrap, attempt, removal, tombstone, or migration receipt.
• No catalog/root/signature authority.
• No advisory engine.
• No runtime core, suite, or guardian skill.
• No hook, scheduler, job, service, automatic remediation, or persistence change.
• No docs, release pipeline, tag, release, store publication, or catalog activation.

Verification

Final clean-room lab preserved at:

davida@20.14.133.241:/tmp/clawsec-install-plan-final.GvyF93/repo

The lab was freshly cloned from https://github.com/prompt-security/clawsec.git and detached at exact base:

47a63a0288ebd975a2287cf76b878e68a20f2565

All 17 copied files matched the local candidate by SHA-256. Audit-critical final hashes:

• validator: e5cc274c422ab510dd089ba43b3e73e7c26cdfe457cf2f2c98f557ead544b161
• test: 4435578daa2da85d7387d2a9aee801732c97ceecba0b54fbf8cee6cbc1903d88

Passed remotely:

• npm ci
• node --check for all changed/new .mjs files
• npm run test:install-plan-contract
• npm run test:metadata-contracts
• npm run test:result-envelope-contract
• node scripts/test-skill-lifecycle-semver.mjs
• npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0
• npx tsc --noEmit
• npm run build
• git diff --check
• exact 17-path status audit

Two independent final read-only audits reported no P0, P1, or P2 findings against the exact hashes above.

npm ci also reported three dependency-audit findings (one moderate, two high). package-lock.json is unchanged, and dependency remediation is intentionally outside this contract PR.

Review focus

• Is ready vs. blocked language sufficiently clear that no authorization or execution is implied?
• Are the common contract and four adapter boundaries correctly separated?
• Is the NanoClaw v2 checkout/transformation model faithful without overstating support?
• Are the v1 resource ceilings and exact-tree disclosure rules acceptable for the first core implementation?
• Does this unit fit the new lifecycle SemVer and core -> suite -> optional guardian design before any skill implementation starts?

---

Generated description

Below is a concise technical summary of the changes proposed in this PR:
Define the clawsec.install-plan/v1 contract and policy around core.plan-release, so install-plan-v1.schema.json and install-plan-policy.json can describe non-authorizing ready and blocked plans for exact-tree installation. Add adapter-specific validation for openclaw, hermes, nanoclaw, and picoclaw through the install-plan schemas, registry, and validator scripts that enforce future core.install-release bindings and rollback rules.

Topic	Details
Adapter checks	Add adapter-specific validation and contract tests for openclaw, hermes, nanoclaw, and picoclaw install flows. Modified files (13) contracts/schemas/install/adapters/hermes-v1.schema.json contracts/schemas/install/adapters/nanoclaw-v2.schema.json contracts/schemas/install/adapters/openclaw-v1.schema.json contracts/schemas/install/adapters/picoclaw-v1.schema.json package.json scripts/ci/install-plan-adapters/hermes.mjs scripts/ci/install-plan-adapters/nanoclaw-v2.mjs scripts/ci/install-plan-adapters/openclaw.mjs scripts/ci/install-plan-adapters/picoclaw.mjs scripts/ci/install-plan-adapters/registry.mjs scripts/ci/validate_clawsec_install_plan.mjs scripts/ci/validate_clawsec_result_envelope.mjs scripts/test-skill-install-plan-contract.mjs Latest Contributors(1) User Commit Date David.a@prompt.security feat(contracts): defin... July 24, 2026
Plan contract	Define the non-authorizing install-plan schema, policy limits, and ready/blocked fixtures for core.plan-release. Modified files (4) contracts/fixtures/install-plan-v1/valid/nanoclaw-v2-blocked-unowned-path.json contracts/fixtures/install-plan-v1/valid/nanoclaw-v2-ready.json contracts/install-plan-policy.json contracts/schemas/install/install-plan-v1.schema.json Latest Contributors(1) User Commit Date David.a@prompt.security feat(contracts): defin... July 24, 2026

_{Review this PR on Baz | Customize your next review}