wisk 0.3.0__tar.gz

wisk-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (Ruff check)
+        run: uv run ruff check .
+
+      - name: Format (Ruff format)
+        run: uv run ruff format --check .
+
+      - name: Type check (ty)
+        run: uv run ty check
+
+      - name: Security audit (Bandit)
+        run: uv run bandit -r src/ -c pyproject.toml
+
+      - name: Dead code check (Vulture)
+        run: uv run vulture src/ --min-confidence 80
+
+      - name: Validate PEP 723 Metadata in scripts
+        run: uv run scripts/check_pep723.py
+
+      - name: Check Version Sync & Changelog Presence
+        run: uv run scripts/check_version.py
+
+      - name: Validate OKF Bundle (Normative Specs Gate)
+        run: uv run okf-parser check knowledge/ --require-spec "../specs/{slug}.md" --normative-spec
+
+      - name: Build consumer-installable wheel
+        run: uv build --wheel
+
+      - name: Smoke installed consumer golden path
+        shell: bash
+        run: |
+          WHEEL="$GITHUB_WORKSPACE/$(find dist -name 'wisk-*.whl' -print -quit)"
+          CONSUMER="$(mktemp -d)"
+          cd "$CONSUMER"
+          uvx --from "$WHEEL" wisk init .
+          test -f .wisk/manifest.json
+          uvx --from "$WHEEL" wisk session start-next "Do the best useful work available"
+          find .wisk/knowledge/experiences/runs -name '*.md' -print -quit | grep -q .
+
+      - name: Run Pytest
+        run: uv run pytest -v
+
+  test-lower-bounds:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Test Lowest Direct Dependencies
+        run: uv sync --resolution lowest-direct
+
+      - name: Run Pytest against Lowest Bounds
+        run: uv run pytest -v
+
+      - name: Validate OKF Bundle against Lowest Bounds
+        run: uv run okf-parser check knowledge/ --require-spec "../specs/{slug}.md" --normative-spec

wisk-0.3.0/.github/workflows/pypi.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

wisk-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.class
+*.egg-info/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.githooks/pre-commit

wisk-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,59 @@
+minimum_prek_version: "0.5.1"
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --no-sync ruff check
+        language: system
+        types: [python]
+
+      - id: ruff-format
+        name: ruff format check
+        entry: uv run --no-sync ruff format --check
+        language: system
+        types: [python]
+
+      - id: ty-check
+        name: ty type check
+        entry: uv run --no-sync ty check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: bandit-check
+        name: bandit security audit
+        entry: uv run --no-sync bandit -r src/ -c pyproject.toml
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: vulture-check
+        name: vulture dead code check
+        entry: uv run --no-sync vulture src/ --min-confidence 80
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pep723-check
+        name: check PEP 723 metadata in scripts
+        entry: uv run --no-sync scripts/check_pep723.py
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: version-check
+        name: check version sync & changelog presence
+        entry: uv run --no-sync scripts/check_version.py
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: okf-check
+        name: okf parser check (normative specs)
+        entry: uv run --no-sync okf-parser check knowledge/ --require-spec "../specs/{slug}.md" --normative-spec
+        language: system
+        pass_filenames: false
+        always_run: true

