Run the learning loop locally.

One-command literal demo

npx --yes --package=project-spine@0.10.0-beta.3 spine demo

This installs the exact npm beta, then creates a temporary Git fixture for the tenant-query case, verifies its historical correction, catches a reintroduced defect, and writes a local HTML report. It does not call a model or execute the fixture code.

GitHub Release asset · SHA-256 ff0d733988e87cd0ee75029eea4599fd214c171896a3a40862d89b87928770a1

Contributor source build

git clone --branch main https://github.com/PetriLahdelma/project-spine.git
cd project-spine
npm ci
npm run build
node dist/cli.js demo

Use the source path when you plan to modify or inspect the implementation. The command examples below use node dist/cli.js from this built checkout; an installed release exposes the equivalent spine command.

Run a case

# Import an explicit local case
node dist/cli.js learn --case ./failure.json

# Verify it against its recorded Git commits
node dist/cli.js replay <case-id>

# Check the current diff
node dist/cli.js guard --diff HEAD~1

# Ask for rules relevant to a file
node dist/cli.js context --files 'src/a.ts'

# Write a local report
node dist/cli.js report --format html --out report.html

Case shape

{
  "version": 1,
  "id": "tenant-query",
  "title": "Preserve the invoice tenant filter",
  "summary": "Review found an invoice query without the required tenant filter.",
  "source": { "kind": "manual" },
  "rules": [{
    "id": "tenant-filter",
    "description": "Keep the observed tenant filter on invoice queries.",
    "files": ["src/invoices.js"],
    "kind": "require-text",
    "text": "WHERE tenant_id = ?"
  }],
  "replay": { "brokenRef": "BROKEN_COMMIT_SHA", "fixedRef": "CORRECTED_COMMIT_SHA" }
}

Use commit identifiers that exist in the current repository. replay reads those Git objects without checking out either commit or modifying the worktree.

CI

- name: Check verified Project Spine rules
  run: node dist/cli.js guard --diff origin/main --json

Treat the JSON output and non-zero exit status as the integration contract. Keep evidence and verified rule files in version control so reviewers can see why a check exists.

Optional agent evaluation

node dist/cli.js evaluate tenant-query   --adapter adapter.json   --allow-execution   --runs 1   --json

Evaluation is separate from historical replay. It executes the configured adapter in temporary clones and requires explicit --allow-execution. There is no OS sandbox. The adapter may use the network, invoke a model, and incur provider costs. Review it before running.

Read docs/evaluation.md for the adapter contract and result format. Use replay when you only need deterministic, read-only verification against existing Git history.

Executable correction pilot

The correction pilot is a separate workflow for a user-reviewed, dependency-free JavaScript node:test that checks behavior a literal rule cannot express. It is available in the published beta for Linux and macOS with local Docker.

# Pre-pull and review the exact image digest first.
docker pull <image@sha256:digest>

# Synthetic behavioral preview using the same exact npm beta.
npx --yes   --package=project-spine@0.10.0-beta.3   spine correction demo   --image <image@sha256:digest>   --allow-execution

# Capture reviewed bytes and evidence. This does not execute code.
node dist/cli.js correction capture   --repo .   --id invoice-tenant-filter   --title "Preserve the invoice tenant filter"   --lesson "Keep invoice queries scoped to the current tenant"   --broken <broken-commit>   --fixed <fixed-commit>   --image <image@sha256:digest>   --test test/invoices.test.mjs   --files-json '["src/invoices.mjs"]'   --out correction.json

# Execute the recorded test under the declared controls.
node dist/cli.js correction verify   --case correction.json --repo . --allow-execution

# Recheck the current tree before returning verified guidance.
node dist/cli.js correction check   --case correction.json --repo . --allow-execution

# Read without execution. The output is labelled candidate.
node dist/cli.js correction context --case correction.json

Add --from-pr URL to capture when you want the reviewed case to point to pull-request evidence. Capture never runs the test. Verify and check require explicit execution consent and validate the digest-pinned container controls.

Read docs/corrections.md for the full pilot contract, or propose a public minimal case. Remove credentials, private data, and proprietary source before sharing.

Existing workflows

spine compile, spine drift check, templates, token inputs, and the local MCP server remain supported. Run node dist/cli.js --help for the exact command surface in your checkout.