blun-king-cli 9.1.65 → 9.1.67

package/standard-skills/venture-flywheel/policy/repository-trust.cjs

@@ -0,0 +1,229 @@
+'use strict';
+
+const TRUST_LEVELS = Object.freeze([
+  'UNTRUSTED',
+  'TRUSTED_LOCAL',
+  'TRUSTED_DEPLOY',
+]);
+
+const CAPABILITIES = Object.freeze([
+  'deploy.production',
+  'network.external',
+  'network.none',
+  'network.registry.read',
+  'repo.metadata.read',
+  'repo.read',
+  'sandbox.execute',
+  'workspace.write',
+  'worktree.create',
+]);
+
+const BASE_CAPABILITIES = Object.freeze([
+  'network.none',
+  'repo.metadata.read',
+  'repo.read',
+]);
+const LOCAL_CAPABILITIES = Object.freeze([
+  ...BASE_CAPABILITIES,
+  'sandbox.execute',
+  'workspace.write',
+  'worktree.create',
+].sort());
+const TRUST_CEILINGS = Object.freeze({
+  UNTRUSTED: BASE_CAPABILITIES,
+  TRUSTED_LOCAL: LOCAL_CAPABILITIES,
+  TRUSTED_DEPLOY: CAPABILITIES,
+});
+const TRUST_FIELDS = new Set([
+  'project_id',
+  'account_id',
+  'trust_level',
+  'version',
+  'granted_capabilities',
+  'denied_capabilities',
+  'last_event_id',
+]);
+const REQUEST_FIELDS = new Set([
+  'event_id',
+  'expected_version',
+  'from_trust_level',
+  'to_trust_level',
+  'granted_capabilities',
+  'denied_capabilities',
+]);
+
+function uvfError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireText(value, field, code = 'UVF_INVALID_TRUST_RECORD') {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw uvfError(code, `${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function assertKnownFields(value, allowed, label, code) {
+  const unknown = Object.keys(value).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) {
+    throw uvfError(code, `unknown ${label} fields: ${unknown.sort().join(', ')}`);
+  }
+}
+
+function validateCapabilityList(value, field, code) {
+  if (!Array.isArray(value)) throw uvfError(code, `${field} must be an array`);
+  const unique = new Set();
+  for (const capability of value) {
+    if (typeof capability !== 'string' || !CAPABILITIES.includes(capability)) {
+      throw uvfError(code, `${field} contains an unknown capability: ${String(capability)}`);
+    }
+    if (unique.has(capability)) throw uvfError(code, `${field} contains a duplicate: ${capability}`);
+    unique.add(capability);
+  }
+  return [...unique].sort();
+}
+
+function validatePartition(grantedInput, deniedInput, code) {
+  const granted = validateCapabilityList(grantedInput, 'granted_capabilities', code);
+  const denied = validateCapabilityList(deniedInput, 'denied_capabilities', code);
+  const combined = [...granted, ...denied];
+  if (new Set(combined).size !== CAPABILITIES.length
+    || [...new Set(combined)].sort().some((capability, index) => capability !== CAPABILITIES[index])) {
+    throw uvfError(code, 'capability grants and denials must form a complete non-overlapping partition');
+  }
+  return { granted, denied };
+}
+
+function validateProjectIdentity(identity) {
+  if (!isRecord(identity)) throw uvfError('UVF_INVALID_PROJECT_IDENTITY', 'project identity must be an object');
+  requireText(identity.project_id, 'project_id', 'UVF_INVALID_PROJECT_IDENTITY');
+  requireText(identity.account_id, 'account_id', 'UVF_INVALID_PROJECT_IDENTITY');
+}
+
+function validateTrustRecord(trust) {
+  if (!isRecord(trust)) throw uvfError('UVF_INVALID_TRUST_RECORD', 'repository trust must be an object');
+  assertKnownFields(trust, TRUST_FIELDS, 'trust', 'UVF_INVALID_TRUST_RECORD');
+  requireText(trust.project_id, 'project_id');
+  requireText(trust.account_id, 'account_id');
+  if (!TRUST_LEVELS.includes(trust.trust_level)) {
+    throw uvfError('UVF_INVALID_TRUST_RECORD', `unknown trust level: ${String(trust.trust_level)}`);
+  }
+  if (!Number.isSafeInteger(trust.version) || trust.version < 0) {
+    throw uvfError('UVF_INVALID_TRUST_RECORD', 'version must be a non-negative integer');
+  }
+  if (trust.last_event_id !== null) requireText(trust.last_event_id, 'last_event_id');
+  const partition = validatePartition(
+    trust.granted_capabilities,
+    trust.denied_capabilities,
+    'UVF_INVALID_TRUST_RECORD',
+  );
+  const ceiling = new Set(TRUST_CEILINGS[trust.trust_level]);
+  const excessive = partition.granted.filter((capability) => !ceiling.has(capability));
+  if (excessive.length > 0) {
+    throw uvfError(
+      'UVF_CAPABILITY_TRUST_VIOLATION',
+      `${trust.trust_level} cannot grant: ${excessive.join(', ')}`,
+    );
+  }
+  return partition;
+}
+
+function createRepositoryTrust(projectIdentity) {
+  validateProjectIdentity(projectIdentity);
+  const granted = [...BASE_CAPABILITIES].sort();
+  return Object.freeze({
+    project_id: projectIdentity.project_id,
+    account_id: projectIdentity.account_id,
+    trust_level: 'UNTRUSTED',
+    version: 0,
+    granted_capabilities: Object.freeze(granted),
+    denied_capabilities: Object.freeze(CAPABILITIES.filter((capability) => !granted.includes(capability))),
+    last_event_id: null,
+  });
+}
+
+function validateTransitionRequest(request) {
+  if (!isRecord(request)) {
+    throw uvfError('UVF_INVALID_TRUST_REQUEST', 'trust transition request must be an object');
+  }
+  assertKnownFields(request, REQUEST_FIELDS, 'trust transition', 'UVF_INVALID_TRUST_REQUEST');
+  requireText(request.event_id, 'event_id', 'UVF_INVALID_TRUST_REQUEST');
+  if (!Number.isSafeInteger(request.expected_version) || request.expected_version < 0) {
+    throw uvfError('UVF_INVALID_TRUST_REQUEST', 'expected_version must be a non-negative integer');
+  }
+  for (const field of ['from_trust_level', 'to_trust_level']) {
+    if (!TRUST_LEVELS.includes(request[field])) {
+      throw uvfError('UVF_INVALID_TRUST_REQUEST', `unknown ${field}: ${String(request[field])}`);
+    }
+  }
+  return validatePartition(
+    request.granted_capabilities,
+    request.denied_capabilities,
+    'UVF_INVALID_TRUST_REQUEST',
+  );
+}
+
+function transitionRepositoryTrust(current, request) {
+  validateTrustRecord(current);
+  const partition = validateTransitionRequest(request);
+  if (request.expected_version !== current.version) {
+    throw uvfError(
+      'UVF_TRUST_VERSION_CONFLICT',
+      `expected version ${request.expected_version}, current version ${current.version}`,
+    );
+  }
+  if (request.from_trust_level !== current.trust_level) {
+    throw uvfError(
+      'UVF_TRUST_STATE_CONFLICT',
+      `expected trust level ${request.from_trust_level}, current level ${current.trust_level}`,
+    );
+  }
+  const fromIndex = TRUST_LEVELS.indexOf(current.trust_level);
+  const toIndex = TRUST_LEVELS.indexOf(request.to_trust_level);
+  if (toIndex === fromIndex || toIndex > fromIndex + 1) {
+    throw uvfError(
+      'UVF_INVALID_TRUST_TRANSITION',
+      `transition ${current.trust_level} -> ${request.to_trust_level} is not allowed`,
+    );
+  }
+
+  const ceiling = new Set(TRUST_CEILINGS[request.to_trust_level]);
+  const excessive = partition.granted.filter((capability) => !ceiling.has(capability));
+  if (excessive.length > 0) {
+    throw uvfError(
+      'UVF_CAPABILITY_TRUST_VIOLATION',
+      `${request.to_trust_level} cannot grant: ${excessive.join(', ')}`,
+    );
+  }
+  const missingBase = BASE_CAPABILITIES.filter((capability) => !partition.granted.includes(capability));
+  if (missingBase.length > 0) {
+    throw uvfError(
+      'UVF_CAPABILITY_TRUST_VIOLATION',
+      `trust records must retain baseline capabilities: ${missingBase.join(', ')}`,
+    );
+  }
+
+  return Object.freeze({
+    project_id: current.project_id,
+    account_id: current.account_id,
+    trust_level: request.to_trust_level,
+    version: current.version + 1,
+    granted_capabilities: Object.freeze(partition.granted),
+    denied_capabilities: Object.freeze(partition.denied),
+    last_event_id: request.event_id,
+  });
+}
+
+module.exports = {
+  CAPABILITIES,
+  TRUST_LEVELS,
+  TRUST_CEILINGS,
+  createRepositoryTrust,
+  transitionRepositoryTrust,
+};

package/standard-skills/venture-flywheel/references/CAPABILITY-MAP.md

@@ -0,0 +1,34 @@
+# Capability Map: Universal Venture Flywheel
+
+Source direction: UVF-Core RFC 2.0.0. This map keeps each rollout phase
+independently testable and prevents the advisor, executor, and deployment gate
+from becoming one authority.
+
+| Module id | Responsibility | Depends on |
+|---|---|---|
+| contracts-trust | Schemas, project scope, trust, capabilities, event log, state machine | - |
+| venture-advisor | Read-only discovery, metrics, baselines, proposals, strategic-authority bridge | contracts-trust |
+| local-execution | Leases, isolated worktrees, sandbox, scoped execution, verification bundles | contracts-trust, venture-advisor |
+| approval-deployment | Exact-state approval, adapter preflight, idempotency, staging, rollback | contracts-trust, local-execution |
+| observation | Post-deployment metrics, guardrails, attribution, inconclusive outcomes | contracts-trust, approval-deployment |
+| controlled-learning | Effectiveness history and human-approved bounded adaptation | observation |
+
+Build order:
+
+```text
+contracts-trust
+  -> venture-advisor
+  -> local-execution
+  -> approval-deployment
+  -> observation
+  -> controlled-learning
+```
+
+The first implementation slice inside `contracts-trust` is `state-events`:
+canonical run transitions plus a hash-linked, secret-rejecting event envelope.
+It has no execution capability.
+
+The second slice is `identity-trust`: deterministic project identity from
+repository facts plus authenticated host context, explicit repository trust
+transitions, and deny-by-default capability decisions. It is also side-effect
+free and grants no execution path by itself.

package/standard-skills/venture-flywheel/references/SPEC-phase0-identity-trust.md

@@ -0,0 +1,77 @@
+# Spec: UVF Phase 0 Identity, Trust, and Capability Contracts
+
+## Objective
+
+Provide a deterministic policy boundary before any UVF repository action.
+Project identity combines observed repository facts with a separately supplied
+authenticated host context. Repository trust starts at `UNTRUSTED`, changes
+only through versioned explicit transitions, and partitions every known
+capability into granted or denied. Capability evaluation fails closed.
+
+This slice does not inspect a repository, execute a command, create a worktree,
+open a network connection, persist trust, or approve an external action.
+
+## Public Contracts
+
+```js
+const identity = deriveProjectIdentity(repositoryFacts, authenticatedHostContext);
+const trust = createRepositoryTrust(identity);
+const nextTrust = transitionRepositoryTrust(trust, request);
+const decision = evaluateCapability({
+  project_identity: identity,
+  repository_trust: nextTrust,
+  capability: 'sandbox.execute',
+  execution_scope: 'isolated_worktree',
+});
+```
+
+Repository facts cannot contain an account, user, or owner identity. The
+authenticated account enters only through the second argument. Equivalent SSH
+and HTTPS remotes produce the same canonical repository identity.
+
+## Trust Levels
+
+- `UNTRUSTED`: metadata and repository reads only.
+- `TRUSTED_LOCAL`: explicit local capabilities may run later, but write and
+  execution capabilities require an isolated worktree.
+- `TRUSTED_DEPLOY`: external capabilities may be requested, but they return
+  `approval_required`; this contract never approves them.
+
+Upgrades are sequential. Downgrades may return directly to a lower trust level.
+Every transition checks `expected_version`, records an event ID, and supplies a
+complete non-overlapping grant/deny partition for the known capability set.
+
+## Commands
+
+```text
+node --test test/venture-flywheel-trust.test.js
+node --check standard-skills/venture-flywheel/identity/project-identity.cjs
+node --check standard-skills/venture-flywheel/policy/repository-trust.cjs
+node --check standard-skills/venture-flywheel/policy/capability-engine.cjs
+npm test
+```
+
+## Testing Strategy
+
+- Equivalent repository observations must derive the same identity.
+- A different authenticated account must derive a different project ID.
+- Identity fields injected into repository facts must be rejected.
+- Unknown repositories may read but cannot write, execute, or use network.
+- Forged grants above a trust ceiling remain denied.
+- Local write and execution require an isolated worktree.
+- External and irreversible capabilities never return `allow`.
+- Stale or skipped trust upgrades are rejected.
+- Schemas are strict and all modules remain free of I/O primitives.
+
+## Success Criteria
+
+- Cross-account and cross-project evaluations fail closed.
+- Capability decisions are one of `allow`, `deny`, or `approval_required`.
+- Every known capability appears exactly once in a trust record.
+- Exported collections and returned records are deeply immutable.
+- Focused mutation probes and the complete package suite are green.
+
+## Boundary
+
+Persistence, repository detection, command execution, worktree creation,
+network adapters, approval issuance, and deployment remain later slices.

package/standard-skills/venture-flywheel/references/SPEC-phase0-state-events.md

@@ -0,0 +1,93 @@
+# Spec: UVF Phase 0 State and Event Contracts
+
+## Objective
+
+Provide the smallest deterministic foundation that makes every UVF run state
+transition auditable. The module rejects illegal and stale transitions, gates
+terminal states on required evidence, creates hash-linked event envelopes, and
+rejects secret-shaped audit payloads.
+
+This slice does not execute commands, inspect repositories, write event files,
+open network connections, or expose a user-facing UVF command.
+
+## Commands
+
+Focused test:
+
+```text
+node --test test/venture-flywheel-state.test.js
+```
+
+Full suite:
+
+```text
+npm test
+```
+
+Syntax checks:
+
+```text
+node --check standard-skills/venture-flywheel/state/task-state-machine.cjs
+node --check standard-skills/venture-flywheel/state/execution-event.cjs
+```
+
+## Project Structure
+
+```text
+standard-skills/venture-flywheel/
+  SKILL.md
+  references/
+  schemas/run-transition.schema.json
+  schemas/execution-event.schema.json
+  state/task-state-machine.cjs
+  state/execution-event.cjs
+test/venture-flywheel-state.test.js
+```
+
+## Code Style
+
+CommonJS, pure functions, frozen exported contracts, explicit machine-readable
+error codes, no hidden I/O:
+
+```js
+const next = transitionRun(current, {
+  event_id: 'evt_01J...',
+  expected_version: current.version,
+  from_state: current.state,
+  to_state: 'profiled',
+});
+```
+
+## Testing Strategy
+
+- Small unit tests cover the canonical path and every guard direction.
+- Mutation-style red probes attempt transition skipping, stale writes, missing
+  completion evidence, broken hash links, event mutation, and secret payloads.
+- The standard-skill bootstrap test proves the contract ships with BLUN King.
+- The full package suite protects unrelated console behavior.
+
+## Boundaries
+
+- Always: validate inputs strictly, reject unknown states and fields, preserve
+  deterministic hashes, keep transitions side-effect free.
+- Ask first: change canonical transition topology, add persistence, expose a
+  CLI/MCP command, or connect repository identity.
+- Never: execute repository code, grant capabilities, perform external action,
+  include secrets in audit data, or infer approval from an event.
+
+## Success Criteria
+
+- The documented canonical forward path is accepted.
+- An illegal jump and a stale optimistic version are rejected.
+- `completed` requires final evidence and `rolled_back` requires rollback
+  evidence.
+- Every accepted transition increments the version and records its event ID.
+- Event hashes are deterministic and a mutation or broken link is detected.
+- Secret-shaped fields are rejected recursively before hashing.
+- JSON schemas reject unknown top-level fields.
+- Focused tests and the complete package suite are green.
+
+## Open Questions
+
+None inside this slice. Persistence, project identity, trust grants, and the
+full schema set remain later `contracts-trust` tasks.

package/standard-skills/venture-flywheel/schemas/capability-decision.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://blun.ai/schemas/uvf/capability-decision.schema.json",
+  "title": "UVF Capability Decision",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["capability", "decision", "reason"],
+  "properties": {
+    "capability": { "type": "string", "minLength": 1 },
+    "decision": { "enum": ["allow", "deny", "approval_required"] },
+    "reason": { "type": "string", "minLength": 1 }
+  }
+}

package/standard-skills/venture-flywheel/schemas/execution-event.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://blun.ai/schemas/uvf/execution-event.schema.json",
+  "title": "UVF Execution Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event_id",
+    "run_id",
+    "project_id",
+    "actor",
+    "event_type",
+    "occurred_at",
+    "payload",
+    "previous_event_hash",
+    "event_hash"
+  ],
+  "properties": {
+    "event_id": { "type": "string", "minLength": 1 },
+    "run_id": { "type": "string", "minLength": 1 },
+    "project_id": { "type": "string", "minLength": 1 },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id", "session_id"],
+      "properties": {
+        "type": { "enum": ["agent", "user", "system"] },
+        "id": { "type": "string", "minLength": 1 },
+        "session_id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "event_type": { "type": "string", "minLength": 1 },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "payload": { "type": "object" },
+    "previous_event_hash": {
+      "type": ["string", "null"],
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "event_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  }
+}

package/standard-skills/venture-flywheel/schemas/project-identity.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://blun.ai/schemas/uvf/project-identity.schema.json",
+  "title": "UVF Project Identity",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project_id", "account_id", "repository"],
+  "properties": {
+    "project_id": { "type": "string", "pattern": "^project:sha256:[a-f0-9]{64}$" },
+    "account_id": { "type": "string", "minLength": 1 },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host",
+        "owner",
+        "name",
+        "canonical_remote_url",
+        "local_repository_root",
+        "initial_repository_fingerprint"
+      ],
+      "properties": {
+        "host": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "canonical_remote_url": { "type": "string", "pattern": "^https://" },
+        "local_repository_root": { "type": "string", "minLength": 1 },
+        "initial_repository_fingerprint": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    }
+  }
+}

package/standard-skills/venture-flywheel/schemas/repository-trust.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://blun.ai/schemas/uvf/repository-trust.schema.json",
+  "title": "UVF Repository Trust",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "project_id",
+    "account_id",
+    "trust_level",
+    "version",
+    "granted_capabilities",
+    "denied_capabilities",
+    "last_event_id"
+  ],
+  "properties": {
+    "project_id": { "type": "string", "pattern": "^project:sha256:[a-f0-9]{64}$" },
+    "account_id": { "type": "string", "minLength": 1 },
+    "trust_level": { "enum": ["UNTRUSTED", "TRUSTED_LOCAL", "TRUSTED_DEPLOY"] },
+    "version": { "type": "integer", "minimum": 0 },
+    "granted_capabilities": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "deploy.production",
+          "network.external",
+          "network.none",
+          "network.registry.read",
+          "repo.metadata.read",
+          "repo.read",
+          "sandbox.execute",
+          "workspace.write",
+          "worktree.create"
+        ]
+      }
+    },
+    "denied_capabilities": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "deploy.production",
+          "network.external",
+          "network.none",
+          "network.registry.read",
+          "repo.metadata.read",
+          "repo.read",
+          "sandbox.execute",
+          "workspace.write",
+          "worktree.create"
+        ]
+      }
+    },
+    "last_event_id": { "type": ["string", "null"], "minLength": 1 }
+  }
+}

package/standard-skills/venture-flywheel/schemas/run-transition.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://blun.ai/schemas/uvf/run-transition.schema.json",
+  "title": "UVF Run Transition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event_id",
+    "expected_version",
+    "from_state",
+    "to_state"
+  ],
+  "$defs": {
+    "state": {
+      "enum": [
+        "discovered",
+        "profiled",
+        "configured",
+        "baseline_measured",
+        "observing",
+        "evidence_ready",
+        "proposal_created",
+        "selected_by_strategic_authority",
+        "approved_for_local_execution",
+        "executing_local",
+        "verifying",
+        "blocked",
+        "aborted",
+        "no_action",
+        "locally_verified",
+        "completed_local",
+        "waiting_approval",
+        "denied",
+        "expired",
+        "approved_exact_state",
+        "deploying",
+        "post_deploy_observation",
+        "attribution_pending",
+        "completed",
+        "rolled_back",
+        "inconclusive"
+      ]
+    }
+  },
+  "properties": {
+    "event_id": { "type": "string", "minLength": 1 },
+    "expected_version": { "type": "integer", "minimum": 0 },
+    "from_state": { "$ref": "#/$defs/state" },
+    "to_state": { "$ref": "#/$defs/state" },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "final_evidence_id": { "type": "string", "minLength": 1 },
+        "rollback_evidence_id": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}