wisk-0.3.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: wisk
+Version: 0.3.0
+Summary: Contract-guided agent execution and persistent learning runtime built on OKF.
+Project-URL: Homepage, https://github.com/franklinbaldo/wisk
+Project-URL: Repository, https://github.com/franklinbaldo/wisk
+Author-email: Franklin Silveira Baldo <franklinbaldo@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: cyclopts>=4.0
+Requires-Dist: duckdb>=1.0
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: ibis-framework[duckdb]>=9.0
+Requires-Dist: networkx>=3.2
+Requires-Dist: okf-parser>=0.45.8
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# Wisk
+
+> **Contract-guided agent execution and persistent learning on OKF.**
+
+`wisk` is an experimental agent runtime inspired by Google Research's 2026 work on compiling agent experience into persistent knowledge for skill evolution.
+
+It uses [Open Knowledge Format (OKF)](https://github.com/franklinbaldo/okf-parser) to represent live execution state and persistent learning as an auditable typed knowledge graph.
+
+## Consumer quickstart
+
+Wisk is intended to be adopted by an existing repository, not reconstructed from a long prompt.
+
+```bash
+uvx wisk init .
+wisk session start-next "Do the best useful work available in this repository"
+```
+
+`wisk init` creates a managed `.wisk/` bundle containing compatible normative contracts, canonical learning roles, and the standard consumer profile.
+
+Managed runtime files can be refreshed with:
+
+```bash
+wisk upgrade .
+```
+
+Upgrade checks hashes before writing. If a Wisk-managed file was edited locally, the command reports a conflict and leaves the installation untouched. Consumer-owned files and runtime knowledge are never overwritten by managed upgrade.
+
+See [RFC 0005](docs/rfc/0005-consumer-golden-path.md).
+
+## What Wisk does
+
+Agent repositories face two related problems:
+
+1. a session can start from a prompt with weak structural guidance about what good execution must establish;
+2. useful lessons from execution are easily lost or mixed into unstructured memory.
+
+Wisk addresses both.
+
+A work session starts from a typed `RunSpec`, creates an intentionally incomplete `LoopRun`, and progressively records readings, goals, decisions, evidence, checks, and an outcome. `okf-parser` validation makes missing contract state visible while the work is still happening.
+
+```text
+RunSpec
+  → LoopRun scaffold
+  → RunReading / RunGoal / RunDecision / RunEvidence / RunCheck
+  → RunOutcome
+  → Experience
+```
+
+That episodic evidence feeds the canonical three-role learning cycle:
+
+```text
+Skill creates/refines a candidate
+              ↓
+Experience executes real work and records what happened
+              ↓
+Wiki synthesizes and compares durable evidence
+              ↓
+Skill revisits the candidate and decides its lifecycle
+              └──────────────→ next Experience
+```
+
+The canonical roles are **Experience**, **Wiki**, and **Skill**. `SkillEvaluation` remains available as an optional explicit benchmark/review artifact when useful.
+
+See [RFC 0004](docs/rfc/0004-canonical-learning-cycle.md).
+
+## Standard profile
+
+`wisk init` installs an opinionated but replaceable standard profile.
+
+- **Experience** is ordinary useful work and is the on-demand fallback for an explicit `session start-next` call.
+- **Wiki** becomes eligible after three new Experiences and has higher priority than ordinary Experience.
+- **Skill** becomes eligible after six new Experiences. Wiki has higher priority, so synthesis runs before skill evolution when both are due.
+
+The default rhythm is roughly:
+
+```text
+Experience × 3 → Wiki
+Experience × 3 → Wiki → Skill
+repeat
+```
+
+Those thresholds are product defaults, not universal laws. Consumers can specialize SessionTypes, RunSpecs, context policies, and cadence without redefining the core learning roles.
+
+## Contract-guided execution
+
+The run artifact is not a report written after the work. It exists before substantive execution begins.
+
+```text
+create scaffold
+→ validate with okf-parser
+→ inspect the next unsatisfied requirement
+→ perform the next useful action
+→ record typed state and evidence
+→ validate again
+→ leave a coherent outcome or handoff
+```
+
+Core concepts include `RunSpec`, `LoopRun`, `RunReading`, `RunGoal`, `RunDecision`, `RunEvidence`, `RunCheck`, `RunOutcome`, and `Handoff`.
+
+Consumers specialize `RunSpec` rather than forcing domain rules into Wisk core. Software development, journalism, legal work, research, and other domains can require different readings, evidence, checks, and result states while sharing the same runtime.
+
+## Persistent learning
+
+- **`Experience`** — episodic evidence distilled from real execution.
+- **`WikiEntry`** — durable knowledge synthesized across experiences.
+- **`AgentSkill`** — reusable procedural guidance; active and experimental versions may coexist.
+- **`SkillProposal`** — explicit change record/rationale for procedural evolution.
+- **`SkillEvaluation`** — optional explicit benchmark or review record.
+
+Procedural state is reversible while evidence and durable knowledge are cumulative. A weak candidate skill can be rejected without losing the experience that showed why it failed.
+
+## CLI
+
+Important entry points include:
+
+```text
+wisk init [repository]
+wisk upgrade [repository]
+wisk context <task>
+wisk session next
+wisk session start-next <task>
+wisk start <task> [--session-type ...]
+wisk check <run>
+wisk run reading|goal|decision|evidence|check|outcome ...
+wisk experience preview|record ...
+wisk handoff list|create|continue ...
+wisk serve
+```
+
+## Python API
+
+```python
+from wisk import Wisk
+```
+
+## Architecture boundary
+
+```text
+okf-parser
+  ├── Markdown/frontmatter parsing
+  ├── concept identity and graph traversal
+  ├── Ibis / DuckDB / NetworkX integration
+  └── schema compilation and validation
+
+wisk
+  ├── RunSpec + live execution semantics
+  ├── SessionType + policy/cadence composition
+  ├── experience and knowledge consolidation
+  ├── skill evolution lifecycle
+  ├── consumer bootstrap + upgrade
+  └── CLI + FastMCP runtime
+```
+
+Wisk does not duplicate generic parsing or validation machinery from `okf-parser`.
+
+## Development and dogfooding
+
+Wisk develops itself through the same runtime. The repository's own `knowledge/` tree is a dogfood consumer with additional development-specific SessionTypes and policies.
+
+The canonical Experience/Wiki/Skill roles are deliberately policy-neutral so other repositories do not inherit Wisk's software-development assumptions.
+
+See [docs/architecture.md](docs/architecture.md) and [docs/dogfooding.md](docs/dogfooding.md).
+
+## Development setup
+
+```bash
+git clone https://github.com/franklinbaldo/wisk.git
+cd wisk
+uv sync
+uv run wisk info
+```
+
+## License
+
+MIT © Franklin Baldo

wisk-0.3.0/README.md

@@ -0,0 +1,175 @@
+# Wisk
+
+> **Contract-guided agent execution and persistent learning on OKF.**
+
+`wisk` is an experimental agent runtime inspired by Google Research's 2026 work on compiling agent experience into persistent knowledge for skill evolution.
+
+It uses [Open Knowledge Format (OKF)](https://github.com/franklinbaldo/okf-parser) to represent live execution state and persistent learning as an auditable typed knowledge graph.
+
+## Consumer quickstart
+
+Wisk is intended to be adopted by an existing repository, not reconstructed from a long prompt.
+
+```bash
+uvx wisk init .
+wisk session start-next "Do the best useful work available in this repository"
+```
+
+`wisk init` creates a managed `.wisk/` bundle containing compatible normative contracts, canonical learning roles, and the standard consumer profile.
+
+Managed runtime files can be refreshed with:
+
+```bash
+wisk upgrade .
+```
+
+Upgrade checks hashes before writing. If a Wisk-managed file was edited locally, the command reports a conflict and leaves the installation untouched. Consumer-owned files and runtime knowledge are never overwritten by managed upgrade.
+
+See [RFC 0005](docs/rfc/0005-consumer-golden-path.md).
+
+## What Wisk does
+
+Agent repositories face two related problems:
+
+1. a session can start from a prompt with weak structural guidance about what good execution must establish;
+2. useful lessons from execution are easily lost or mixed into unstructured memory.
+
+Wisk addresses both.
+
+A work session starts from a typed `RunSpec`, creates an intentionally incomplete `LoopRun`, and progressively records readings, goals, decisions, evidence, checks, and an outcome. `okf-parser` validation makes missing contract state visible while the work is still happening.
+
+```text
+RunSpec
+  → LoopRun scaffold
+  → RunReading / RunGoal / RunDecision / RunEvidence / RunCheck
+  → RunOutcome
+  → Experience
+```
+
+That episodic evidence feeds the canonical three-role learning cycle:
+
+```text
+Skill creates/refines a candidate
+              ↓
+Experience executes real work and records what happened
+              ↓
+Wiki synthesizes and compares durable evidence
+              ↓
+Skill revisits the candidate and decides its lifecycle
+              └──────────────→ next Experience
+```
+
+The canonical roles are **Experience**, **Wiki**, and **Skill**. `SkillEvaluation` remains available as an optional explicit benchmark/review artifact when useful.
+
+See [RFC 0004](docs/rfc/0004-canonical-learning-cycle.md).
+
+## Standard profile
+
+`wisk init` installs an opinionated but replaceable standard profile.
+
+- **Experience** is ordinary useful work and is the on-demand fallback for an explicit `session start-next` call.
+- **Wiki** becomes eligible after three new Experiences and has higher priority than ordinary Experience.
+- **Skill** becomes eligible after six new Experiences. Wiki has higher priority, so synthesis runs before skill evolution when both are due.
+
+The default rhythm is roughly:
+
+```text
+Experience × 3 → Wiki
+Experience × 3 → Wiki → Skill
+repeat
+```
+
+Those thresholds are product defaults, not universal laws. Consumers can specialize SessionTypes, RunSpecs, context policies, and cadence without redefining the core learning roles.
+
+## Contract-guided execution
+
+The run artifact is not a report written after the work. It exists before substantive execution begins.
+
+```text
+create scaffold
+→ validate with okf-parser
+→ inspect the next unsatisfied requirement
+→ perform the next useful action
+→ record typed state and evidence
+→ validate again
+→ leave a coherent outcome or handoff
+```
+
+Core concepts include `RunSpec`, `LoopRun`, `RunReading`, `RunGoal`, `RunDecision`, `RunEvidence`, `RunCheck`, `RunOutcome`, and `Handoff`.
+
+Consumers specialize `RunSpec` rather than forcing domain rules into Wisk core. Software development, journalism, legal work, research, and other domains can require different readings, evidence, checks, and result states while sharing the same runtime.
+
+## Persistent learning
+
+- **`Experience`** — episodic evidence distilled from real execution.
+- **`WikiEntry`** — durable knowledge synthesized across experiences.
+- **`AgentSkill`** — reusable procedural guidance; active and experimental versions may coexist.
+- **`SkillProposal`** — explicit change record/rationale for procedural evolution.
+- **`SkillEvaluation`** — optional explicit benchmark or review record.
+
+Procedural state is reversible while evidence and durable knowledge are cumulative. A weak candidate skill can be rejected without losing the experience that showed why it failed.
+
+## CLI
+
+Important entry points include:
+
+```text
+wisk init [repository]
+wisk upgrade [repository]
+wisk context <task>
+wisk session next
+wisk session start-next <task>
+wisk start <task> [--session-type ...]
+wisk check <run>
+wisk run reading|goal|decision|evidence|check|outcome ...
+wisk experience preview|record ...
+wisk handoff list|create|continue ...
+wisk serve
+```
+
+## Python API
+
+```python
+from wisk import Wisk
+```
+
+## Architecture boundary
+
+```text
+okf-parser
+  ├── Markdown/frontmatter parsing
+  ├── concept identity and graph traversal
+  ├── Ibis / DuckDB / NetworkX integration
+  └── schema compilation and validation
+
+wisk
+  ├── RunSpec + live execution semantics
+  ├── SessionType + policy/cadence composition
+  ├── experience and knowledge consolidation
+  ├── skill evolution lifecycle
+  ├── consumer bootstrap + upgrade
+  └── CLI + FastMCP runtime
+```
+
+Wisk does not duplicate generic parsing or validation machinery from `okf-parser`.
+
+## Development and dogfooding
+
+Wisk develops itself through the same runtime. The repository's own `knowledge/` tree is a dogfood consumer with additional development-specific SessionTypes and policies.
+
+The canonical Experience/Wiki/Skill roles are deliberately policy-neutral so other repositories do not inherit Wisk's software-development assumptions.
+
+See [docs/architecture.md](docs/architecture.md) and [docs/dogfooding.md](docs/dogfooding.md).
+
+## Development setup
+
+```bash
+git clone https://github.com/franklinbaldo/wisk.git
+cd wisk
+uv sync
+uv run wisk info
+```
+
+## License
+
+MIT © Franklin Baldo

wisk-0.3.0/changelog/changes/agent-run-surfaces.md

@@ -0,0 +1,13 @@
+---
+type: Changelog
+version: 0.2.11
+date: 2026-09-06
+---
+
+# Agent-facing session and run surfaces
+
+- adds MCP tools for starting the next eligible session and recording every typed live-run component;
+- adds CLI `session next` / `session start-next` and `run reading|goal|decision|evidence|check|outcome` commands;
+- allows the core MCP and CLI context/start/check operations to target an explicit Wisk bundle path;
+- exposes `target_session_type` through CLI handoff creation;
+- keeps each mutation effect-explicit and delegates persistence to the validated Wisk runtime service layer.

wisk-0.3.0/changelog/changes/bootstrap-wisk.md

@@ -0,0 +1,9 @@
+---
+type: Changelog
+version: 0.1.0
+date: 2026-09-02
+---
+
+# Bootstrap do runtime Wisk sobre OKF
+
+- Inicializa o repositorio franklinbaldo/wisk e define especificacoes OKF.

wisk-0.3.0/changelog/changes/builtin-session-types.md

@@ -0,0 +1,14 @@
+---
+type: Changelog
+version: 0.2.7
+date: 2026-09-05
+---
+
+# Built-in Wisk session types
+
+- adds inference, wiki-maintainer, skill-evolver, and evaluator SessionTypes alongside development;
+- gives each built-in its own RunSpec and curated context policy;
+- keeps the inference session focused on active skills rather than injected wiki knowledge;
+- gives wiki maintenance access to experiences plus existing WikiEntry knowledge;
+- gives skill evolution both consolidated wiki knowledge and supporting experiences;
+- encourages pattern-shaped WikiEntry consolidation through prompt nudges without introducing a Pattern ontology type.

wisk-0.3.0/changelog/changes/check-next-action.md

@@ -0,0 +1,13 @@
+---
+type: Changelog
+version: 0.2.2
+date: 2026-09-05
+---
+
+# Actionable contract-guided checks
+
+- faz `Wisk.check_run()` devolver `next_action` derivado da primeira exigência tipada ainda não satisfeita;
+- preserva a ordem declarada pelo `RunSpec`, tornando a orientação determinística e diretamente ligada ao contrato da rodada;
+- devolve uma ação explícita `complete` quando a rodada satisfaz seu `RunSpec`;
+- preserva `unsatisfied` como diagnóstico completo e mantém CLI/MCP alinhados pela mesma resposta do runtime;
+- cobre o comportamento com contrato TDD para scaffold incompleto e rodada conforme.

wisk-0.3.0/changelog/changes/consumer-golden-path.md

@@ -0,0 +1,20 @@
+---
+type: Changelog
+version: 0.3.0
+date: 2026-09-06
+---
+
+# Consumer golden path
+
+- adds non-destructive `wisk init` for existing repositories;
+- installs managed normative specs, canonical Experience/Wiki/Skill contracts, and a standard consumer profile;
+- installs a managed `.wisk/.gitignore` so reproducible manifest/spec/system state does not pollute consumer diffs while local and learned state remains versionable;
+- preserves versioned consumer/runtime knowledge (`local`, `experiences`, `wiki`, `skills`) when a fresh clone runs `init`;
+- adds manifest-backed `wisk upgrade` with SHA-256 conflict detection and rollback-safe final writes;
+- makes explicit `session start-next` fall back to on-demand Experience while preserving automatic `session next` semantics;
+- autodiscovers `.wisk/knowledge` from the repository root in CLI commands;
+- packages normative and canonical bootstrap assets in the wheel;
+- makes scheduler selection prefer leaf SessionType specializations so consumer children replace managed defaults without priority tricks;
+- makes `RunSpec.parent_spec` operational: required readings, goals, evidence, and checks append into the effective pinned contract;
+- lets Handoffs targeting a parent SessionType activate compatible leaf specializations;
+- documents the canonical cross-session Experience → Wiki → Skill evaluation lifecycle and consumer/core responsibility boundary.

wisk-0.3.0/changelog/changes/contract-guided-start-check.md

@@ -0,0 +1,13 @@
+---
+type: Changelog
+version: 0.2.0
+date: 2026-09-05
+---
+
+# Contract-guided live runs
+
+- adiciona `Wisk.start_run()` e `Wisk.check_run()`;
+- expõe `wisk start` e `wisk check` no CLI;
+- expõe `wisk_start` e `wisk_check` no FastMCP;
+- combina validação estrutural do `okf-parser` com requisitos operacionais definidos por `RunSpec`;
+- adiciona testes para o ciclo scaffold incompleto → contrato satisfeito.

wisk-0.3.0/changelog/changes/experience-recording-phase1.md

@@ -0,0 +1,13 @@
+---
+type: Changelog
+version: 0.2.3
+date: 2026-09-05
+---
+
+# Experience Recording joins contract-guided execution
+
+- restores `preview_experience()` and `record_experience()` on top of the RunSpec/LoopRun runtime;
+- validates every persisted Experience with the normative OKF gate and rolls back invalid writes;
+- exposes `wisk experience preview|record` plus FastMCP preview/write tools;
+- lets an Experience reference the `LoopRun` that produced it, preserving execution-to-learning provenance;
+- preserves the original causal TDD history from PR #23 while reanchoring the implementation on the current runtime.

wisk-0.3.0/changelog/changes/handoff-runtime.md

@@ -0,0 +1,15 @@
+---
+type: Changelog
+version: 0.2.4
+date: 2026-09-05
+---
+
+# Cross-session Handoff runtime
+
+- adiciona `Handoff` como conceito OKF tipado para trabalho material deixado entre sessões;
+- separa `RunOutcome.result_state` de `work_status: complete | partial`;
+- exige Handoff ativo quando uma rodada declara trabalho parcial;
+- faz `context` e `start` exporem handoffs ativos e relevantes;
+- adiciona criação, listagem e continuação/arquivamento com provenance `created_by_run → continued_by_run`;
+- expõe o lifecycle na CLI e no FastMCP;
+- cobre o ciclo completo com testes de retomada entre duas `LoopRun`.