blun-king-cli 9.1.66 → 9.1.68

package/standard-skills/venture-flywheel/references/BEISPIELE-phase0.md

@@ -0,0 +1,146 @@
+# Venture Flywheel: Beispiele für Phase 0
+
+Phase 0 stellt ausschließlich reine Verträge bereit. Sie führt keine
+Repository-Befehle aus, verwendet kein Netzwerk und führt weder Deployments
+noch Veröffentlichungen, Käufe oder ausgehende Nachrichten durch.
+
+## Öffentliche Funktionen
+
+- `deriveProjectIdentity` leitet aus Repository-Fakten und einem
+  authentifizierten Konto eine deterministische Projektidentität ab.
+- `createRepositoryTrust` erzeugt den anfänglichen Datensatz mit `UNTRUSTED`.
+- `transitionRepositoryTrust` wendet einen ausdrücklichen, versionierten
+  Trust-Wechsel an.
+- `evaluateCapability` liefert `allow`, `deny` oder `approval_required` und
+  entscheidet bei Unklarheit ablehnend.
+- `transitionRun` führt genau einen zulässigen, optimistisch versionierten
+  Zustandswechsel aus.
+- `createExecutionEvent` erzeugt ein deterministisches, hash-verkettetes
+  Prüfereignis und weist geheimnisverdächtige Felder in Nutzdaten ab.
+- `verifyEventChain` prüft Reihenfolge, Verknüpfungen und Hashes einer
+  vollständigen Ereigniskette.
+
+## Vollständiges Beispiel
+
+Das folgende CommonJS-Beispiel leitet eine Projektidentität ab, erzeugt lokalen
+Trust, vergleicht die Ausführung im Repository mit der Ausführung in einem
+isolierten Worktree, setzt einen Lauf fort, erzeugt zwei verkettete Ereignisse
+und prüft anschließend die Kette.
+
+```js
+const { deriveProjectIdentity } = require('./identity/project-identity.cjs');
+const {
+  CAPABILITIES,
+  createRepositoryTrust,
+  transitionRepositoryTrust,
+} = require('./policy/repository-trust.cjs');
+const { evaluateCapability } = require('./policy/capability-engine.cjs');
+const { transitionRun } = require('./state/task-state-machine.cjs');
+const {
+  createExecutionEvent,
+  verifyEventChain,
+} = require('./state/execution-event.cjs');
+
+const identity = deriveProjectIdentity({
+  repository_host: 'github.com',
+  repository_owner: 'example',
+  repository_name: 'venture',
+  canonical_remote_url: 'git@github.com:example/venture.git',
+  local_repository_root: 'C:/Work/venture',
+  initial_repository_fingerprint: `sha256:${'a'.repeat(64)}`,
+}, { account_id: 'account-123' });
+
+const initialTrust = createRepositoryTrust(identity);
+const localCapabilities = [
+  'network.none',
+  'repo.metadata.read',
+  'repo.read',
+  'sandbox.execute',
+  'workspace.write',
+  'worktree.create',
+];
+const granted = new Set(localCapabilities);
+const localTrust = transitionRepositoryTrust(initialTrust, {
+  event_id: 'evt-trust-local',
+  expected_version: initialTrust.version,
+  from_trust_level: initialTrust.trust_level,
+  to_trust_level: 'TRUSTED_LOCAL',
+  granted_capabilities: [...granted].sort(),
+  denied_capabilities: CAPABILITIES.filter(
+    (capability) => !granted.has(capability),
+  ),
+});
+
+const deniedInRepository = evaluateCapability({
+  project_identity: identity,
+  repository_trust: localTrust,
+  capability: 'sandbox.execute',
+  execution_scope: 'repository',
+});
+const allowedInWorktree = evaluateCapability({
+  project_identity: identity,
+  repository_trust: localTrust,
+  capability: 'sandbox.execute',
+  execution_scope: 'isolated_worktree',
+});
+
+let run = { run_id: 'run-001', state: 'discovered', version: 0 };
+run = transitionRun(run, {
+  event_id: 'evt-profiled',
+  expected_version: 0,
+  from_state: 'discovered',
+  to_state: 'profiled',
+});
+
+const firstEvent = createExecutionEvent({
+  event_id: 'evt-profiled',
+  run_id: run.run_id,
+  project_id: identity.project_id,
+  actor: { type: 'agent', id: 'agent-1', session_id: 'session-1' },
+  event_type: 'run.profiled',
+  occurred_at: '2026-08-24T10:00:00.000Z',
+  payload: {
+    from_state: 'discovered',
+    to_state: 'profiled',
+    version: run.version,
+  },
+});
+const secondEvent = createExecutionEvent({
+  event_id: 'evt-policy',
+  run_id: run.run_id,
+  project_id: identity.project_id,
+  actor: { type: 'agent', id: 'agent-1', session_id: 'session-1' },
+  event_type: 'policy.checked',
+  occurred_at: '2026-08-24T10:01:00.000Z',
+  payload: { decision: allowedInWorktree.decision },
+  previous_event_hash: firstEvent.event_hash,
+});
+
+console.log(deniedInRepository);
+console.log(allowedInWorktree);
+console.log(verifyEventChain([firstEvent, secondEvent]));
+```
+
+Erwartete Entscheidungen: Die Ausführung im Repository wird mit
+`isolated_worktree_required` abgewiesen, die Ausführung im isolierten Worktree
+wird erlaubt und die Kettenprüfung liefert `{ ok: true }`.
+
+## Wichtige Schutzregeln
+
+- Ein Repository beginnt mit `UNTRUSTED`; Trust-Hochstufungen müssen
+  nacheinander erfolgen.
+- Jeder Trust- und Laufwechsel muss die aktuelle `expected_version` verwenden.
+- `workspace.write` und `sandbox.execute` erfordern
+  `execution_scope: 'isolated_worktree'`.
+- Externe oder irreversible Fähigkeiten liefern niemals `allow`, sondern
+  höchstens `approval_required`.
+- `completed` erfordert `final_evidence_id`, `rolled_back` erfordert
+  `rollback_evidence_id` innerhalb von `evidence`.
+- Ereignisnutzdaten mit Feldern wie `token`, `password`, `secret`, `api_key`
+  oder `access_token` werden vor dem Hashen abgewiesen.
+- `no_action` ist ein gültiges Endergebnis.
+
+## Prüfung
+
+Führe `node --test test/venture-flywheel-state.test.js`,
+`node --test test/venture-flywheel-trust.test.js` und `npm test` aus.

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 }
+      }
+    }
+  }
+}