Skip to main content

Upgrade to SPOQ 1.1.1

SPOQ 1.1.1 is available on PyPI. Upgrade the package, then preview and confirm the database upgrade if your project still uses schema 1.

Install the published release

pipx upgrade spoq
# First installation:
pipx install spoq==1.1.1

SPOQ 1.1.1 corrects the PyPI Repository link to the public GitHub source. It preserves the 1.1.0 runtime; existing 1.1.0 workspaces need no additional schema conversion for this patch.

After the database step, initialization refreshes existing client registrations, seven SPOQ entry points and the collaboration helper while preserving custom configuration. Restart your coding client afterward. Optional semantic search now uses FastEmbed 0.9.1 or later and Pillow 13 or later. Run spoq reindex when prompted if the model revision changed.

Preview the database upgrade

spoq workflow upgrade --root /path/to/project --dry-run
# Review the preview and obtain confirmation before this step:
spoq workflow upgrade --root /path/to/project --yes
spoq init --upgrade --target /path/to/project

Existing 1.0 databases remain on schema 1 until you explicitly confirm. Existing work commands keep working there; workflow mutations require schema 2. The upgrade creates a consistent SQLite backup in .spoq/backups using the backup API, including committed WAL data. Fresh projects start with schema 2. Running init --upgrade first also detects schema 1 and offers this same backed-up upgrade prompt before refreshing skills; it does not bypass confirmation.

Old binaries reject schema 2. Stop all clients before restoring a verified schema 1 backup into a clean destination; installing an older package alone does not downgrade the database. Retain the backup and avoid a shared network-drive WAL database.

Choose the planning effort

Classic retains planning, planning validation, execution and implementation validation. Small, clear, low-impact, loosely coupled work uses its compact profile with the same gates. PIQARD (plan it quickly, AI records decisions) adds discovery, a narrative plan and optional design sources before a human review and task decomposition. Routing records its inputs and reasons; it records an effort band rather than predicting time or launching a model.

/spoq "Build a CSV importer with tests"
/spoq "Use PIQARD to plan the billing redesign"
/spoq-plan "Plan the importer only"
/spoq importer

Codex uses $spoq and the corresponding skill mentions. Planning-only stops before implementation. Discovery and design use /spoq-discover and /spoq-design; the four existing stage skills remain independently callable. Saved strategy definitions and routing stay pinned to the run.

Review one exact revision

A human response identifies the current review attempt, artifact ID and SHA-256. Rejection produces a new revision; approving an older artifact cannot approve the replacement. The local client attests to the user action. Peer messages, waiting time and model agreement are not approval, and no operating-system identity verification is claimed.

Loops have finite phase-attempt and transition budgets; waiting polls do not spend attempts and resume does not reset exhausted limits. Task implementation attempts also persist, with a default of three total. Changed goals require a proposed successor run with fresh routing and reviews.

Inspect progress locally

spoq workflow list --root /path/to/project
spoq workflow inspect RUN_ID --root /path/to/project
spoq ui --root /path/to/project --run RUN_ID --no-open

Open the printed loopback URL to view the strategy graph, work DAG, attempts, evidence and blockers. The bundled viewer is read-only and needs no Node runtime. A connected coding client performs the skills; the MCP server and viewer do not run a model or silently approve work.

Understand the evidence

Narrative plans, Mermaid diagrams and ERDs, algorithms, and typed formal records are reviewable sources. Formal states distinguish specified, tested, proven, disproven and unverified. A proven record requires supplied verifier details and proof; SPOQ does not execute a solver or independently establish the claim. Likewise, gates compute their verdict from recorded checks and reviewer scores, without re-running those checks on the server.

Historical pre-1.0 conversion

spoq migrate --root /path/to/project --dry-run
spoq init --upgrade --target /path/to/project
  • Maps → Project Plans; Epics → Features.
  • Tasks and journals → structured SQLite records in .spoq/spoq.db.

Original files remain intact. Preview the conversion before confirming it; original bytes, checksums and ZIP backups are retained. This legacy conversion is separate from schema 1 → 2. Resolve migration diagnostics before execution. Jira references may be stored, but SPOQ does not connect to Jira.

The published 1.0 verification covered historical client upgrades and local search. The 1.1 release adds installed-package, process-recovery and browser checks. Claude protocol and skill compatibility were checked without Claude inference; native Windows/macOS and a current remote CI/deployment run were not tested.

Quickstart · Published PyPI 1.1.1